# Create an Access Code
Source: https://docs.seam.co/api/access_codes/create

/openapi.json post /access_codes/create
Creates a new [access code](/low-level-apis/smart-locks/access-codes). For granting access, we recommend [Access Grants](/use-cases/granting-access) instead: they work across both standalone smart locks and access control systems and manage the underlying codes for you. Use this low-level endpoint only when you need direct control over a code on a single device, such as setting a custom PIN value.



# Create Multiple Linked Access Codes
Source: https://docs.seam.co/api/access_codes/create_multiple

/openapi.json post /access_codes/create_multiple
Creates new [access codes](/low-level-apis/smart-locks/access-codes) that share a common code across multiple devices.

Users with more than one door lock in a property may want to create groups of linked access codes, all of which have the same code (PIN). For example, a short-term rental host may want to provide guests the same PIN for both a front door lock and a back door lock.

If you specify a custom code, Seam assigns this custom code to each of the resulting access codes. However, in this case, Seam does not link these access codes together with a `common_code_key`. That is, `common_code_key` remains null for these access codes.

If you want to change these access codes that are not linked by a `common_code_key`, you cannot use `/access_codes/update_multiple`. However, you can update each of these access codes individually, using `/access_codes/update`.

See also [Creating and Updating Multiple Linked Access Codes](/low-level-apis/smart-locks/access-codes/creating-and-updating-multiple-linked-access-codes).

For granting a person access to a space, [Access Grants](/use-cases/granting-access) are the default and recommended approach and work across both standalone smart locks and access systems. Use the lower-level Access Codes API directly only when you specifically need to manage individual PIN codes.



# Delete an Access Code
Source: https://docs.seam.co/api/access_codes/delete

/openapi.json post /access_codes/delete
Deletes an [access code](/low-level-apis/smart-locks/access-codes).



# Access Code Errors and Warnings
Source: https://docs.seam.co/api/access_codes/errors

Errors and warnings that Seam reports on the Access Code resource, each with its code and meaning.

## Errors

Each error is an object with the following shape:

```json Example error theme={null}
{
  "error_code": "provider_issue",
  "message": "Indicates a provider-specific issue that prevents the access code from being set or managed. Check the error message for details.",
  "created_at": "2025-01-01T00:00:00.000Z",
  "is_access_code_error": true
}
```

<Accordion title="Error object properties">
  <ResponseField name="error_code" type="Enum (String)">
    Unique identifier of the type of error. Enables quick recognition and categorization of the issue.

    One of the error codes listed below.
  </ResponseField>

  <ResponseField name="message" type="String">
    Detailed description of the error. Provides insights into the issue and potentially how to rectify it.
  </ResponseField>

  <ResponseField name="created_at" type="String (ISO 8601)">
    Date and time at which Seam created the error.
  </ResponseField>

  <ResponseField name="change_type" type="Enum (String)">
    Indicates the type of external modification. `modified` means the code's PIN or schedule was changed. `removed` means the code was deleted from the device.
  </ResponseField>

  <ResponseField name="is_access_code_error" type="Boolean">
    Indicates that this is an access code error.
  </ResponseField>

  <ResponseField name="is_bridge_error" type="Boolean">
    Indicates whether the error is related to [Seam Bridge](/capability-guides/seam-bridge).
  </ResponseField>

  <ResponseField name="is_connected_account_error" type="Boolean">
    Indicates that the error is a [connected account](/api/connected_accounts/object) error.
  </ResponseField>

  <ResponseField name="is_device_error" type="Boolean">
    Indicates that the error is not a device error.
  </ResponseField>

  <ResponseField name="managed_access_code_id" type="String (UUID)">
    ID of the managed access code that conflicts with this managed access code, when Seam can identify it.
  </ResponseField>

  <ResponseField name="modified_fields" type="Array">
    List of fields that were changed externally, with their previous and new values.
  </ResponseField>

  <ResponseField name="unmanaged_access_code_id" type="String (UUID)">
    ID of the unmanaged access code that conflicts with this managed access code, when Seam can identify it.
  </ResponseField>
</Accordion>

### `access_code_inactive`

Indicates that the access code is disabled or inactive on the device. The code exists but will not grant access until re-enabled.

***

### `conflicting_external_modification`

Code was modified or removed externally after Seam successfully set it on the device. The external change conflicts with the state that Seam is trying to apply, so Seam will attempt to set the code on the device again.

***

### `duplicate_code_on_device`

Duplicate access code detected on device.

***

### `failed_to_remove_from_device`

Failed to remove code from device.

***

### `failed_to_set_on_device`

Failed to set code on device.

***

### `no_space_for_access_code_on_device`

No space for access code on device.

***

### `provider_issue`

Indicates a provider-specific issue that prevents the access code from being set or managed. Check the error message for details.

***

### Connected Account

<Note>
  These errors are inherited from the [Connected Account](/api/connected_accounts/errors) resource. When they are set on the parent connected account, they are propagated to this resource's errors list.
</Note>

#### `account_disconnected`

Indicates that the account is disconnected.

***

#### `bridge_disconnected`

Indicates that the Seam API cannot communicate with [Seam Bridge](/capability-guides/seam-bridge), for example, if the Seam Bridge executable has stopped or if the computer running the Seam Bridge executable is offline. See also [Troubleshooting Your Access Control System](/low-level-apis/access-systems/troubleshooting-your-access-control-system#acs_system-errors-seam_bridge_disconnected).

***

#### `dormakaba_sites_disconnected`

Indicates that one or more dormakaba sites associated with the connected account could not be connected. Contact dormakaba support.

***

#### `insufficient_permissions`

Indicates that Seam's integration user does not have sufficient permissions on the provider's system to which this device belongs, so Seam cannot manage access codes or unlock the device. See the error message for specifics, then either reauthorize the connected account in Seam or grant the integration user the required permissions in the provider's system.

***

#### `salto_ks_subscription_limit_exceeded`

Indicates that the Salto site user limit has been reached.

***

### Device

<Note>
  These errors are inherited from the [Device](/api/devices/errors) resource. When they are set on the parent device, they are propagated to this resource's errors list.
</Note>

#### `august_lock_not_authorized`

Indicates that the user is not authorized to use the August lock.

***

#### `device_disconnected`

Indicates that the device is disconnected.

***

#### `device_offline`

Indicates that the device is offline.

***

#### `device_removed`

Indicates that the device has been removed.

***

#### `hub_disconnected`

Indicates that the hub is disconnected.

***

#### `missing_device_credentials`

Indicates that device credentials are missing.

***

#### `subscription_required`

Indicates that a subscription is required to connect.

***

## Warnings

Each warning is an object with the following shape:

```json Example warning theme={null}
{
  "warning_code": "code_rotates_periodically",
  "message": "The access code's PIN rotates periodically when the code is renewed. Retrieve the latest code before each use.",
  "created_at": "2025-01-01T00:00:00.000Z"
}
```

<Accordion title="Warning object properties">
  <ResponseField name="warning_code" type="Enum (String)">
    Unique identifier of the type of warning. Enables quick recognition and categorization of the issue.

    One of the warning codes listed below.
  </ResponseField>

  <ResponseField name="message" type="String">
    Detailed description of the warning. Provides insights into the issue and potentially how to rectify it.
  </ResponseField>

  <ResponseField name="created_at" type="String (ISO 8601)">
    Date and time at which Seam created the warning.
  </ResponseField>

  <ResponseField name="change_type" type="Enum (String)">
    Indicates the type of external modification. `modified` means the code's PIN or schedule was changed. `removed` means the code was deleted from the device.
  </ResponseField>

  <ResponseField name="modified_fields" type="Array">
    List of fields that were changed externally, with their previous and new values.
  </ResponseField>
</Accordion>

### `being_deleted`

Access code is being deleted.

***

### `code_rotates_periodically`

The access code's PIN rotates periodically when the code is renewed. Retrieve the latest code before each use.

***

### `delay_in_removing_from_device`

Delay in removing code from device.

***

### `delay_in_setting_on_device`

Delay in setting code on device.

***

### `external_modification_in_effect`

Code was modified or removed externally after Seam successfully set it on the device. External modification is allowed for this code, so the externally modified state is being honored.

***

### `igloo_algopin_must_be_used_within_24_hours`

Algopins must be used within 24 hours.

***

### `management_transferred`

Management was transferred to another workspace.

***

### `third_party_integration_detected`

Third-party integration detected that may cause access codes to fail.

***

### `time_frame_adjusted_for_unknown_time_zone`

The device's time zone is unknown and this code's time frame crosses a daylight-saving transition in at least one plausible time zone. A 1-hour safety buffer has been applied to the side of the time frame affected by the transition (`ends_at` for spring-forward, `starts_at` for fall-back) so the code stays active through the shift — the code may be usable up to 1 hour beyond your requested window. Set the device's time zone via `/devices/report_provider_metadata` to clear the buffer and guarantee exact handling.

***

### `unknown_issue_with_access_code`

An unknown issue occurred with the access code.

***

### `using_backup_access_code`

A backup access code has been pulled and is being used in place of this access code.

***


# Access Code Events
Source: https://docs.seam.co/api/access_codes/events

Webhook events that Seam emits for the Access Code resource, with example payloads and properties.

## `access_code.created`

An [access code](/low-level-apis/smart-locks/access-codes) was created.

<ResponseExample>
  ```json Example webhook payload theme={null}
  {
    "access_code_id": "00000000-0000-0000-0000-000000000000",
    "connected_account_custom_metadata": {},
    "connected_account_id": "00000000-0000-0000-0000-000000000000",
    "created_at": "2025-01-01T00:00:00.000Z",
    "device_custom_metadata": {},
    "device_id": "00000000-0000-0000-0000-000000000000",
    "event_description": "An [access code](/low-level-apis/smart-locks/access-codes) was created.",
    "event_id": "00000000-0000-0000-0000-000000000000",
    "event_type": "access_code.created",
    "occurred_at": "2025-01-01T00:00:00.000Z",
    "workspace_id": "00000000-0000-0000-0000-000000000000"
  }
  ```
</ResponseExample>

<Accordion title="Properties">
  <ResponseField name="access_code_id" type="String (UUID)">
    ID of the affected access code.
  </ResponseField>

  <ResponseField name="connected_account_custom_metadata" type="Object">
    Custom metadata of the connected account, present when connected\_account\_id is provided.
  </ResponseField>

  <ResponseField name="connected_account_id" type="String (UUID)">
    ID of the connected account associated with the affected access code.
  </ResponseField>

  <ResponseField name="created_at" type="String (ISO 8601)">
    Date and time at which the event was created.
  </ResponseField>

  <ResponseField name="device_custom_metadata" type="Object">
    Custom metadata of the device, present when device\_id is provided.
  </ResponseField>

  <ResponseField name="device_id" type="String (UUID)">
    ID of the device associated with the affected access code.
  </ResponseField>

  <ResponseField name="event_description" type="String">
    Human-readable description of the event. Persisted when the event is created (so the creating code, including a provider, can supply a tailored description) and otherwise derived from the event.
  </ResponseField>

  <ResponseField name="event_id" type="String (UUID)">
    ID of the event.
  </ResponseField>

  <ResponseField name="event_type" type="Enum (String)">
    Value: `access_code.created`
  </ResponseField>

  <ResponseField name="occurred_at" type="String (ISO 8601)">
    Date and time at which the event occurred.
  </ResponseField>

  <ResponseField name="workspace_id" type="String (UUID)">
    ID of the workspace associated with the event.
  </ResponseField>
</Accordion>

## `access_code.changed`

An [access code](/low-level-apis/smart-locks/access-codes) was changed.

<ResponseExample>
  ```json Example webhook payload theme={null}
  {
    "access_code_id": "00000000-0000-0000-0000-000000000000",
    "change_reason": "",
    "changed_properties": [],
    "connected_account_custom_metadata": {},
    "connected_account_id": "00000000-0000-0000-0000-000000000000",
    "created_at": "2025-01-01T00:00:00.000Z",
    "device_custom_metadata": {},
    "device_id": "00000000-0000-0000-0000-000000000000",
    "event_description": "An [access code](/low-level-apis/smart-locks/access-codes) was changed.",
    "event_id": "00000000-0000-0000-0000-000000000000",
    "event_type": "access_code.changed",
    "occurred_at": "2025-01-01T00:00:00.000Z",
    "workspace_id": "00000000-0000-0000-0000-000000000000"
  }
  ```
</ResponseExample>

<Accordion title="Properties">
  <ResponseField name="access_code_id" type="String (UUID)">
    ID of the affected access code.
  </ResponseField>

  <ResponseField name="change_reason" type="String">
    Human-readable reason for the change (e.g. `ongoing code auto-renewed`).
  </ResponseField>

  <ResponseField name="changed_properties" type="Array">
    List of properties that changed on the access code.
  </ResponseField>

  <ResponseField name="connected_account_custom_metadata" type="Object">
    Custom metadata of the connected account, present when connected\_account\_id is provided.
  </ResponseField>

  <ResponseField name="connected_account_id" type="String (UUID)">
    ID of the connected account associated with the affected access code.
  </ResponseField>

  <ResponseField name="created_at" type="String (ISO 8601)">
    Date and time at which the event was created.
  </ResponseField>

  <ResponseField name="device_custom_metadata" type="Object">
    Custom metadata of the device, present when device\_id is provided.
  </ResponseField>

  <ResponseField name="device_id" type="String (UUID)">
    ID of the device associated with the affected access code.
  </ResponseField>

  <ResponseField name="event_description" type="String">
    Human-readable description of the event. Persisted when the event is created (so the creating code, including a provider, can supply a tailored description) and otherwise derived from the event.
  </ResponseField>

  <ResponseField name="event_id" type="String (UUID)">
    ID of the event.
  </ResponseField>

  <ResponseField name="event_type" type="Enum (String)">
    Value: `access_code.changed`
  </ResponseField>

  <ResponseField name="occurred_at" type="String (ISO 8601)">
    Date and time at which the event occurred.
  </ResponseField>

  <ResponseField name="workspace_id" type="String (UUID)">
    ID of the workspace associated with the event.
  </ResponseField>
</Accordion>

## `access_code.name_changed`

The name of an [access code](/low-level-apis/smart-locks/access-codes) was changed on the device.

<ResponseExample>
  ```json Example webhook payload theme={null}
  {
    "access_code_id": "00000000-0000-0000-0000-000000000000",
    "connected_account_custom_metadata": {},
    "connected_account_id": "00000000-0000-0000-0000-000000000000",
    "created_at": "2025-01-01T00:00:00.000Z",
    "description": "",
    "device_custom_metadata": {},
    "device_id": "00000000-0000-0000-0000-000000000000",
    "event_description": "The name of an [access code](/low-level-apis/smart-locks/access-codes) was changed on the device.",
    "event_id": "00000000-0000-0000-0000-000000000000",
    "event_type": "access_code.name_changed",
    "from": {
      "name": "My Access Code"
    },
    "occurred_at": "2025-01-01T00:00:00.000Z",
    "to": {
      "name": "My Access Code"
    },
    "workspace_id": "00000000-0000-0000-0000-000000000000"
  }
  ```
</ResponseExample>

<Accordion title="Properties">
  <ResponseField name="access_code_id" type="String (UUID)">
    ID of the affected access code.
  </ResponseField>

  <ResponseField name="connected_account_custom_metadata" type="Object">
    Custom metadata of the connected account, present when connected\_account\_id is provided.
  </ResponseField>

  <ResponseField name="connected_account_id" type="String (UUID)">
    ID of the connected account associated with the affected access code.
  </ResponseField>

  <ResponseField name="created_at" type="String (ISO 8601)">
    Date and time at which the event was created.
  </ResponseField>

  <ResponseField name="description" type="String">
    Human-readable description of the change and its source.
  </ResponseField>

  <ResponseField name="device_custom_metadata" type="Object">
    Custom metadata of the device, present when device\_id is provided.
  </ResponseField>

  <ResponseField name="device_id" type="String (UUID)">
    ID of the device associated with the affected access code.
  </ResponseField>

  <ResponseField name="event_description" type="String">
    Human-readable description of the event. Persisted when the event is created (so the creating code, including a provider, can supply a tailored description) and otherwise derived from the event.
  </ResponseField>

  <ResponseField name="event_id" type="String (UUID)">
    ID of the event.
  </ResponseField>

  <ResponseField name="event_type" type="Enum (String)">
    Value: `access_code.name_changed`
  </ResponseField>

  <ResponseField name="from" type="Object">
    Previous access code name configuration.

    <Expandable title="properties">
      <ResponseField name="name" type="String">
        Previous name of the access code.
      </ResponseField>
    </Expandable>
  </ResponseField>

  <ResponseField name="occurred_at" type="String (ISO 8601)">
    Date and time at which the event occurred.
  </ResponseField>

  <ResponseField name="to" type="Object">
    New access code name configuration.

    <Expandable title="properties">
      <ResponseField name="name" type="String">
        New name of the access code.
      </ResponseField>
    </Expandable>
  </ResponseField>

  <ResponseField name="workspace_id" type="String (UUID)">
    ID of the workspace associated with the event.
  </ResponseField>
</Accordion>

## `access_code.code_changed`

The pin code of an [access code](/low-level-apis/smart-locks/access-codes) was changed on the device.

<ResponseExample>
  ```json Example webhook payload theme={null}
  {
    "access_code_id": "00000000-0000-0000-0000-000000000000",
    "connected_account_custom_metadata": {},
    "connected_account_id": "00000000-0000-0000-0000-000000000000",
    "created_at": "2025-01-01T00:00:00.000Z",
    "description": "",
    "device_custom_metadata": {},
    "device_id": "00000000-0000-0000-0000-000000000000",
    "event_description": "The pin code of an [access code](/low-level-apis/smart-locks/access-codes) was changed on the device.",
    "event_id": "00000000-0000-0000-0000-000000000000",
    "event_type": "access_code.code_changed",
    "from": {
      "code": "1234"
    },
    "occurred_at": "2025-01-01T00:00:00.000Z",
    "to": {
      "code": "1234"
    },
    "workspace_id": "00000000-0000-0000-0000-000000000000"
  }
  ```
</ResponseExample>

<Accordion title="Properties">
  <ResponseField name="access_code_id" type="String (UUID)">
    ID of the affected access code.
  </ResponseField>

  <ResponseField name="connected_account_custom_metadata" type="Object">
    Custom metadata of the connected account, present when connected\_account\_id is provided.
  </ResponseField>

  <ResponseField name="connected_account_id" type="String (UUID)">
    ID of the connected account associated with the affected access code.
  </ResponseField>

  <ResponseField name="created_at" type="String (ISO 8601)">
    Date and time at which the event was created.
  </ResponseField>

  <ResponseField name="description" type="String">
    Human-readable description of the change and its source.
  </ResponseField>

  <ResponseField name="device_custom_metadata" type="Object">
    Custom metadata of the device, present when device\_id is provided.
  </ResponseField>

  <ResponseField name="device_id" type="String (UUID)">
    ID of the device associated with the affected access code.
  </ResponseField>

  <ResponseField name="event_description" type="String">
    Human-readable description of the event. Persisted when the event is created (so the creating code, including a provider, can supply a tailored description) and otherwise derived from the event.
  </ResponseField>

  <ResponseField name="event_id" type="String (UUID)">
    ID of the event.
  </ResponseField>

  <ResponseField name="event_type" type="Enum (String)">
    Value: `access_code.code_changed`
  </ResponseField>

  <ResponseField name="from" type="Object">
    Previous pin code configuration.

    <Expandable title="properties">
      <ResponseField name="code" type="String">
        Previous pin code.
      </ResponseField>
    </Expandable>
  </ResponseField>

  <ResponseField name="occurred_at" type="String (ISO 8601)">
    Date and time at which the event occurred.
  </ResponseField>

  <ResponseField name="to" type="Object">
    New pin code configuration.

    <Expandable title="properties">
      <ResponseField name="code" type="String">
        New pin code.
      </ResponseField>
    </Expandable>
  </ResponseField>

  <ResponseField name="workspace_id" type="String (UUID)">
    ID of the workspace associated with the event.
  </ResponseField>
</Accordion>

## `access_code.time_frame_changed`

The time frame of an [access code](/low-level-apis/smart-locks/access-codes) was changed on the device.

<ResponseExample>
  ```json Example webhook payload theme={null}
  {
    "access_code_id": "00000000-0000-0000-0000-000000000000",
    "connected_account_custom_metadata": {},
    "connected_account_id": "00000000-0000-0000-0000-000000000000",
    "created_at": "2025-01-01T00:00:00.000Z",
    "description": "",
    "device_custom_metadata": {},
    "device_id": "00000000-0000-0000-0000-000000000000",
    "event_description": "The time frame of an [access code](/low-level-apis/smart-locks/access-codes) was changed on the device.",
    "event_id": "00000000-0000-0000-0000-000000000000",
    "event_type": "access_code.time_frame_changed",
    "from": {
      "ends_at": "2025-01-01T00:00:00.000Z",
      "starts_at": "2025-01-01T00:00:00.000Z"
    },
    "occurred_at": "2025-01-01T00:00:00.000Z",
    "to": {
      "ends_at": "2025-01-01T00:00:00.000Z",
      "starts_at": "2025-01-01T00:00:00.000Z"
    },
    "workspace_id": "00000000-0000-0000-0000-000000000000"
  }
  ```
</ResponseExample>

<Accordion title="Properties">
  <ResponseField name="access_code_id" type="String (UUID)">
    ID of the affected access code.
  </ResponseField>

  <ResponseField name="connected_account_custom_metadata" type="Object">
    Custom metadata of the connected account, present when connected\_account\_id is provided.
  </ResponseField>

  <ResponseField name="connected_account_id" type="String (UUID)">
    ID of the connected account associated with the affected access code.
  </ResponseField>

  <ResponseField name="created_at" type="String (ISO 8601)">
    Date and time at which the event was created.
  </ResponseField>

  <ResponseField name="description" type="String">
    Human-readable description of the change and its source.
  </ResponseField>

  <ResponseField name="device_custom_metadata" type="Object">
    Custom metadata of the device, present when device\_id is provided.
  </ResponseField>

  <ResponseField name="device_id" type="String (UUID)">
    ID of the device associated with the affected access code.
  </ResponseField>

  <ResponseField name="event_description" type="String">
    Human-readable description of the event. Persisted when the event is created (so the creating code, including a provider, can supply a tailored description) and otherwise derived from the event.
  </ResponseField>

  <ResponseField name="event_id" type="String (UUID)">
    ID of the event.
  </ResponseField>

  <ResponseField name="event_type" type="Enum (String)">
    Value: `access_code.time_frame_changed`
  </ResponseField>

  <ResponseField name="from" type="Object">
    Previous time frame configuration.

    <Expandable title="properties">
      <ResponseField name="ends_at" type="String">
        Previous end time.
      </ResponseField>

      <ResponseField name="starts_at" type="String">
        Previous start time.
      </ResponseField>
    </Expandable>
  </ResponseField>

  <ResponseField name="occurred_at" type="String (ISO 8601)">
    Date and time at which the event occurred.
  </ResponseField>

  <ResponseField name="to" type="Object">
    New time frame configuration.

    <Expandable title="properties">
      <ResponseField name="ends_at" type="String">
        New end time.
      </ResponseField>

      <ResponseField name="starts_at" type="String">
        New start time.
      </ResponseField>
    </Expandable>
  </ResponseField>

  <ResponseField name="workspace_id" type="String (UUID)">
    ID of the workspace associated with the event.
  </ResponseField>
</Accordion>

## `access_code.mutations_requested`

Mutations were requested on an [access code](/low-level-apis/smart-locks/access-codes). This event fires at request time, before the change is confirmed on the device.

<ResponseExample>
  ```json Example webhook payload theme={null}
  {
    "access_code_id": "00000000-0000-0000-0000-000000000000",
    "connected_account_custom_metadata": {},
    "connected_account_id": "00000000-0000-0000-0000-000000000000",
    "created_at": "2025-01-01T00:00:00.000Z",
    "device_custom_metadata": {},
    "device_id": "00000000-0000-0000-0000-000000000000",
    "event_description": "Mutations were requested on an [access code](/low-level-apis/smart-locks/access-codes). This event fires at request time, before the change is confirmed on the device.",
    "event_id": "00000000-0000-0000-0000-000000000000",
    "event_type": "access_code.mutations_requested",
    "occurred_at": "2025-01-01T00:00:00.000Z",
    "requested_mutations": [],
    "workspace_id": "00000000-0000-0000-0000-000000000000"
  }
  ```
</ResponseExample>

<Accordion title="Properties">
  <ResponseField name="access_code_id" type="String (UUID)">
    ID of the affected access code.
  </ResponseField>

  <ResponseField name="connected_account_custom_metadata" type="Object">
    Custom metadata of the connected account, present when connected\_account\_id is provided.
  </ResponseField>

  <ResponseField name="connected_account_id" type="String (UUID)">
    ID of the connected account associated with the affected access code.
  </ResponseField>

  <ResponseField name="created_at" type="String (ISO 8601)">
    Date and time at which the event was created.
  </ResponseField>

  <ResponseField name="device_custom_metadata" type="Object">
    Custom metadata of the device, present when device\_id is provided.
  </ResponseField>

  <ResponseField name="device_id" type="String (UUID)">
    ID of the device associated with the affected access code.
  </ResponseField>

  <ResponseField name="event_description" type="String">
    Human-readable description of the event. Persisted when the event is created (so the creating code, including a provider, can supply a tailored description) and otherwise derived from the event.
  </ResponseField>

  <ResponseField name="event_id" type="String (UUID)">
    ID of the event.
  </ResponseField>

  <ResponseField name="event_type" type="Enum (String)">
    Value: `access_code.mutations_requested`
  </ResponseField>

  <ResponseField name="occurred_at" type="String (ISO 8601)">
    Date and time at which the event occurred.
  </ResponseField>

  <ResponseField name="requested_mutations" type="Array">
    Array of mutations requested on the access code, each containing the mutation type and from/to values.
  </ResponseField>

  <ResponseField name="workspace_id" type="String (UUID)">
    ID of the workspace associated with the event.
  </ResponseField>
</Accordion>

## `access_code.scheduled_on_device`

An [access code](/low-level-apis/smart-locks/access-codes) was [scheduled natively](/low-level-apis/smart-locks/access-codes#native-scheduling) on a device.

<ResponseExample>
  ```json Example webhook payload theme={null}
  {
    "access_code_id": "00000000-0000-0000-0000-000000000000",
    "code": "1234",
    "connected_account_custom_metadata": {},
    "connected_account_id": "00000000-0000-0000-0000-000000000000",
    "created_at": "2025-01-01T00:00:00.000Z",
    "device_custom_metadata": {},
    "device_id": "00000000-0000-0000-0000-000000000000",
    "event_description": "An [access code](/low-level-apis/smart-locks/access-codes) was [scheduled natively](/low-level-apis/smart-locks/access-codes#native-scheduling) on a device.",
    "event_id": "00000000-0000-0000-0000-000000000000",
    "event_type": "access_code.scheduled_on_device",
    "occurred_at": "2025-01-01T00:00:00.000Z",
    "workspace_id": "00000000-0000-0000-0000-000000000000"
  }
  ```
</ResponseExample>

<Accordion title="Properties">
  <ResponseField name="access_code_id" type="String (UUID)">
    ID of the affected access code.
  </ResponseField>

  <ResponseField name="code" type="String">
    Code for the affected access code.
  </ResponseField>

  <ResponseField name="connected_account_custom_metadata" type="Object">
    Custom metadata of the connected account, present when connected\_account\_id is provided.
  </ResponseField>

  <ResponseField name="connected_account_id" type="String (UUID)">
    ID of the connected account associated with the affected access code.
  </ResponseField>

  <ResponseField name="created_at" type="String (ISO 8601)">
    Date and time at which the event was created.
  </ResponseField>

  <ResponseField name="device_custom_metadata" type="Object">
    Custom metadata of the device, present when device\_id is provided.
  </ResponseField>

  <ResponseField name="device_id" type="String (UUID)">
    ID of the device associated with the affected access code.
  </ResponseField>

  <ResponseField name="event_description" type="String">
    Human-readable description of the event. Persisted when the event is created (so the creating code, including a provider, can supply a tailored description) and otherwise derived from the event.
  </ResponseField>

  <ResponseField name="event_id" type="String (UUID)">
    ID of the event.
  </ResponseField>

  <ResponseField name="event_type" type="Enum (String)">
    Value: `access_code.scheduled_on_device`
  </ResponseField>

  <ResponseField name="occurred_at" type="String (ISO 8601)">
    Date and time at which the event occurred.
  </ResponseField>

  <ResponseField name="workspace_id" type="String (UUID)">
    ID of the workspace associated with the event.
  </ResponseField>
</Accordion>

## `access_code.set_on_device`

An [access code](/low-level-apis/smart-locks/access-codes) was set on a device.

<ResponseExample>
  ```json Example webhook payload theme={null}
  {
    "access_code_id": "00000000-0000-0000-0000-000000000000",
    "code": "1234",
    "connected_account_custom_metadata": {},
    "connected_account_id": "00000000-0000-0000-0000-000000000000",
    "created_at": "2025-01-01T00:00:00.000Z",
    "device_custom_metadata": {},
    "device_id": "00000000-0000-0000-0000-000000000000",
    "event_description": "An [access code](/low-level-apis/smart-locks/access-codes) was set on a device.",
    "event_id": "00000000-0000-0000-0000-000000000000",
    "event_type": "access_code.set_on_device",
    "occurred_at": "2025-01-01T00:00:00.000Z",
    "workspace_id": "00000000-0000-0000-0000-000000000000"
  }
  ```
</ResponseExample>

<Accordion title="Properties">
  <ResponseField name="access_code_id" type="String (UUID)">
    ID of the affected access code.
  </ResponseField>

  <ResponseField name="code" type="String">
    Code for the affected access code.
  </ResponseField>

  <ResponseField name="connected_account_custom_metadata" type="Object">
    Custom metadata of the connected account, present when connected\_account\_id is provided.
  </ResponseField>

  <ResponseField name="connected_account_id" type="String (UUID)">
    ID of the connected account associated with the affected access code.
  </ResponseField>

  <ResponseField name="created_at" type="String (ISO 8601)">
    Date and time at which the event was created.
  </ResponseField>

  <ResponseField name="device_custom_metadata" type="Object">
    Custom metadata of the device, present when device\_id is provided.
  </ResponseField>

  <ResponseField name="device_id" type="String (UUID)">
    ID of the device associated with the affected access code.
  </ResponseField>

  <ResponseField name="event_description" type="String">
    Human-readable description of the event. Persisted when the event is created (so the creating code, including a provider, can supply a tailored description) and otherwise derived from the event.
  </ResponseField>

  <ResponseField name="event_id" type="String (UUID)">
    ID of the event.
  </ResponseField>

  <ResponseField name="event_type" type="Enum (String)">
    Value: `access_code.set_on_device`
  </ResponseField>

  <ResponseField name="occurred_at" type="String (ISO 8601)">
    Date and time at which the event occurred.
  </ResponseField>

  <ResponseField name="workspace_id" type="String (UUID)">
    ID of the workspace associated with the event.
  </ResponseField>
</Accordion>

## `access_code.removed_from_device`

An [access code](/low-level-apis/smart-locks/access-codes) was removed from a device.

<ResponseExample>
  ```json Example webhook payload theme={null}
  {
    "access_code_id": "00000000-0000-0000-0000-000000000000",
    "connected_account_custom_metadata": {},
    "connected_account_id": "00000000-0000-0000-0000-000000000000",
    "created_at": "2025-01-01T00:00:00.000Z",
    "device_custom_metadata": {},
    "device_id": "00000000-0000-0000-0000-000000000000",
    "event_description": "An [access code](/low-level-apis/smart-locks/access-codes) was removed from a device.",
    "event_id": "00000000-0000-0000-0000-000000000000",
    "event_type": "access_code.removed_from_device",
    "occurred_at": "2025-01-01T00:00:00.000Z",
    "workspace_id": "00000000-0000-0000-0000-000000000000"
  }
  ```
</ResponseExample>

<Accordion title="Properties">
  <ResponseField name="access_code_id" type="String (UUID)">
    ID of the affected access code.
  </ResponseField>

  <ResponseField name="connected_account_custom_metadata" type="Object">
    Custom metadata of the connected account, present when connected\_account\_id is provided.
  </ResponseField>

  <ResponseField name="connected_account_id" type="String (UUID)">
    ID of the connected account associated with the affected access code.
  </ResponseField>

  <ResponseField name="created_at" type="String (ISO 8601)">
    Date and time at which the event was created.
  </ResponseField>

  <ResponseField name="device_custom_metadata" type="Object">
    Custom metadata of the device, present when device\_id is provided.
  </ResponseField>

  <ResponseField name="device_id" type="String (UUID)">
    ID of the device associated with the affected access code.
  </ResponseField>

  <ResponseField name="event_description" type="String">
    Human-readable description of the event. Persisted when the event is created (so the creating code, including a provider, can supply a tailored description) and otherwise derived from the event.
  </ResponseField>

  <ResponseField name="event_id" type="String (UUID)">
    ID of the event.
  </ResponseField>

  <ResponseField name="event_type" type="Enum (String)">
    Value: `access_code.removed_from_device`
  </ResponseField>

  <ResponseField name="occurred_at" type="String (ISO 8601)">
    Date and time at which the event occurred.
  </ResponseField>

  <ResponseField name="workspace_id" type="String (UUID)">
    ID of the workspace associated with the event.
  </ResponseField>
</Accordion>

## `access_code.delay_in_setting_on_device`

There was an unusually long delay in setting an [access code](/low-level-apis/smart-locks/access-codes) on a device.

<ResponseExample>
  ```json Example webhook payload theme={null}
  {
    "access_code_errors": [],
    "access_code_id": "00000000-0000-0000-0000-000000000000",
    "access_code_warnings": [],
    "connected_account_custom_metadata": {},
    "connected_account_errors": [],
    "connected_account_id": "00000000-0000-0000-0000-000000000000",
    "connected_account_warnings": [],
    "created_at": "2025-01-01T00:00:00.000Z",
    "device_custom_metadata": {},
    "device_errors": [],
    "device_id": "00000000-0000-0000-0000-000000000000",
    "device_warnings": [],
    "event_description": "There was an unusually long delay in setting an [access code](/low-level-apis/smart-locks/access-codes) on a device.",
    "event_id": "00000000-0000-0000-0000-000000000000",
    "event_type": "access_code.delay_in_setting_on_device",
    "occurred_at": "2025-01-01T00:00:00.000Z",
    "workspace_id": "00000000-0000-0000-0000-000000000000"
  }
  ```
</ResponseExample>

<Accordion title="Properties">
  <ResponseField name="access_code_errors" type="Array">
    Errors associated with the access code.
  </ResponseField>

  <ResponseField name="access_code_id" type="String (UUID)">
    ID of the affected access code.
  </ResponseField>

  <ResponseField name="access_code_warnings" type="Array">
    Warnings associated with the access code.
  </ResponseField>

  <ResponseField name="connected_account_custom_metadata" type="Object">
    Custom metadata of the connected account, present when connected\_account\_id is provided.
  </ResponseField>

  <ResponseField name="connected_account_errors" type="Array">
    Errors associated with the connected account.
  </ResponseField>

  <ResponseField name="connected_account_id" type="String (UUID)">
    ID of the connected account associated with the affected access code.
  </ResponseField>

  <ResponseField name="connected_account_warnings" type="Array">
    Warnings associated with the connected account.
  </ResponseField>

  <ResponseField name="created_at" type="String (ISO 8601)">
    Date and time at which the event was created.
  </ResponseField>

  <ResponseField name="device_custom_metadata" type="Object">
    Custom metadata of the device, present when device\_id is provided.
  </ResponseField>

  <ResponseField name="device_errors" type="Array">
    Errors associated with the device.
  </ResponseField>

  <ResponseField name="device_id" type="String (UUID)">
    ID of the device associated with the affected access code.
  </ResponseField>

  <ResponseField name="device_warnings" type="Array">
    Warnings associated with the device.
  </ResponseField>

  <ResponseField name="event_description" type="String">
    Human-readable description of the event. Persisted when the event is created (so the creating code, including a provider, can supply a tailored description) and otherwise derived from the event.
  </ResponseField>

  <ResponseField name="event_id" type="String (UUID)">
    ID of the event.
  </ResponseField>

  <ResponseField name="event_type" type="Enum (String)">
    Value: `access_code.delay_in_setting_on_device`
  </ResponseField>

  <ResponseField name="occurred_at" type="String (ISO 8601)">
    Date and time at which the event occurred.
  </ResponseField>

  <ResponseField name="workspace_id" type="String (UUID)">
    ID of the workspace associated with the event.
  </ResponseField>
</Accordion>

## `access_code.failed_to_set_on_device`

An [access code](/low-level-apis/smart-locks/access-codes) failed to be set on a device.

<ResponseExample>
  ```json Example webhook payload theme={null}
  {
    "access_code_errors": [],
    "access_code_id": "00000000-0000-0000-0000-000000000000",
    "access_code_warnings": [],
    "connected_account_custom_metadata": {},
    "connected_account_errors": [],
    "connected_account_id": "00000000-0000-0000-0000-000000000000",
    "connected_account_warnings": [],
    "created_at": "2025-01-01T00:00:00.000Z",
    "device_custom_metadata": {},
    "device_errors": [],
    "device_id": "00000000-0000-0000-0000-000000000000",
    "device_warnings": [],
    "event_description": "An [access code](/low-level-apis/smart-locks/access-codes) failed to be set on a device.",
    "event_id": "00000000-0000-0000-0000-000000000000",
    "event_type": "access_code.failed_to_set_on_device",
    "occurred_at": "2025-01-01T00:00:00.000Z",
    "workspace_id": "00000000-0000-0000-0000-000000000000"
  }
  ```
</ResponseExample>

<Accordion title="Properties">
  <ResponseField name="access_code_errors" type="Array">
    Errors associated with the access code.
  </ResponseField>

  <ResponseField name="access_code_id" type="String (UUID)">
    ID of the affected access code.
  </ResponseField>

  <ResponseField name="access_code_warnings" type="Array">
    Warnings associated with the access code.
  </ResponseField>

  <ResponseField name="connected_account_custom_metadata" type="Object">
    Custom metadata of the connected account, present when connected\_account\_id is provided.
  </ResponseField>

  <ResponseField name="connected_account_errors" type="Array">
    Errors associated with the connected account.
  </ResponseField>

  <ResponseField name="connected_account_id" type="String (UUID)">
    ID of the connected account associated with the affected access code.
  </ResponseField>

  <ResponseField name="connected_account_warnings" type="Array">
    Warnings associated with the connected account.
  </ResponseField>

  <ResponseField name="created_at" type="String (ISO 8601)">
    Date and time at which the event was created.
  </ResponseField>

  <ResponseField name="device_custom_metadata" type="Object">
    Custom metadata of the device, present when device\_id is provided.
  </ResponseField>

  <ResponseField name="device_errors" type="Array">
    Errors associated with the device.
  </ResponseField>

  <ResponseField name="device_id" type="String (UUID)">
    ID of the device associated with the affected access code.
  </ResponseField>

  <ResponseField name="device_warnings" type="Array">
    Warnings associated with the device.
  </ResponseField>

  <ResponseField name="event_description" type="String">
    Human-readable description of the event. Persisted when the event is created (so the creating code, including a provider, can supply a tailored description) and otherwise derived from the event.
  </ResponseField>

  <ResponseField name="event_id" type="String (UUID)">
    ID of the event.
  </ResponseField>

  <ResponseField name="event_type" type="Enum (String)">
    Value: `access_code.failed_to_set_on_device`
  </ResponseField>

  <ResponseField name="occurred_at" type="String (ISO 8601)">
    Date and time at which the event occurred.
  </ResponseField>

  <ResponseField name="workspace_id" type="String (UUID)">
    ID of the workspace associated with the event.
  </ResponseField>
</Accordion>

## `access_code.deleted`

An [access code](/low-level-apis/smart-locks/access-codes) was deleted.

<ResponseExample>
  ```json Example webhook payload theme={null}
  {
    "access_code_id": "00000000-0000-0000-0000-000000000000",
    "code": "1234",
    "connected_account_custom_metadata": {},
    "connected_account_id": "00000000-0000-0000-0000-000000000000",
    "created_at": "2025-01-01T00:00:00.000Z",
    "device_custom_metadata": {},
    "device_id": "00000000-0000-0000-0000-000000000000",
    "event_description": "An [access code](/low-level-apis/smart-locks/access-codes) was deleted.",
    "event_id": "00000000-0000-0000-0000-000000000000",
    "event_type": "access_code.deleted",
    "occurred_at": "2025-01-01T00:00:00.000Z",
    "workspace_id": "00000000-0000-0000-0000-000000000000"
  }
  ```
</ResponseExample>

<Accordion title="Properties">
  <ResponseField name="access_code_id" type="String (UUID)">
    ID of the affected access code.
  </ResponseField>

  <ResponseField name="code" type="String">
    Code for the affected access code.
  </ResponseField>

  <ResponseField name="connected_account_custom_metadata" type="Object">
    Custom metadata of the connected account, present when connected\_account\_id is provided.
  </ResponseField>

  <ResponseField name="connected_account_id" type="String (UUID)">
    ID of the connected account associated with the affected access code.
  </ResponseField>

  <ResponseField name="created_at" type="String (ISO 8601)">
    Date and time at which the event was created.
  </ResponseField>

  <ResponseField name="device_custom_metadata" type="Object">
    Custom metadata of the device, present when device\_id is provided.
  </ResponseField>

  <ResponseField name="device_id" type="String (UUID)">
    ID of the device associated with the affected access code.
  </ResponseField>

  <ResponseField name="event_description" type="String">
    Human-readable description of the event. Persisted when the event is created (so the creating code, including a provider, can supply a tailored description) and otherwise derived from the event.
  </ResponseField>

  <ResponseField name="event_id" type="String (UUID)">
    ID of the event.
  </ResponseField>

  <ResponseField name="event_type" type="Enum (String)">
    Value: `access_code.deleted`
  </ResponseField>

  <ResponseField name="occurred_at" type="String (ISO 8601)">
    Date and time at which the event occurred.
  </ResponseField>

  <ResponseField name="workspace_id" type="String (UUID)">
    ID of the workspace associated with the event.
  </ResponseField>
</Accordion>

## `access_code.delay_in_removing_from_device`

There was an unusually long delay in removing an [access code](/low-level-apis/smart-locks/access-codes) from a device.

<ResponseExample>
  ```json Example webhook payload theme={null}
  {
    "access_code_errors": [],
    "access_code_id": "00000000-0000-0000-0000-000000000000",
    "access_code_warnings": [],
    "connected_account_custom_metadata": {},
    "connected_account_errors": [],
    "connected_account_id": "00000000-0000-0000-0000-000000000000",
    "connected_account_warnings": [],
    "created_at": "2025-01-01T00:00:00.000Z",
    "device_custom_metadata": {},
    "device_errors": [],
    "device_id": "00000000-0000-0000-0000-000000000000",
    "device_warnings": [],
    "event_description": "There was an unusually long delay in removing an [access code](/low-level-apis/smart-locks/access-codes) from a device.",
    "event_id": "00000000-0000-0000-0000-000000000000",
    "event_type": "access_code.delay_in_removing_from_device",
    "occurred_at": "2025-01-01T00:00:00.000Z",
    "workspace_id": "00000000-0000-0000-0000-000000000000"
  }
  ```
</ResponseExample>

<Accordion title="Properties">
  <ResponseField name="access_code_errors" type="Array">
    Errors associated with the access code.
  </ResponseField>

  <ResponseField name="access_code_id" type="String (UUID)">
    ID of the affected access code.
  </ResponseField>

  <ResponseField name="access_code_warnings" type="Array">
    Warnings associated with the access code.
  </ResponseField>

  <ResponseField name="connected_account_custom_metadata" type="Object">
    Custom metadata of the connected account, present when connected\_account\_id is provided.
  </ResponseField>

  <ResponseField name="connected_account_errors" type="Array">
    Errors associated with the connected account.
  </ResponseField>

  <ResponseField name="connected_account_id" type="String (UUID)">
    ID of the connected account associated with the affected access code.
  </ResponseField>

  <ResponseField name="connected_account_warnings" type="Array">
    Warnings associated with the connected account.
  </ResponseField>

  <ResponseField name="created_at" type="String (ISO 8601)">
    Date and time at which the event was created.
  </ResponseField>

  <ResponseField name="device_custom_metadata" type="Object">
    Custom metadata of the device, present when device\_id is provided.
  </ResponseField>

  <ResponseField name="device_errors" type="Array">
    Errors associated with the device.
  </ResponseField>

  <ResponseField name="device_id" type="String (UUID)">
    ID of the device associated with the affected access code.
  </ResponseField>

  <ResponseField name="device_warnings" type="Array">
    Warnings associated with the device.
  </ResponseField>

  <ResponseField name="event_description" type="String">
    Human-readable description of the event. Persisted when the event is created (so the creating code, including a provider, can supply a tailored description) and otherwise derived from the event.
  </ResponseField>

  <ResponseField name="event_id" type="String (UUID)">
    ID of the event.
  </ResponseField>

  <ResponseField name="event_type" type="Enum (String)">
    Value: `access_code.delay_in_removing_from_device`
  </ResponseField>

  <ResponseField name="occurred_at" type="String (ISO 8601)">
    Date and time at which the event occurred.
  </ResponseField>

  <ResponseField name="workspace_id" type="String (UUID)">
    ID of the workspace associated with the event.
  </ResponseField>
</Accordion>

## `access_code.failed_to_remove_from_device`

An [access code](/low-level-apis/smart-locks/access-codes) failed to be removed from a device.

<ResponseExample>
  ```json Example webhook payload theme={null}
  {
    "access_code_errors": [],
    "access_code_id": "00000000-0000-0000-0000-000000000000",
    "access_code_warnings": [],
    "connected_account_custom_metadata": {},
    "connected_account_errors": [],
    "connected_account_id": "00000000-0000-0000-0000-000000000000",
    "connected_account_warnings": [],
    "created_at": "2025-01-01T00:00:00.000Z",
    "device_custom_metadata": {},
    "device_errors": [],
    "device_id": "00000000-0000-0000-0000-000000000000",
    "device_warnings": [],
    "event_description": "An [access code](/low-level-apis/smart-locks/access-codes) failed to be removed from a device.",
    "event_id": "00000000-0000-0000-0000-000000000000",
    "event_type": "access_code.failed_to_remove_from_device",
    "occurred_at": "2025-01-01T00:00:00.000Z",
    "workspace_id": "00000000-0000-0000-0000-000000000000"
  }
  ```
</ResponseExample>

<Accordion title="Properties">
  <ResponseField name="access_code_errors" type="Array">
    Errors associated with the access code.
  </ResponseField>

  <ResponseField name="access_code_id" type="String (UUID)">
    ID of the affected access code.
  </ResponseField>

  <ResponseField name="access_code_warnings" type="Array">
    Warnings associated with the access code.
  </ResponseField>

  <ResponseField name="connected_account_custom_metadata" type="Object">
    Custom metadata of the connected account, present when connected\_account\_id is provided.
  </ResponseField>

  <ResponseField name="connected_account_errors" type="Array">
    Errors associated with the connected account.
  </ResponseField>

  <ResponseField name="connected_account_id" type="String (UUID)">
    ID of the connected account associated with the affected access code.
  </ResponseField>

  <ResponseField name="connected_account_warnings" type="Array">
    Warnings associated with the connected account.
  </ResponseField>

  <ResponseField name="created_at" type="String (ISO 8601)">
    Date and time at which the event was created.
  </ResponseField>

  <ResponseField name="device_custom_metadata" type="Object">
    Custom metadata of the device, present when device\_id is provided.
  </ResponseField>

  <ResponseField name="device_errors" type="Array">
    Errors associated with the device.
  </ResponseField>

  <ResponseField name="device_id" type="String (UUID)">
    ID of the device associated with the affected access code.
  </ResponseField>

  <ResponseField name="device_warnings" type="Array">
    Warnings associated with the device.
  </ResponseField>

  <ResponseField name="event_description" type="String">
    Human-readable description of the event. Persisted when the event is created (so the creating code, including a provider, can supply a tailored description) and otherwise derived from the event.
  </ResponseField>

  <ResponseField name="event_id" type="String (UUID)">
    ID of the event.
  </ResponseField>

  <ResponseField name="event_type" type="Enum (String)">
    Value: `access_code.failed_to_remove_from_device`
  </ResponseField>

  <ResponseField name="occurred_at" type="String (ISO 8601)">
    Date and time at which the event occurred.
  </ResponseField>

  <ResponseField name="workspace_id" type="String (UUID)">
    ID of the workspace associated with the event.
  </ResponseField>
</Accordion>

## `access_code.modified_external_to_seam`

An [access code](/low-level-apis/smart-locks/access-codes) was modified outside of Seam.

<ResponseExample>
  ```json Example webhook payload theme={null}
  {
    "access_code_id": "00000000-0000-0000-0000-000000000000",
    "connected_account_custom_metadata": {},
    "connected_account_id": "00000000-0000-0000-0000-000000000000",
    "created_at": "2025-01-01T00:00:00.000Z",
    "device_custom_metadata": {},
    "device_id": "00000000-0000-0000-0000-000000000000",
    "event_description": "An [access code](/low-level-apis/smart-locks/access-codes) was modified outside of Seam.",
    "event_id": "00000000-0000-0000-0000-000000000000",
    "event_type": "access_code.modified_external_to_seam",
    "occurred_at": "2025-01-01T00:00:00.000Z",
    "workspace_id": "00000000-0000-0000-0000-000000000000"
  }
  ```
</ResponseExample>

<Accordion title="Properties">
  <ResponseField name="access_code_id" type="String (UUID)">
    ID of the affected access code.
  </ResponseField>

  <ResponseField name="connected_account_custom_metadata" type="Object">
    Custom metadata of the connected account, present when connected\_account\_id is provided.
  </ResponseField>

  <ResponseField name="connected_account_id" type="String (UUID)">
    ID of the connected account associated with the affected access code.
  </ResponseField>

  <ResponseField name="created_at" type="String (ISO 8601)">
    Date and time at which the event was created.
  </ResponseField>

  <ResponseField name="device_custom_metadata" type="Object">
    Custom metadata of the device, present when device\_id is provided.
  </ResponseField>

  <ResponseField name="device_id" type="String (UUID)">
    ID of the device associated with the affected access code.
  </ResponseField>

  <ResponseField name="event_description" type="String">
    Human-readable description of the event. Persisted when the event is created (so the creating code, including a provider, can supply a tailored description) and otherwise derived from the event.
  </ResponseField>

  <ResponseField name="event_id" type="String (UUID)">
    ID of the event.
  </ResponseField>

  <ResponseField name="event_type" type="Enum (String)">
    Value: `access_code.modified_external_to_seam`
  </ResponseField>

  <ResponseField name="occurred_at" type="String (ISO 8601)">
    Date and time at which the event occurred.
  </ResponseField>

  <ResponseField name="workspace_id" type="String (UUID)">
    ID of the workspace associated with the event.
  </ResponseField>
</Accordion>

## `access_code.deleted_external_to_seam`

An [access code](/low-level-apis/smart-locks/access-codes) was deleted outside of Seam.

<ResponseExample>
  ```json Example webhook payload theme={null}
  {
    "access_code_id": "00000000-0000-0000-0000-000000000000",
    "connected_account_custom_metadata": {},
    "connected_account_id": "00000000-0000-0000-0000-000000000000",
    "created_at": "2025-01-01T00:00:00.000Z",
    "device_custom_metadata": {},
    "device_id": "00000000-0000-0000-0000-000000000000",
    "event_description": "An [access code](/low-level-apis/smart-locks/access-codes) was deleted outside of Seam.",
    "event_id": "00000000-0000-0000-0000-000000000000",
    "event_type": "access_code.deleted_external_to_seam",
    "occurred_at": "2025-01-01T00:00:00.000Z",
    "workspace_id": "00000000-0000-0000-0000-000000000000"
  }
  ```
</ResponseExample>

<Accordion title="Properties">
  <ResponseField name="access_code_id" type="String (UUID)">
    ID of the affected access code.
  </ResponseField>

  <ResponseField name="connected_account_custom_metadata" type="Object">
    Custom metadata of the connected account, present when connected\_account\_id is provided.
  </ResponseField>

  <ResponseField name="connected_account_id" type="String (UUID)">
    ID of the connected account associated with the affected access code.
  </ResponseField>

  <ResponseField name="created_at" type="String (ISO 8601)">
    Date and time at which the event was created.
  </ResponseField>

  <ResponseField name="device_custom_metadata" type="Object">
    Custom metadata of the device, present when device\_id is provided.
  </ResponseField>

  <ResponseField name="device_id" type="String (UUID)">
    ID of the device associated with the affected access code.
  </ResponseField>

  <ResponseField name="event_description" type="String">
    Human-readable description of the event. Persisted when the event is created (so the creating code, including a provider, can supply a tailored description) and otherwise derived from the event.
  </ResponseField>

  <ResponseField name="event_id" type="String (UUID)">
    ID of the event.
  </ResponseField>

  <ResponseField name="event_type" type="Enum (String)">
    Value: `access_code.deleted_external_to_seam`
  </ResponseField>

  <ResponseField name="occurred_at" type="String (ISO 8601)">
    Date and time at which the event occurred.
  </ResponseField>

  <ResponseField name="workspace_id" type="String (UUID)">
    ID of the workspace associated with the event.
  </ResponseField>
</Accordion>

## `access_code.backup_access_code_pulled`

A [backup access code](/low-level-apis/smart-locks/access-codes/backup-access-codes) was pulled from the backup access code pool and set on a device.

<ResponseExample>
  ```json Example webhook payload theme={null}
  {
    "access_code_id": "00000000-0000-0000-0000-000000000000",
    "backup_access_code_id": "",
    "connected_account_custom_metadata": {},
    "connected_account_id": "00000000-0000-0000-0000-000000000000",
    "created_at": "2025-01-01T00:00:00.000Z",
    "device_custom_metadata": {},
    "device_id": "00000000-0000-0000-0000-000000000000",
    "event_description": "A [backup access code](/low-level-apis/smart-locks/access-codes/backup-access-codes) was pulled from the backup access code pool and set on a device.",
    "event_id": "00000000-0000-0000-0000-000000000000",
    "event_type": "access_code.backup_access_code_pulled",
    "occurred_at": "2025-01-01T00:00:00.000Z",
    "workspace_id": "00000000-0000-0000-0000-000000000000"
  }
  ```
</ResponseExample>

<Accordion title="Properties">
  <ResponseField name="access_code_id" type="String (UUID)">
    ID of the affected access code.
  </ResponseField>

  <ResponseField name="backup_access_code_id" type="String">
    ID of the backup access code that was pulled from the pool.
  </ResponseField>

  <ResponseField name="connected_account_custom_metadata" type="Object">
    Custom metadata of the connected account, present when connected\_account\_id is provided.
  </ResponseField>

  <ResponseField name="connected_account_id" type="String (UUID)">
    ID of the connected account associated with the affected access code.
  </ResponseField>

  <ResponseField name="created_at" type="String (ISO 8601)">
    Date and time at which the event was created.
  </ResponseField>

  <ResponseField name="device_custom_metadata" type="Object">
    Custom metadata of the device, present when device\_id is provided.
  </ResponseField>

  <ResponseField name="device_id" type="String (UUID)">
    ID of the device associated with the affected access code.
  </ResponseField>

  <ResponseField name="event_description" type="String">
    Human-readable description of the event. Persisted when the event is created (so the creating code, including a provider, can supply a tailored description) and otherwise derived from the event.
  </ResponseField>

  <ResponseField name="event_id" type="String (UUID)">
    ID of the event.
  </ResponseField>

  <ResponseField name="event_type" type="Enum (String)">
    Value: `access_code.backup_access_code_pulled`
  </ResponseField>

  <ResponseField name="occurred_at" type="String (ISO 8601)">
    Date and time at which the event occurred.
  </ResponseField>

  <ResponseField name="workspace_id" type="String (UUID)">
    ID of the workspace associated with the event.
  </ResponseField>
</Accordion>


# Generate a Code
Source: https://docs.seam.co/api/access_codes/generate_code

/openapi.json post /access_codes/generate_code
Generates a code for an [access code](/low-level-apis/smart-locks/access-codes), given a device ID.



# Get an Access Code
Source: https://docs.seam.co/api/access_codes/get

/openapi.json post /access_codes/get
Returns a specified [access code](/low-level-apis/smart-locks/access-codes).

You must specify either `access_code_id` or both `device_id` and `code`.

You must include at least one request parameter.



# List Access Codes
Source: https://docs.seam.co/api/access_codes/list

/openapi.json post /access_codes/list
Returns a list of all [access codes](/low-level-apis/smart-locks/access-codes).

Specify `device_id`, `access_code_ids`, `access_method_id`, `access_grant_id`, or `access_grant_key`.

You must include at least one request parameter.



# The Access Code Object
Source: https://docs.seam.co/api/access_codes/object

Learn how the access_code object represents a smart lock PIN code you can customize, track, and program across hundreds of supported keypad and pinpad locks.

## The access\_code Object

Represents a smart lock [access code](/low-level-apis/smart-locks/access-codes).

An access code is a code used for a keypad or pinpad device. Unlike physical keys, which can easily be lost or duplicated, PIN codes can be customized, tracked, and altered on the fly. Using the Seam Access Code API, you can easily generate access codes on the hundreds of door lock models with which we integrate.

Seam supports programming two types of access codes: [ongoing](/low-level-apis/smart-locks/access-codes#ongoing-access-codes) and [time-bound](/low-level-apis/smart-locks/access-codes#time-bound-access-codes). To differentiate between the two, refer to the `type` property of the access code. Ongoing codes display as `ongoing`, whereas time-bound codes are labeled `time_bound`. An ongoing access code is active, until it has been removed from the device. To specify an ongoing access code, leave both `starts_at` and `ends_at` empty. A time-bound access code will be programmed at the `starts_at` time and removed at the `ends_at` time.

In addition, for certain devices, Seam also supports [offline access codes](/low-level-apis/smart-locks/access-codes#offline-access-codes). Offline access (PIN) codes are designed for door locks that might not always maintain an internet connection. For this type of access code, the device manufacturer uses encryption keys (tokens) to create server-based registries of algorithmically-generated offline PIN codes. Because the tokens remain synchronized with the managed devices, the locks do not require an active internet connection—and you do not need to be near the locks—to create an offline access code. Then, owners or managers can share these offline codes with users through a variety of mechanisms, such as messaging applications. That is, lock users do not need to install a smartphone application to receive an offline access code.

For granting a person access to a space, [Access Grants](/use-cases/granting-access) are the default and recommended approach and work across both standalone smart locks and access systems. Use the lower-level Access Codes API directly only when you specifically need to manage individual PIN codes.

<ResponseExample>
  ```json One-Time-Use Offline Access Code theme={null}
  {
    "access_code_id": "e9cf6dd6-89aa-477f-a701-c08f3de13c1f",
    "code": "1234",
    "common_code_key": null,
    "created_at": "2025-06-14T16:54:17.946242Z",
    "device_id": "c9cd621d-ef0c-45c8-b608-026ebdb74615",
    "ends_at": "2025-07-04T16:54:17.946049Z",
    "errors": [],
    "pending_mutations": [],
    "is_backup": false,
    "is_backup_access_code_available": false,
    "is_external_modification_allowed": false,
    "is_managed": true,
    "is_offline_access_code": true,
    "is_one_time_use": true,
    "is_scheduled_on_device": true,
    "is_waiting_for_code_assignment": false,
    "name": "My Access Code",
    "pulled_backup_access_code_id": null,
    "starts_at": "2025-07-02T16:54:17.946049Z",
    "status": "set",
    "type": "time_bound",
    "warnings": [],
    "workspace_id": "750fc0bc-4450-4356-8d9f-18c6a3a6b2c7"
  }
  ```

  ```json Ongoing Online Access Code theme={null}
  {
    "access_code_id": "e9cf6dd6-89aa-477f-a701-c08f3de13c1f",
    "code": "1234",
    "common_code_key": "auto_set_by_create_multiple_550e8400-e29b-41d4-a716-446655440000",
    "created_at": "2025-06-14T16:54:17.946242Z",
    "device_id": "c9cd621d-ef0c-45c8-b608-026ebdb74615",
    "ends_at": null,
    "errors": [],
    "pending_mutations": [],
    "is_backup": false,
    "is_backup_access_code_available": true,
    "is_external_modification_allowed": true,
    "is_managed": true,
    "is_offline_access_code": false,
    "is_one_time_use": false,
    "is_scheduled_on_device": true,
    "is_waiting_for_code_assignment": false,
    "name": "My Access Code",
    "pulled_backup_access_code_id": null,
    "starts_at": null,
    "status": "set",
    "type": "ongoing",
    "warnings": [],
    "workspace_id": "750fc0bc-4450-4356-8d9f-18c6a3a6b2c7"
  }
  ```

  ```json Time-bound Online Access Code theme={null}
  {
    "access_code_id": "e9cf6dd6-89aa-477f-a701-c08f3de13c1f",
    "code": "1234",
    "common_code_key": "auto_set_by_create_multiple_550e8400-e29b-41d4-a716-446655440000",
    "created_at": "2025-06-14T16:54:17.946242Z",
    "device_id": "c9cd621d-ef0c-45c8-b608-026ebdb74615",
    "ends_at": "2025-07-04T16:54:17.946049Z",
    "errors": [],
    "pending_mutations": [],
    "is_backup": false,
    "is_backup_access_code_available": true,
    "is_external_modification_allowed": true,
    "is_managed": true,
    "is_offline_access_code": false,
    "is_one_time_use": false,
    "is_scheduled_on_device": true,
    "is_waiting_for_code_assignment": false,
    "name": "My Access Code",
    "pulled_backup_access_code_id": null,
    "starts_at": "2025-07-02T16:54:17.946049Z",
    "status": "set",
    "type": "time_bound",
    "warnings": [],
    "workspace_id": "750fc0bc-4450-4356-8d9f-18c6a3a6b2c7"
  }
  ```

  ```json Time-bound Offline Access Code theme={null}
  {
    "access_code_id": "e9cf6dd6-89aa-477f-a701-c08f3de13c1f",
    "code": "1234",
    "common_code_key": null,
    "created_at": "2025-06-14T16:54:17.946242Z",
    "device_id": "c9cd621d-ef0c-45c8-b608-026ebdb74615",
    "ends_at": "2025-07-04T16:54:17.946049Z",
    "errors": [],
    "pending_mutations": [],
    "is_backup": false,
    "is_backup_access_code_available": false,
    "is_external_modification_allowed": false,
    "is_managed": true,
    "is_offline_access_code": true,
    "is_one_time_use": false,
    "is_scheduled_on_device": true,
    "is_waiting_for_code_assignment": false,
    "name": "My Access Code",
    "pulled_backup_access_code_id": null,
    "starts_at": "2025-07-02T16:54:17.946049Z",
    "status": "set",
    "type": "time_bound",
    "warnings": [],
    "workspace_id": "750fc0bc-4450-4356-8d9f-18c6a3a6b2c7"
  }
  ```
</ResponseExample>

***

## Properties

<ResponseField name="access_code_id" type="String (UUID)">
  Unique identifier for the access code.
</ResponseField>

<ResponseField name="code" type="String">
  Code used for access. Typically, a numeric or alphanumeric string.
</ResponseField>

<ResponseField name="common_code_key" type="String">
  Unique identifier for a group of access codes that share the same code.
</ResponseField>

<ResponseField name="created_at" type="String (ISO 8601)">
  Date and time at which the access code was created.
</ResponseField>

<ResponseField name="device_id" type="String (UUID)">
  Unique identifier for the device associated with the access code.
</ResponseField>

<ResponseField name="dormakaba_oracode_metadata" type="Object">
  Metadata for a dormakaba Oracode managed access code. Only present for access codes from dormakaba Oracode devices.

  <Expandable title="properties">
    <ResponseField name="is_cancellable" type="Boolean">
      Indicates whether the stay can be cancelled via the Dormakaba Oracode API.
    </ResponseField>

    <ResponseField name="is_early_checkin_able" type="Boolean">
      Indicates whether early check-in is available for this stay.
    </ResponseField>

    <ResponseField name="is_extendable" type="Boolean">
      Indicates whether the stay can be extended via the Dormakaba Oracode API.
    </ResponseField>

    <ResponseField name="is_overridable" type="Boolean">
      Indicates whether the access code can be overridden. When false, the maximum number of overrides has been reached.
    </ResponseField>

    <ResponseField name="site_name" type="String">
      Dormakaba Oracode site name associated with this access code.
    </ResponseField>

    <ResponseField name="stay_id" type="number">
      Dormakaba Oracode stay ID associated with this access code.
    </ResponseField>

    <ResponseField name="user_level_id" type="String">
      Dormakaba Oracode user level ID associated with this access code.
    </ResponseField>

    <ResponseField name="user_level_name" type="String">
      Dormakaba Oracode user level name associated with this access code.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="ends_at" type="String (ISO 8601)">
  Date and time after which the time-bound access code becomes inactive.
</ResponseField>

<ResponseField name="errors" type="Array">
  Errors associated with the [access code](/low-level-apis/smart-locks/access-codes).
</ResponseField>

<ResponseField name="is_backup" type="Boolean">
  Indicates whether the access code is a backup code.
</ResponseField>

<ResponseField name="is_backup_access_code_available" type="Boolean">
  Indicates whether a backup access code is available for use if the primary access code is lost or compromised.
</ResponseField>

<ResponseField name="is_external_modification_allowed" type="Boolean">
  Indicates whether changes to the access code from external sources are permitted.
</ResponseField>

<ResponseField name="is_managed" type="Boolean">
  Indicates whether Seam manages the access code.
</ResponseField>

<ResponseField name="is_offline_access_code" type="Boolean">
  Indicates 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.
</ResponseField>

<ResponseField name="is_one_time_use" type="Boolean">
  Indicates whether the access code can only be used once. If `true`, the code becomes invalid after the first use.
</ResponseField>

<ResponseField name="is_scheduled_on_device" type="Boolean">
  Indicates whether the code is set on the device according to a preconfigured schedule.
</ResponseField>

<ResponseField name="is_waiting_for_code_assignment" type="Boolean">
  Indicates whether the access code is waiting for a code assignment.
</ResponseField>

<ResponseField name="name" type="String">
  Name of the access code. Enables administrators and users to identify the access code easily, especially when there are numerous access codes. Note that the name provided on Seam is used to identify the code on Seam and is not necessarily the name that will appear in 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`. To provide a consistent experience, Seam identifies 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 to meet provider constraints. To help your 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).
</ResponseField>

<ResponseField name="pending_mutations" type="Array">
  Collection of pending mutations for the access code. Indicates changes that Seam is in the process of pushing to the device.
</ResponseField>

<ResponseField name="pulled_backup_access_code_id" type="String (UUID)">
  Identifier of the pulled backup access code. Used to associate the pulled backup access code with the original access code.
</ResponseField>

<ResponseField name="starts_at" type="String (ISO 8601)">
  Date and time at which the time-bound access code becomes active.
</ResponseField>

<ResponseField name="status" type="Enum (String)">
  Current status of the access code within the operational lifecycle. Values are `setting`, a transitional phase that indicates that the code is being configured or activated; `set`, which indicates that the code is active and operational; `unset`, which indicates a deactivated or unused state, either before activation or after deliberate deactivation; `removing`, which indicates a transitional period in which the code is being deleted or made inactive; and `unknown`, which indicates an indeterminate state, due to reasons such as system errors or incomplete data, that highlights a potential need for system review or troubleshooting. See also [Lifecycle of Access Codes](/low-level-apis/smart-locks/access-codes/lifecycle-of-access-codes).
</ResponseField>

<ResponseField name="type" type="Enum (String)">
  Type of the access code. `ongoing` access codes are active continuously until deactivated manually. `time_bound` access codes have a specific duration.
</ResponseField>

<ResponseField name="warnings" type="Array">
  Warnings associated with the [access code](/low-level-apis/smart-locks/access-codes).
</ResponseField>

<ResponseField name="workspace_id" type="String (UUID)">
  Unique identifier for the Seam workspace associated with the access code.
</ResponseField>


# Pull a Backup Access Code
Source: https://docs.seam.co/api/access_codes/pull_backup_access_code

/openapi.json post /access_codes/pull_backup_access_code
Retrieves a backup access code for an [access code](/low-level-apis/smart-locks/access-codes). See also [Managing Backup Access Codes](/low-level-apis/smart-locks/access-codes/backup-access-codes).

A backup access code pool is a collection of pre-programmed access codes stored on a device, ready for use. These codes are programmed in addition to the regular access codes on Seam, serving as a safety net for any issues with the primary codes. If there's ever a complication with a primary access code—be it due to intermittent connectivity, manual removal from a device, or provider outages—a backup code can be retrieved. Its end time can then be adjusted to align with the original code, facilitating seamless and uninterrupted access.

You can pull a backup access code from the pool at any time. These backup codes are guaranteed to work immediately and automatically programmed to be removed from the device after the access code ends.

You can only pull backup access codes for time-bound access codes.

Before pulling a backup access code, make sure that the device's `properties.supports_backup_access_code_pool` is `true`. Then, to activate the backup pool, set `use_backup_access_code_pool` to `true` when creating an access code.



# Report Device Access Code Constraints
Source: https://docs.seam.co/api/access_codes/report_device_constraints

/openapi.json post /access_codes/report_device_constraints
Enables you to report access code-related constraints for a device. Currently, supports reporting supported code length constraints for SmartThings devices.

Specify either `supported_code_lengths` or `min_code_length`/`max_code_length`.



# Simulate Creating an Unmanaged Access Code
Source: https://docs.seam.co/api/access_codes/simulate/create_unmanaged_access_code

/openapi.json post /access_codes/simulate/create_unmanaged_access_code
Simulates the creation of an [unmanaged access code](/low-level-apis/smart-locks/access-codes/migrating-existing-access-codes) in a [sandbox workspace](/core-concepts/workspaces#sandbox-workspaces).



# Convert an Unmanaged Access Code
Source: https://docs.seam.co/api/access_codes/unmanaged/convert_to_managed

/openapi.json post /access_codes/unmanaged/convert_to_managed
Converts an [unmanaged access code](/low-level-apis/smart-locks/access-codes/migrating-existing-access-codes) to an [access code managed through Seam](/low-level-apis/smart-locks/access-codes).

An unmanaged access code has a limited set of operations that you can perform on it. Once you convert an unmanaged access code to a managed access code, the full set of access code operations and lifecycle events becomes available for it.

Note that not all device providers support converting an unmanaged access code to a managed access code.



# Delete an Unmanaged Access Code
Source: https://docs.seam.co/api/access_codes/unmanaged/delete

/openapi.json post /access_codes/unmanaged/delete
Deletes an [unmanaged access code](/low-level-apis/smart-locks/access-codes/migrating-existing-access-codes).



# Unmanaged Access Codes Errors and Warnings
Source: https://docs.seam.co/api/access_codes/unmanaged/errors

Errors and warnings that Seam reports on the Unmanaged Access Codes resource, each with its code and meaning.

## Errors

Each error is an object with the following shape:

```json Example error theme={null}
{
  "error_code": "provider_issue",
  "message": "Indicates a provider-specific issue that prevents the access code from being set or managed. Check the error message for details.",
  "created_at": "2025-01-01T00:00:00.000Z",
  "is_access_code_error": true
}
```

<Accordion title="Error object properties">
  <ResponseField name="error_code" type="Enum (String)">
    Unique identifier of the type of error. Enables quick recognition and categorization of the issue.

    One of the error codes listed below.
  </ResponseField>

  <ResponseField name="message" type="String">
    Detailed description of the error. Provides insights into the issue and potentially how to rectify it.
  </ResponseField>

  <ResponseField name="created_at" type="String (ISO 8601)">
    Date and time at which Seam created the error.
  </ResponseField>

  <ResponseField name="change_type" type="Enum (String)">
    Indicates the type of external modification. `modified` means the code's PIN or schedule was changed. `removed` means the code was deleted from the device.
  </ResponseField>

  <ResponseField name="is_access_code_error" type="Boolean">
    Indicates that this is an access code error.
  </ResponseField>

  <ResponseField name="is_bridge_error" type="Boolean">
    Indicates whether the error is related to [Seam Bridge](/capability-guides/seam-bridge).
  </ResponseField>

  <ResponseField name="is_connected_account_error" type="Boolean">
    Indicates that the error is a [connected account](/api/connected_accounts/object) error.
  </ResponseField>

  <ResponseField name="is_device_error" type="Boolean">
    Indicates that the error is not a device error.
  </ResponseField>

  <ResponseField name="managed_access_code_id" type="String (UUID)">
    ID of the managed access code that conflicts with this managed access code, when Seam can identify it.
  </ResponseField>

  <ResponseField name="modified_fields" type="Array">
    List of fields that were changed externally, with their previous and new values.
  </ResponseField>

  <ResponseField name="unmanaged_access_code_id" type="String (UUID)">
    ID of the unmanaged access code that conflicts with this managed access code, when Seam can identify it.
  </ResponseField>
</Accordion>

### `access_code_inactive`

Indicates that the access code is disabled or inactive on the device. The code exists but will not grant access until re-enabled.

***

### `conflicting_external_modification`

Code was modified or removed externally after Seam successfully set it on the device. The external change conflicts with the state that Seam is trying to apply, so Seam will attempt to set the code on the device again.

***

### `duplicate_code_on_device`

Duplicate access code detected on device.

***

### `failed_to_remove_from_device`

Failed to remove code from device.

***

### `failed_to_set_on_device`

Failed to set code on device.

***

### `no_space_for_access_code_on_device`

No space for access code on device.

***

### `provider_issue`

Indicates a provider-specific issue that prevents the access code from being set or managed. Check the error message for details.

***

### Connected Account

<Note>
  These errors are inherited from the [Connected Account](/api/connected_accounts/errors) resource. When they are set on the parent connected account, they are propagated to this resource's errors list.
</Note>

#### `account_disconnected`

Indicates that the account is disconnected.

***

#### `bridge_disconnected`

Indicates that the Seam API cannot communicate with [Seam Bridge](/capability-guides/seam-bridge), for example, if the Seam Bridge executable has stopped or if the computer running the Seam Bridge executable is offline. See also [Troubleshooting Your Access Control System](/low-level-apis/access-systems/troubleshooting-your-access-control-system#acs_system-errors-seam_bridge_disconnected).

***

#### `dormakaba_sites_disconnected`

Indicates that one or more dormakaba sites associated with the connected account could not be connected. Contact dormakaba support.

***

#### `insufficient_permissions`

Indicates that Seam's integration user does not have sufficient permissions on the provider's system to which this device belongs, so Seam cannot manage access codes or unlock the device. See the error message for specifics, then either reauthorize the connected account in Seam or grant the integration user the required permissions in the provider's system.

***

#### `salto_ks_subscription_limit_exceeded`

Indicates that the Salto site user limit has been reached.

***

### Device

<Note>
  These errors are inherited from the [Device](/api/devices/errors) resource. When they are set on the parent device, they are propagated to this resource's errors list.
</Note>

#### `august_lock_not_authorized`

Indicates that the user is not authorized to use the August lock.

***

#### `device_disconnected`

Indicates that the device is disconnected.

***

#### `device_offline`

Indicates that the device is offline.

***

#### `device_removed`

Indicates that the device has been removed.

***

#### `hub_disconnected`

Indicates that the hub is disconnected.

***

#### `missing_device_credentials`

Indicates that device credentials are missing.

***

#### `subscription_required`

Indicates that a subscription is required to connect.

***

## Warnings

Each warning is an object with the following shape:

```json Example warning theme={null}
{
  "warning_code": "code_rotates_periodically",
  "message": "The access code's PIN rotates periodically when the code is renewed. Retrieve the latest code before each use.",
  "created_at": "2025-01-01T00:00:00.000Z"
}
```

<Accordion title="Warning object properties">
  <ResponseField name="warning_code" type="Enum (String)">
    Unique identifier of the type of warning. Enables quick recognition and categorization of the issue.

    One of the warning codes listed below.
  </ResponseField>

  <ResponseField name="message" type="String">
    Detailed description of the warning. Provides insights into the issue and potentially how to rectify it.
  </ResponseField>

  <ResponseField name="created_at" type="String (ISO 8601)">
    Date and time at which Seam created the warning.
  </ResponseField>

  <ResponseField name="change_type" type="Enum (String)">
    Indicates the type of external modification. `modified` means the code's PIN or schedule was changed. `removed` means the code was deleted from the device.
  </ResponseField>

  <ResponseField name="modified_fields" type="Array">
    List of fields that were changed externally, with their previous and new values.
  </ResponseField>
</Accordion>

### `being_deleted`

Access code is being deleted.

***

### `code_rotates_periodically`

The access code's PIN rotates periodically when the code is renewed. Retrieve the latest code before each use.

***

### `delay_in_removing_from_device`

Delay in removing code from device.

***

### `delay_in_setting_on_device`

Delay in setting code on device.

***

### `external_modification_in_effect`

Code was modified or removed externally after Seam successfully set it on the device. External modification is allowed for this code, so the externally modified state is being honored.

***

### `igloo_algopin_must_be_used_within_24_hours`

Algopins must be used within 24 hours.

***

### `management_transferred`

Management was transferred to another workspace.

***

### `third_party_integration_detected`

Third-party integration detected that may cause access codes to fail.

***

### `time_frame_adjusted_for_unknown_time_zone`

The device's time zone is unknown and this code's time frame crosses a daylight-saving transition in at least one plausible time zone. A 1-hour safety buffer has been applied to the side of the time frame affected by the transition (`ends_at` for spring-forward, `starts_at` for fall-back) so the code stays active through the shift — the code may be usable up to 1 hour beyond your requested window. Set the device's time zone via `/devices/report_provider_metadata` to clear the buffer and guarantee exact handling.

***

### `unknown_issue_with_access_code`

An unknown issue occurred with the access code.

***

### `using_backup_access_code`

A backup access code has been pulled and is being used in place of this access code.

***


# Unmanaged Access Codes Events
Source: https://docs.seam.co/api/access_codes/unmanaged/events

Webhook events that Seam emits for the Unmanaged Access Codes resource, with example payloads and properties.

## `access_code.unmanaged.converted_to_managed`

An [unmanaged access code](/low-level-apis/smart-locks/access-codes/migrating-existing-access-codes) was converted successfully to a managed access code.

<ResponseExample>
  ```json Example webhook payload theme={null}
  {
    "access_code_id": "00000000-0000-0000-0000-000000000000",
    "connected_account_custom_metadata": {},
    "connected_account_id": "00000000-0000-0000-0000-000000000000",
    "created_at": "2025-01-01T00:00:00.000Z",
    "device_custom_metadata": {},
    "device_id": "00000000-0000-0000-0000-000000000000",
    "event_description": "An [unmanaged access code](/low-level-apis/smart-locks/access-codes/migrating-existing-access-codes) was converted successfully to a managed access code.",
    "event_id": "00000000-0000-0000-0000-000000000000",
    "event_type": "access_code.unmanaged.converted_to_managed",
    "occurred_at": "2025-01-01T00:00:00.000Z",
    "workspace_id": "00000000-0000-0000-0000-000000000000"
  }
  ```
</ResponseExample>

<Accordion title="Properties">
  <ResponseField name="access_code_id" type="String (UUID)">
    ID of the affected access code.
  </ResponseField>

  <ResponseField name="connected_account_custom_metadata" type="Object">
    Custom metadata of the connected account, present when connected\_account\_id is provided.
  </ResponseField>

  <ResponseField name="connected_account_id" type="String (UUID)">
    ID of the connected account associated with the affected access code.
  </ResponseField>

  <ResponseField name="created_at" type="String (ISO 8601)">
    Date and time at which the event was created.
  </ResponseField>

  <ResponseField name="device_custom_metadata" type="Object">
    Custom metadata of the device, present when device\_id is provided.
  </ResponseField>

  <ResponseField name="device_id" type="String (UUID)">
    ID of the device associated with the affected access code.
  </ResponseField>

  <ResponseField name="event_description" type="String">
    Human-readable description of the event. Persisted when the event is created (so the creating code, including a provider, can supply a tailored description) and otherwise derived from the event.
  </ResponseField>

  <ResponseField name="event_id" type="String (UUID)">
    ID of the event.
  </ResponseField>

  <ResponseField name="event_type" type="Enum (String)">
    Value: `access_code.unmanaged.converted_to_managed`
  </ResponseField>

  <ResponseField name="occurred_at" type="String (ISO 8601)">
    Date and time at which the event occurred.
  </ResponseField>

  <ResponseField name="workspace_id" type="String (UUID)">
    ID of the workspace associated with the event.
  </ResponseField>
</Accordion>

## `access_code.unmanaged.failed_to_convert_to_managed`

An [unmanaged access code](/low-level-apis/smart-locks/access-codes/migrating-existing-access-codes) failed to be converted to a managed access code.

<ResponseExample>
  ```json Example webhook payload theme={null}
  {
    "access_code_errors": [],
    "access_code_id": "00000000-0000-0000-0000-000000000000",
    "access_code_warnings": [],
    "connected_account_custom_metadata": {},
    "connected_account_errors": [],
    "connected_account_id": "00000000-0000-0000-0000-000000000000",
    "connected_account_warnings": [],
    "created_at": "2025-01-01T00:00:00.000Z",
    "device_custom_metadata": {},
    "device_errors": [],
    "device_id": "00000000-0000-0000-0000-000000000000",
    "device_warnings": [],
    "event_description": "An [unmanaged access code](/low-level-apis/smart-locks/access-codes/migrating-existing-access-codes) failed to be converted to a managed access code.",
    "event_id": "00000000-0000-0000-0000-000000000000",
    "event_type": "access_code.unmanaged.failed_to_convert_to_managed",
    "occurred_at": "2025-01-01T00:00:00.000Z",
    "workspace_id": "00000000-0000-0000-0000-000000000000"
  }
  ```
</ResponseExample>

<Accordion title="Properties">
  <ResponseField name="access_code_errors" type="Array">
    Errors associated with the access code.
  </ResponseField>

  <ResponseField name="access_code_id" type="String (UUID)">
    ID of the affected access code.
  </ResponseField>

  <ResponseField name="access_code_warnings" type="Array">
    Warnings associated with the access code.
  </ResponseField>

  <ResponseField name="connected_account_custom_metadata" type="Object">
    Custom metadata of the connected account, present when connected\_account\_id is provided.
  </ResponseField>

  <ResponseField name="connected_account_errors" type="Array">
    Errors associated with the connected account.
  </ResponseField>

  <ResponseField name="connected_account_id" type="String (UUID)">
    ID of the connected account associated with the affected access code.
  </ResponseField>

  <ResponseField name="connected_account_warnings" type="Array">
    Warnings associated with the connected account.
  </ResponseField>

  <ResponseField name="created_at" type="String (ISO 8601)">
    Date and time at which the event was created.
  </ResponseField>

  <ResponseField name="device_custom_metadata" type="Object">
    Custom metadata of the device, present when device\_id is provided.
  </ResponseField>

  <ResponseField name="device_errors" type="Array">
    Errors associated with the device.
  </ResponseField>

  <ResponseField name="device_id" type="String (UUID)">
    ID of the device associated with the affected access code.
  </ResponseField>

  <ResponseField name="device_warnings" type="Array">
    Warnings associated with the device.
  </ResponseField>

  <ResponseField name="event_description" type="String">
    Human-readable description of the event. Persisted when the event is created (so the creating code, including a provider, can supply a tailored description) and otherwise derived from the event.
  </ResponseField>

  <ResponseField name="event_id" type="String (UUID)">
    ID of the event.
  </ResponseField>

  <ResponseField name="event_type" type="Enum (String)">
    Value: `access_code.unmanaged.failed_to_convert_to_managed`
  </ResponseField>

  <ResponseField name="occurred_at" type="String (ISO 8601)">
    Date and time at which the event occurred.
  </ResponseField>

  <ResponseField name="workspace_id" type="String (UUID)">
    ID of the workspace associated with the event.
  </ResponseField>
</Accordion>

## `access_code.unmanaged.created`

An [unmanaged access code](/low-level-apis/smart-locks/access-codes/migrating-existing-access-codes) was created on a device.

<ResponseExample>
  ```json Example webhook payload theme={null}
  {
    "access_code_id": "00000000-0000-0000-0000-000000000000",
    "connected_account_custom_metadata": {},
    "connected_account_id": "00000000-0000-0000-0000-000000000000",
    "created_at": "2025-01-01T00:00:00.000Z",
    "device_custom_metadata": {},
    "device_id": "00000000-0000-0000-0000-000000000000",
    "event_description": "An [unmanaged access code](/low-level-apis/smart-locks/access-codes/migrating-existing-access-codes) was created on a device.",
    "event_id": "00000000-0000-0000-0000-000000000000",
    "event_type": "access_code.unmanaged.created",
    "occurred_at": "2025-01-01T00:00:00.000Z",
    "workspace_id": "00000000-0000-0000-0000-000000000000"
  }
  ```
</ResponseExample>

<Accordion title="Properties">
  <ResponseField name="access_code_id" type="String (UUID)">
    ID of the affected access code.
  </ResponseField>

  <ResponseField name="connected_account_custom_metadata" type="Object">
    Custom metadata of the connected account, present when connected\_account\_id is provided.
  </ResponseField>

  <ResponseField name="connected_account_id" type="String (UUID)">
    ID of the connected account associated with the affected access code.
  </ResponseField>

  <ResponseField name="created_at" type="String (ISO 8601)">
    Date and time at which the event was created.
  </ResponseField>

  <ResponseField name="device_custom_metadata" type="Object">
    Custom metadata of the device, present when device\_id is provided.
  </ResponseField>

  <ResponseField name="device_id" type="String (UUID)">
    ID of the device associated with the affected access code.
  </ResponseField>

  <ResponseField name="event_description" type="String">
    Human-readable description of the event. Persisted when the event is created (so the creating code, including a provider, can supply a tailored description) and otherwise derived from the event.
  </ResponseField>

  <ResponseField name="event_id" type="String (UUID)">
    ID of the event.
  </ResponseField>

  <ResponseField name="event_type" type="Enum (String)">
    Value: `access_code.unmanaged.created`
  </ResponseField>

  <ResponseField name="occurred_at" type="String (ISO 8601)">
    Date and time at which the event occurred.
  </ResponseField>

  <ResponseField name="workspace_id" type="String (UUID)">
    ID of the workspace associated with the event.
  </ResponseField>
</Accordion>

## `access_code.unmanaged.removed`

An [unmanaged access code](/low-level-apis/smart-locks/access-codes/migrating-existing-access-codes) was removed from a device.

<ResponseExample>
  ```json Example webhook payload theme={null}
  {
    "access_code_id": "00000000-0000-0000-0000-000000000000",
    "connected_account_custom_metadata": {},
    "connected_account_id": "00000000-0000-0000-0000-000000000000",
    "created_at": "2025-01-01T00:00:00.000Z",
    "device_custom_metadata": {},
    "device_id": "00000000-0000-0000-0000-000000000000",
    "event_description": "An [unmanaged access code](/low-level-apis/smart-locks/access-codes/migrating-existing-access-codes) was removed from a device.",
    "event_id": "00000000-0000-0000-0000-000000000000",
    "event_type": "access_code.unmanaged.removed",
    "occurred_at": "2025-01-01T00:00:00.000Z",
    "workspace_id": "00000000-0000-0000-0000-000000000000"
  }
  ```
</ResponseExample>

<Accordion title="Properties">
  <ResponseField name="access_code_id" type="String (UUID)">
    ID of the affected access code.
  </ResponseField>

  <ResponseField name="connected_account_custom_metadata" type="Object">
    Custom metadata of the connected account, present when connected\_account\_id is provided.
  </ResponseField>

  <ResponseField name="connected_account_id" type="String (UUID)">
    ID of the connected account associated with the affected access code.
  </ResponseField>

  <ResponseField name="created_at" type="String (ISO 8601)">
    Date and time at which the event was created.
  </ResponseField>

  <ResponseField name="device_custom_metadata" type="Object">
    Custom metadata of the device, present when device\_id is provided.
  </ResponseField>

  <ResponseField name="device_id" type="String (UUID)">
    ID of the device associated with the affected access code.
  </ResponseField>

  <ResponseField name="event_description" type="String">
    Human-readable description of the event. Persisted when the event is created (so the creating code, including a provider, can supply a tailored description) and otherwise derived from the event.
  </ResponseField>

  <ResponseField name="event_id" type="String (UUID)">
    ID of the event.
  </ResponseField>

  <ResponseField name="event_type" type="Enum (String)">
    Value: `access_code.unmanaged.removed`
  </ResponseField>

  <ResponseField name="occurred_at" type="String (ISO 8601)">
    Date and time at which the event occurred.
  </ResponseField>

  <ResponseField name="workspace_id" type="String (UUID)">
    ID of the workspace associated with the event.
  </ResponseField>
</Accordion>


# Get an Unmanaged Access Code
Source: https://docs.seam.co/api/access_codes/unmanaged/get

/openapi.json post /access_codes/unmanaged/get
Returns a specified [unmanaged access code](/low-level-apis/smart-locks/access-codes/migrating-existing-access-codes).

You must specify either `access_code_id` or both `device_id` and `code`.

You must include at least one request parameter.



# List Unmanaged Access Codes
Source: https://docs.seam.co/api/access_codes/unmanaged/list

/openapi.json post /access_codes/unmanaged/list
Returns a list of all [unmanaged access codes](/low-level-apis/smart-locks/access-codes/migrating-existing-access-codes).



# Unmanaged Access Codes
Source: https://docs.seam.co/api/access_codes/unmanaged/object

Learn how the unmanaged_access_code object represents an existing smart lock PIN code that Seam tracks but does not manage until you convert it.

## The unmanaged\_access\_code Object

Represents an [unmanaged smart lock access code](/low-level-apis/smart-locks/access-codes/migrating-existing-access-codes).

An access code is a code used for a keypad or pinpad device. Unlike physical keys, which can easily be lost or duplicated, PIN codes can be customized, tracked, and altered on the fly.

When you create an access code on a device in Seam, it is created as a managed access code. Access codes that exist on a device that were not created through Seam are considered unmanaged codes. We strictly limit the operations that can be performed on unmanaged codes.

Prior to using Seam to manage your devices, you may have used another lock management system to manage the access codes on your devices. Where possible, we help you keep any existing access codes on devices and transition those codes to ones managed by your Seam workspace.

Not all providers support unmanaged access codes. The following providers do not support unmanaged access codes:

* [Kwikset](/device-and-system-integration-guides/kwikset-locks)

<ResponseExample>
  ```json Unmanaged Access Code theme={null}
  {
    "access_code_id": "88fa1812-bef8-4108-9fb4-4855376c3edf",
    "code": "1234",
    "created_at": "2025-06-16T16:54:17.946283Z",
    "device_id": "b3439f17-7273-46f3-9e20-9a283d9cb5b4",
    "ends_at": "2025-06-23T16:54:17.946261Z",
    "errors": [],
    "is_managed": false,
    "name": "My Unmanaged Access Code",
    "starts_at": "2025-06-21T16:54:17.946261Z",
    "status": "set",
    "type": "time_bound",
    "warnings": [],
    "workspace_id": "750fc0bc-4450-4356-8d9f-18c6a3a6b2c7"
  }
  ```
</ResponseExample>

***

## Properties

<ResponseField name="access_code_id" type="String (UUID)">
  Unique identifier for the access code.
</ResponseField>

<ResponseField name="cannot_be_managed" type="Boolean">
  Indicates that Seam cannot convert this unmanaged access code to a managed access code. Some providers do not support management of unmanaged access codes through API integrations.
</ResponseField>

<ResponseField name="cannot_delete_unmanaged_access_code" type="Boolean">
  Indicates that Seam cannot delete this unmanaged access code through the provider. If this access code needs to be deleted, it will only be possible from the manufacturer app.
</ResponseField>

<ResponseField name="code" type="String">
  Code used for access. Typically, a numeric or alphanumeric string.
</ResponseField>

<ResponseField name="created_at" type="String (ISO 8601)">
  Date and time at which the access code was created.
</ResponseField>

<ResponseField name="device_id" type="String (UUID)">
  Unique identifier for the device associated with the access code.
</ResponseField>

<ResponseField name="dormakaba_oracode_metadata" type="Object">
  Metadata for a dormakaba Oracode unmanaged access code. Only present for unmanaged access codes from dormakaba Oracode devices.

  <Expandable title="properties">
    <ResponseField name="is_cancellable" type="Boolean">
      Indicates whether the stay can be cancelled via the Dormakaba Oracode API.
    </ResponseField>

    <ResponseField name="is_early_checkin_able" type="Boolean">
      Indicates whether early check-in is available for this stay.
    </ResponseField>

    <ResponseField name="is_extendable" type="Boolean">
      Indicates whether the stay can be extended via the Dormakaba Oracode API.
    </ResponseField>

    <ResponseField name="is_overridable" type="Boolean">
      Indicates whether the access code can be overridden. When false, the maximum number of overrides has been reached.
    </ResponseField>

    <ResponseField name="site_name" type="String">
      Dormakaba Oracode site name associated with this access code.
    </ResponseField>

    <ResponseField name="stay_id" type="number">
      Dormakaba Oracode stay ID associated with this access code.
    </ResponseField>

    <ResponseField name="user_level_id" type="String">
      Dormakaba Oracode user level ID associated with this access code.
    </ResponseField>

    <ResponseField name="user_level_name" type="String">
      Dormakaba Oracode user level name associated with this access code.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="ends_at" type="String (ISO 8601)">
  Date and time after which the time-bound access code becomes inactive.
</ResponseField>

<ResponseField name="errors" type="Array">
  Errors associated with the [access code](/low-level-apis/smart-locks/access-codes).
</ResponseField>

<ResponseField name="is_managed" type="Boolean">
  Indicates that Seam does not manage the access code.
</ResponseField>

<ResponseField name="name" type="String">
  Name of the access code. Enables administrators and users to identify the access code easily, especially when there are numerous access codes. Note that the name provided on Seam is used to identify the code on Seam and is not necessarily the name that will appear in 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`. To provide a consistent experience, Seam identifies 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 to meet provider constraints. To help your 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).
</ResponseField>

<ResponseField name="starts_at" type="String (ISO 8601)">
  Date and time at which the time-bound access code becomes active.
</ResponseField>

<ResponseField name="status" type="Enum (String)">
  Current status of the access code within the operational lifecycle. `set` indicates that the code is active and operational. `unset` indicates that the code exists on the provider but is not usable on the device.
</ResponseField>

<ResponseField name="type" type="Enum (String)">
  Type of the access code. `ongoing` access codes are active continuously until deactivated manually. `time_bound` access codes have a specific duration.
</ResponseField>

<ResponseField name="warnings" type="Array">
  Warnings associated with the [access code](/low-level-apis/smart-locks/access-codes).
</ResponseField>

<ResponseField name="workspace_id" type="String (UUID)">
  Unique identifier for the Seam workspace associated with the access code.
</ResponseField>


# Update an Unmanaged Access Code
Source: https://docs.seam.co/api/access_codes/unmanaged/update

/openapi.json post /access_codes/unmanaged/update
Updates a specified [unmanaged access code](/low-level-apis/smart-locks/access-codes/migrating-existing-access-codes).



# Update an Access Code
Source: https://docs.seam.co/api/access_codes/update

/openapi.json post /access_codes/update
Updates a specified active or upcoming [access code](/low-level-apis/smart-locks/access-codes).

See also [Modifying Access Codes](/low-level-apis/smart-locks/access-codes/modifying-access-codes).



# Update Multiple Linked Access Codes
Source: https://docs.seam.co/api/access_codes/update_multiple

/openapi.json post /access_codes/update_multiple
Updates [access codes](/low-level-apis/smart-locks/access-codes) that share a common code across multiple devices.

Specify the `common_code_key` to identify the set of access codes that you want to update.

See also [Update Linked Access Codes](/low-level-apis/smart-locks/access-codes/creating-and-updating-multiple-linked-access-codes#update-linked-access-codes).



# Create an Access Grant
Source: https://docs.seam.co/api/access_grants/create

/openapi.json post /access_grants/create
Creates a new [Access Grant](/use-cases/granting-access). Access Grants are the default and recommended way to grant a user access to any physical space, irrespective of the locking hardware. They work with both standalone smart locks (using `device_ids`) and access control systems (using `acs_entrance_ids` or `space_ids`), and can issue PIN codes, key cards, and mobile keys through a single request.



# Delete an Access Grant
Source: https://docs.seam.co/api/access_grants/delete

/openapi.json post /access_grants/delete
Delete an Access Grant.



# Access Grant Errors and Warnings
Source: https://docs.seam.co/api/access_grants/errors

Errors and warnings that Seam reports on the Access Grant resource, each with its code and meaning.

## Errors

Each error is an object with the following shape:

```json Example error theme={null}
{
  "error_code": "cannot_create_requested_access_methods",
  "message": "Indicates that Seam could not create one or more of the requested access methods for the access grant.",
  "created_at": "2025-01-01T00:00:00.000Z",
  "missing_device_ids": []
}
```

<Accordion title="Error object properties">
  <ResponseField name="error_code" type="Enum (String)">
    Unique identifier of the type of error. Enables quick recognition and categorization of the issue.

    One of the error codes listed below.
  </ResponseField>

  <ResponseField name="message" type="String">
    Detailed description of the error. Provides insights into the issue and potentially how to rectify it.
  </ResponseField>

  <ResponseField name="created_at" type="String (ISO 8601)">
    Date and time at which Seam created the error.
  </ResponseField>

  <ResponseField name="missing_device_ids" type="Array">
    IDs of the devices that did not receive an access code at grant creation. Use these to identify which specific devices failed when the message reports a partial failure.
  </ResponseField>
</Accordion>

### `cannot_create_requested_access_methods`

Indicates that Seam could not create one or more of the requested access methods for the access grant.

***

## Warnings

Each warning is an object with the following shape:

```json Example warning theme={null}
{
  "warning_code": "being_deleted",
  "message": "Indicates that the access grant is being deleted.",
  "created_at": "2025-01-01T00:00:00.000Z"
}
```

<Accordion title="Warning object properties">
  <ResponseField name="warning_code" type="Enum (String)">
    Unique identifier of the type of warning. Enables quick recognition and categorization of the issue.

    One of the warning codes listed below.
  </ResponseField>

  <ResponseField name="message" type="String">
    Detailed description of the warning. Provides insights into the issue and potentially how to rectify it.
  </ResponseField>

  <ResponseField name="created_at" type="String (ISO 8601)">
    Date and time at which Seam created the warning.
  </ResponseField>

  <ResponseField name="access_method_ids" type="Array">
    IDs of the access methods being updated.
  </ResponseField>

  <ResponseField name="device_id" type="String (UUID)">
    ID of the device where the requested code was unavailable.
  </ResponseField>

  <ResponseField name="failed_devices" type="Array">
    Devices whose access codes could not be revoked during reconciliation. Present when the provider does not support revoking an offline access code (e.g. Dormakaba oracode with exhausted override budget).
  </ResponseField>

  <ResponseField name="new_code" type="String">
    The new PIN code that was assigned instead.
  </ResponseField>

  <ResponseField name="original_code" type="String">
    The originally requested PIN code that was unavailable.
  </ResponseField>

  <ResponseField name="reason" type="Enum (String)">
    Specific reason why the grant's times are not programmable on the device.
  </ResponseField>
</Accordion>

### `being_deleted`

Indicates that the [access grant](/use-cases/granting-access) is being deleted.

***

### `device_does_not_support_access_codes`

Indicates that a device in the access grant does not support access codes and was excluded from code materialization.

***

### `device_time_constraints_violated`

Indicates that a device in the access grant cannot program an access code for the grant's time range because of device-specific time constraints.

***

### `overprovisioned_access`

Indicates that the access grant has access to locations it should not have. Access methods are being removed from the extra locations.

***

### `requested_code_unavailable`

Indicates that the requested PIN code was already in use on a device, so a different code was assigned.

***

### `underprovisioned_access`

Indicates that the access grant should have access to more locations than it currently does. Access methods are being created for the missing locations.

***

### `updating_access_times`

Indicates that the access times for this [access grant](/use-cases/granting-access) are being updated.

***


# Access Grant Events
Source: https://docs.seam.co/api/access_grants/events

Webhook events that Seam emits for the Access Grant resource, with example payloads and properties.

## `access_grant.created`

An Access Grant was created.

<ResponseExample>
  ```json Example webhook payload theme={null}
  {
    "access_grant_id": "00000000-0000-0000-0000-000000000000",
    "created_at": "2025-01-01T00:00:00.000Z",
    "event_description": "An Access Grant was created.",
    "event_id": "00000000-0000-0000-0000-000000000000",
    "event_type": "access_grant.created",
    "occurred_at": "2025-01-01T00:00:00.000Z",
    "workspace_id": "00000000-0000-0000-0000-000000000000"
  }
  ```
</ResponseExample>

<Accordion title="Properties">
  <ResponseField name="access_grant_id" type="String (UUID)">
    ID of the affected Access Grant.
  </ResponseField>

  <ResponseField name="created_at" type="String (ISO 8601)">
    Date and time at which the event was created.
  </ResponseField>

  <ResponseField name="event_description" type="String">
    Human-readable description of the event. Persisted when the event is created (so the creating code, including a provider, can supply a tailored description) and otherwise derived from the event.
  </ResponseField>

  <ResponseField name="event_id" type="String (UUID)">
    ID of the event.
  </ResponseField>

  <ResponseField name="event_type" type="Enum (String)">
    Value: `access_grant.created`
  </ResponseField>

  <ResponseField name="occurred_at" type="String (ISO 8601)">
    Date and time at which the event occurred.
  </ResponseField>

  <ResponseField name="workspace_id" type="String (UUID)">
    ID of the workspace associated with the event.
  </ResponseField>
</Accordion>

## `access_grant.deleted`

An Access Grant was deleted.

<ResponseExample>
  ```json Example webhook payload theme={null}
  {
    "access_grant_id": "00000000-0000-0000-0000-000000000000",
    "created_at": "2025-01-01T00:00:00.000Z",
    "event_description": "An Access Grant was deleted.",
    "event_id": "00000000-0000-0000-0000-000000000000",
    "event_type": "access_grant.deleted",
    "occurred_at": "2025-01-01T00:00:00.000Z",
    "workspace_id": "00000000-0000-0000-0000-000000000000"
  }
  ```
</ResponseExample>

<Accordion title="Properties">
  <ResponseField name="access_grant_id" type="String (UUID)">
    ID of the affected Access Grant.
  </ResponseField>

  <ResponseField name="created_at" type="String (ISO 8601)">
    Date and time at which the event was created.
  </ResponseField>

  <ResponseField name="event_description" type="String">
    Human-readable description of the event. Persisted when the event is created (so the creating code, including a provider, can supply a tailored description) and otherwise derived from the event.
  </ResponseField>

  <ResponseField name="event_id" type="String (UUID)">
    ID of the event.
  </ResponseField>

  <ResponseField name="event_type" type="Enum (String)">
    Value: `access_grant.deleted`
  </ResponseField>

  <ResponseField name="occurred_at" type="String (ISO 8601)">
    Date and time at which the event occurred.
  </ResponseField>

  <ResponseField name="workspace_id" type="String (UUID)">
    ID of the workspace associated with the event.
  </ResponseField>
</Accordion>

## `access_grant.access_granted_to_all_doors`

All access requested for an Access Grant was successfully granted.

<ResponseExample>
  ```json Example webhook payload theme={null}
  {
    "access_grant_id": "00000000-0000-0000-0000-000000000000",
    "created_at": "2025-01-01T00:00:00.000Z",
    "event_description": "All access requested for an Access Grant was successfully granted.",
    "event_id": "00000000-0000-0000-0000-000000000000",
    "event_type": "access_grant.access_granted_to_all_doors",
    "occurred_at": "2025-01-01T00:00:00.000Z",
    "workspace_id": "00000000-0000-0000-0000-000000000000"
  }
  ```
</ResponseExample>

<Accordion title="Properties">
  <ResponseField name="access_grant_id" type="String (UUID)">
    ID of the affected Access Grant.
  </ResponseField>

  <ResponseField name="created_at" type="String (ISO 8601)">
    Date and time at which the event was created.
  </ResponseField>

  <ResponseField name="event_description" type="String">
    Human-readable description of the event. Persisted when the event is created (so the creating code, including a provider, can supply a tailored description) and otherwise derived from the event.
  </ResponseField>

  <ResponseField name="event_id" type="String (UUID)">
    ID of the event.
  </ResponseField>

  <ResponseField name="event_type" type="Enum (String)">
    Value: `access_grant.access_granted_to_all_doors`
  </ResponseField>

  <ResponseField name="occurred_at" type="String (ISO 8601)">
    Date and time at which the event occurred.
  </ResponseField>

  <ResponseField name="workspace_id" type="String (UUID)">
    ID of the workspace associated with the event.
  </ResponseField>
</Accordion>

## `access_grant.access_granted_to_door`

Access requested as part of an Access Grant to a particular door was successfully granted.

<ResponseExample>
  ```json Example webhook payload theme={null}
  {
    "access_grant_id": "00000000-0000-0000-0000-000000000000",
    "acs_entrance_id": "00000000-0000-0000-0000-000000000000",
    "created_at": "2025-01-01T00:00:00.000Z",
    "event_description": "Access requested as part of an Access Grant to a particular door was successfully granted.",
    "event_id": "00000000-0000-0000-0000-000000000000",
    "event_type": "access_grant.access_granted_to_door",
    "occurred_at": "2025-01-01T00:00:00.000Z",
    "workspace_id": "00000000-0000-0000-0000-000000000000"
  }
  ```
</ResponseExample>

<Accordion title="Properties">
  <ResponseField name="access_grant_id" type="String (UUID)">
    ID of the affected Access Grant.
  </ResponseField>

  <ResponseField name="acs_entrance_id" type="String (UUID)">
    ID of the affected [entrance](/low-level-apis/access-systems/retrieving-entrance-details).
  </ResponseField>

  <ResponseField name="created_at" type="String (ISO 8601)">
    Date and time at which the event was created.
  </ResponseField>

  <ResponseField name="event_description" type="String">
    Human-readable description of the event. Persisted when the event is created (so the creating code, including a provider, can supply a tailored description) and otherwise derived from the event.
  </ResponseField>

  <ResponseField name="event_id" type="String (UUID)">
    ID of the event.
  </ResponseField>

  <ResponseField name="event_type" type="Enum (String)">
    Value: `access_grant.access_granted_to_door`
  </ResponseField>

  <ResponseField name="occurred_at" type="String (ISO 8601)">
    Date and time at which the event occurred.
  </ResponseField>

  <ResponseField name="workspace_id" type="String (UUID)">
    ID of the workspace associated with the event.
  </ResponseField>
</Accordion>

## `access_grant.access_to_door_lost`

Access to a particular door that was requested as part of an Access Grant was lost.

<ResponseExample>
  ```json Example webhook payload theme={null}
  {
    "access_grant_id": "00000000-0000-0000-0000-000000000000",
    "acs_entrance_id": "00000000-0000-0000-0000-000000000000",
    "created_at": "2025-01-01T00:00:00.000Z",
    "event_description": "Access to a particular door that was requested as part of an Access Grant was lost.",
    "event_id": "00000000-0000-0000-0000-000000000000",
    "event_type": "access_grant.access_to_door_lost",
    "occurred_at": "2025-01-01T00:00:00.000Z",
    "workspace_id": "00000000-0000-0000-0000-000000000000"
  }
  ```
</ResponseExample>

<Accordion title="Properties">
  <ResponseField name="access_grant_id" type="String (UUID)">
    ID of the affected Access Grant.
  </ResponseField>

  <ResponseField name="acs_entrance_id" type="String (UUID)">
    ID of the affected [entrance](/low-level-apis/access-systems/retrieving-entrance-details).
  </ResponseField>

  <ResponseField name="created_at" type="String (ISO 8601)">
    Date and time at which the event was created.
  </ResponseField>

  <ResponseField name="event_description" type="String">
    Human-readable description of the event. Persisted when the event is created (so the creating code, including a provider, can supply a tailored description) and otherwise derived from the event.
  </ResponseField>

  <ResponseField name="event_id" type="String (UUID)">
    ID of the event.
  </ResponseField>

  <ResponseField name="event_type" type="Enum (String)">
    Value: `access_grant.access_to_door_lost`
  </ResponseField>

  <ResponseField name="occurred_at" type="String (ISO 8601)">
    Date and time at which the event occurred.
  </ResponseField>

  <ResponseField name="workspace_id" type="String (UUID)">
    ID of the workspace associated with the event.
  </ResponseField>
</Accordion>

## `access_grant.access_times_changed`

An Access Grant's start or end time was changed.

<ResponseExample>
  ```json Example webhook payload theme={null}
  {
    "access_grant_id": "00000000-0000-0000-0000-000000000000",
    "access_grant_key": "",
    "created_at": "2025-01-01T00:00:00.000Z",
    "ends_at": "2025-01-01T00:00:00.000Z",
    "event_description": "An Access Grant's start or end time was changed.",
    "event_id": "00000000-0000-0000-0000-000000000000",
    "event_type": "access_grant.access_times_changed",
    "occurred_at": "2025-01-01T00:00:00.000Z",
    "starts_at": "2025-01-01T00:00:00.000Z",
    "workspace_id": "00000000-0000-0000-0000-000000000000"
  }
  ```
</ResponseExample>

<Accordion title="Properties">
  <ResponseField name="access_grant_id" type="String (UUID)">
    ID of the affected Access Grant.
  </ResponseField>

  <ResponseField name="access_grant_key" type="String">
    Key of the affected Access Grant (if present).
  </ResponseField>

  <ResponseField name="created_at" type="String (ISO 8601)">
    Date and time at which the event was created.
  </ResponseField>

  <ResponseField name="ends_at" type="String">
    The new end time for the access grant.
  </ResponseField>

  <ResponseField name="event_description" type="String">
    Human-readable description of the event. Persisted when the event is created (so the creating code, including a provider, can supply a tailored description) and otherwise derived from the event.
  </ResponseField>

  <ResponseField name="event_id" type="String (UUID)">
    ID of the event.
  </ResponseField>

  <ResponseField name="event_type" type="Enum (String)">
    Value: `access_grant.access_times_changed`
  </ResponseField>

  <ResponseField name="occurred_at" type="String (ISO 8601)">
    Date and time at which the event occurred.
  </ResponseField>

  <ResponseField name="starts_at" type="String">
    The new start time for the access grant.
  </ResponseField>

  <ResponseField name="workspace_id" type="String (UUID)">
    ID of the workspace associated with the event.
  </ResponseField>
</Accordion>

## `access_grant.could_not_create_requested_access_methods`

One or more requested access methods could not be created for an Access Grant.

<ResponseExample>
  ```json Example webhook payload theme={null}
  {
    "access_grant_id": "00000000-0000-0000-0000-000000000000",
    "created_at": "2025-01-01T00:00:00.000Z",
    "error_message": "",
    "event_description": "One or more requested access methods could not be created for an Access Grant.",
    "event_id": "00000000-0000-0000-0000-000000000000",
    "event_type": "access_grant.could_not_create_requested_access_methods",
    "missing_device_ids": [],
    "occurred_at": "2025-01-01T00:00:00.000Z",
    "workspace_id": "00000000-0000-0000-0000-000000000000"
  }
  ```
</ResponseExample>

<Accordion title="Properties">
  <ResponseField name="access_grant_id" type="String (UUID)">
    ID of the affected Access Grant.
  </ResponseField>

  <ResponseField name="created_at" type="String (ISO 8601)">
    Date and time at which the event was created.
  </ResponseField>

  <ResponseField name="error_message" type="String">
    Description of why the access methods could not be created.
  </ResponseField>

  <ResponseField name="event_description" type="String">
    Human-readable description of the event. Persisted when the event is created (so the creating code, including a provider, can supply a tailored description) and otherwise derived from the event.
  </ResponseField>

  <ResponseField name="event_id" type="String (UUID)">
    ID of the event.
  </ResponseField>

  <ResponseField name="event_type" type="Enum (String)">
    Value: `access_grant.could_not_create_requested_access_methods`
  </ResponseField>

  <ResponseField name="missing_device_ids" type="Array">
    IDs of the devices that did not receive a requested access method. Use these to identify which specific devices failed without having to fetch the Access Grant.
  </ResponseField>

  <ResponseField name="occurred_at" type="String (ISO 8601)">
    Date and time at which the event occurred.
  </ResponseField>

  <ResponseField name="workspace_id" type="String (UUID)">
    ID of the workspace associated with the event.
  </ResponseField>
</Accordion>


# Get an Access Grant
Source: https://docs.seam.co/api/access_grants/get

/openapi.json post /access_grants/get
Get an Access Grant.

You must include at least one request parameter.



# Get related Access Grant resources
Source: https://docs.seam.co/api/access_grants/get_related

/openapi.json post /access_grants/get_related
Gets all related resources for one or more Access Grants.

You must include at least one request parameter.



# List Access Grants
Source: https://docs.seam.co/api/access_grants/list

/openapi.json post /access_grants/list
Gets an Access Grant.



# The Access Grant Object
Source: https://docs.seam.co/api/access_grants/object

Learn how the access_grant object grants a user identity access to spaces, entrances, and devices through mobile keys, plastic cards, and PIN codes.

## The access\_grant Object

Represents an Access Grant. Access Grants enable you to grant a user identity access to spaces, entrances, and devices through one or more access methods, such as mobile keys, plastic cards, and PIN codes. You can create an Access Grant for an existing user identity, or you can create a new user identity *while* creating the new Access Grant.

<ResponseExample>
  ```json Access Grant theme={null}
  {
    "access_grant_id": "ef83cca9-5fdf-4ac2-93f3-c21c5a8be54b",
    "access_method_ids": [
      "a1b2c3d4-e5f6-4a3b-2c1d-0e9f8a7b6c5d",
      "5f4e3d2c-1b0a-9f8e-7d6c-5b4a3c2d1e0f",
      "c7d8e9f0-1a2b-3c4d-5e6f-7a8b9c0d1e2f"
    ],
    "created_at": "2025-06-16T16:54:17.946606Z",
    "display_name": "My Access Grant",
    "ends_at": "2025-06-18T16:54:17.946606Z",
    "instant_key_url": "https://ik.seam.co/ABCXYZ",
    "requested_access_methods": [
      {
        "display_name": "PIN Code Credential",
        "mode": "code",
        "created_at": "2025-06-16T16:54:17.946606Z",
        "created_access_method_ids": [
          "a1b2c3d4-e5f6-4a3b-2c1d-0e9f8a7b6c5d"
        ]
      },
      {
        "display_name": "Card Credential",
        "mode": "card",
        "created_at": "2025-06-16T16:54:19.946606Z",
        "created_access_method_ids": [
          "5f4e3d2c-1b0a-9f8e-7d6c-5b4a3c2d1e0f"
        ]
      },
      {
        "display_name": "Mobile Key Credential",
        "mode": "mobile_key",
        "created_at": "2025-06-16T16:54:21.946606Z",
        "created_access_method_ids": [
          "c7d8e9f0-1a2b-3c4d-5e6f-7a8b9c0d1e2f"
        ]
      }
    ],
    "space_ids": [
      "1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
      "7f8e9d0a-1b2c-3d4e-5f6a-7b8c9d0e1f2a"
    ],
    "starts_at": "2025-06-16T16:54:17.946606Z",
    "user_identity_id": "e3d736c1-540d-4d10-83e5-9a4e135453b4",
    "workspace_id": "750fc0bc-4450-4356-8d9f-18c6a3a6b2c7"
  }
  ```
</ResponseExample>

***

## Properties

<ResponseField name="access_grant_id" type="String (UUID)">
  ID of the Access Grant.
</ResponseField>

<ResponseField name="access_grant_key" type="String">
  Unique key for the access grant within the workspace.
</ResponseField>

<ResponseField name="access_method_ids" type="Array">
  IDs of the access methods created for the Access Grant.
</ResponseField>

<ResponseField name="client_session_token" type="String">
  Client Session Token. Only returned if the Access Grant has a mobile\_key access method.
</ResponseField>

<ResponseField name="created_at" type="String (ISO 8601)">
  Date and time at which the Access Grant was created.
</ResponseField>

<ResponseField name="customization_profile_id" type="String (UUID)">
  ID of the customization profile associated with the Access Grant.
</ResponseField>

<ResponseField name="display_name" type="String">
  Display name of the Access Grant.
</ResponseField>

<ResponseField name="ends_at" type="String (ISO 8601)">
  Date and time at which the Access Grant ends.
</ResponseField>

<ResponseField name="errors" type="Array">
  Errors associated with the [access grant](/use-cases/granting-access).
</ResponseField>

<ResponseField name="instant_key_url" type="String">
  Instant Key URL. Only returned if the Access Grant has a single mobile\_key access\_method.
</ResponseField>

<ResponseField name="location_ids" type="Array">
  **Deprecated**. Use `space_ids`.

  The location ids.
</ResponseField>

<ResponseField name="name" type="String">
  Name of the Access Grant. If not provided, the display name will be computed.
</ResponseField>

<ResponseField name="pending_mutations" type="Array">
  List of pending mutations for the access grant. This shows updates that are in progress.
</ResponseField>

<ResponseField name="requested_access_methods" type="Array">
  Access methods that the user requested for the Access Grant.

  <Expandable title="properties">
    <ResponseField name="code" type="String">
      Specific PIN code to use for this access method. Only applicable when mode is 'code'.
    </ResponseField>

    <ResponseField name="created_access_method_ids" type="Array">
      IDs of the access methods created for the requested access method.
    </ResponseField>

    <ResponseField name="created_at" type="String (ISO 8601)">
      Date and time at which the requested access method was added to the Access Grant.
    </ResponseField>

    <ResponseField name="display_name" type="String">
      Display name of the access method.
    </ResponseField>

    <ResponseField name="instant_key_max_use_count" type="number">
      Maximum number of times the instant key can be used. Only applicable when mode is 'mobile\_key'. Defaults to 1 if not specified.
    </ResponseField>

    <ResponseField name="mode" type="Enum (String)">
      Access method mode. Supported values: `code`, `card`, `mobile_key`, `cloud_key`.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="reservation_key" type="String">
  Reservation key for the access grant.
</ResponseField>

<ResponseField name="space_ids" type="Array">
  IDs of the spaces to which the Access Grant gives access.
</ResponseField>

<ResponseField name="starts_at" type="String (ISO 8601)">
  Date and time at which the Access Grant starts.
</ResponseField>

<ResponseField name="user_identity_id" type="String (UUID)">
  ID of user identity to which the Access Grant gives access.
</ResponseField>

<ResponseField name="warnings" type="Array">
  Warnings associated with the [access grant](/use-cases/granting-access).
</ResponseField>

<ResponseField name="workspace_id" type="String (UUID)">
  ID of the Seam workspace associated with the Access Grant.
</ResponseField>


# Add Requested Access Methods to Access Grant
Source: https://docs.seam.co/api/access_grants/request_access_methods

/openapi.json post /access_grants/request_access_methods
Adds additional requested access methods to an existing Access Grant.



# Get an Unmanaged Access Grant
Source: https://docs.seam.co/api/access_grants/unmanaged/get

/openapi.json post /access_grants/unmanaged/get
Get an unmanaged Access Grant (where is_managed = false).



# List Unmanaged Access Grants
Source: https://docs.seam.co/api/access_grants/unmanaged/list

/openapi.json post /access_grants/unmanaged/list
Gets unmanaged Access Grants (where is_managed = false).



# Update an Unmanaged Access Grant
Source: https://docs.seam.co/api/access_grants/unmanaged/update

/openapi.json post /access_grants/unmanaged/update
Updates an unmanaged Access Grant to make it managed.

This endpoint can only be used to convert unmanaged access grants to managed ones by setting `is_managed` to `true`. It cannot be used to convert managed access grants back to unmanaged.

When converting an unmanaged access grant to managed, all associated access methods will also be converted to managed.



# Update an Access Grant
Source: https://docs.seam.co/api/access_grants/update

/openapi.json post /access_grants/update
Updates an existing Access Grant's time window.

You must include at least one request parameter.



# Assign a Card Credential to an Access Method
Source: https://docs.seam.co/api/access_methods/assign_card

/openapi.json post /access_methods/assign_card
Assigns a pre-registered card credential, identified by `card_number`, to a card-mode access method. Use this endpoint for access systems that use pre-registered cards, where a physical card must be associated with an access method before it can be used for access. Assigning a card credential also triggers issuance of the access method.



# Delete an Access Method
Source: https://docs.seam.co/api/access_methods/delete

/openapi.json post /access_methods/delete
Deletes an access method.

You must include at least one request parameter.



# Encode an Access Method
Source: https://docs.seam.co/api/access_methods/encode

/openapi.json post /access_methods/encode
Encodes an existing access method onto a plastic card placed on the specified [encoder](/low-level-apis/access-systems/working-with-card-encoders-and-scanners).



# Access Method Errors and Warnings
Source: https://docs.seam.co/api/access_methods/errors

Errors and warnings that Seam reports on the Access Method resource, each with its code and meaning.

## Errors

Each error is an object with the following shape:

```json Example error theme={null}
{
  "error_code": "failed_to_issue",
  "message": "Indicates that Seam was unable to issue this access method before its access grant started, so the recipient may be unable to access the space. This usually points to a problem that needs attention, such as an offline or disconnected device. Seam keeps retrying, and this error clears automatically if the access method is eventually issued.",
  "created_at": "2025-01-01T00:00:00.000Z"
}
```

<Accordion title="Error object properties">
  <ResponseField name="error_code" type="Enum (String)">
    Unique identifier of the type of error. Enables quick recognition and categorization of the issue.

    One of the error codes listed below.
  </ResponseField>

  <ResponseField name="message" type="String">
    Detailed description of the error. Provides insights into the issue and potentially how to rectify it.
  </ResponseField>

  <ResponseField name="created_at" type="String (ISO 8601)">
    Date and time at which Seam created the error.
  </ResponseField>
</Accordion>

### `failed_to_issue`

Indicates that Seam was unable to issue this [access method](/use-cases/granting-access/creating-an-access-grant) before its access grant started, so the recipient may be unable to access the space. This usually points to a problem that needs attention, such as an offline or disconnected device. Seam keeps retrying, and this error clears automatically if the access method is eventually issued.

***

## Warnings

Each warning is an object with the following shape:

```json Example warning theme={null}
{
  "warning_code": "being_deleted",
  "message": "Indicates that the access method is being deleted.",
  "created_at": "2025-01-01T00:00:00.000Z"
}
```

<Accordion title="Warning object properties">
  <ResponseField name="warning_code" type="Enum (String)">
    Unique identifier of the type of warning. Enables quick recognition and categorization of the issue.

    One of the warning codes listed below.
  </ResponseField>

  <ResponseField name="message" type="String">
    Detailed description of the warning. Provides insights into the issue and potentially how to rectify it.
  </ResponseField>

  <ResponseField name="created_at" type="String (ISO 8601)">
    Date and time at which Seam created the warning.
  </ResponseField>

  <ResponseField name="original_access_method_id" type="String (UUID)">
    ID of the original access method from which this backup access method was split, if applicable.
  </ResponseField>
</Accordion>

### `being_deleted`

Indicates that the [access method](/use-cases/granting-access/creating-an-access-grant) is being deleted.

***

### `delay_in_issuing`

Indicates that Seam has not yet issued this [access method](/use-cases/granting-access/creating-an-access-grant), even though its access grant is about to begin, so access may not be ready when the recipient arrives. Seam is still attempting to issue it, and this warning clears automatically once issuance succeeds.

***

### `pulled_backup_access_code`

Indicates that all attempts to create an access code on this device before the start time failed and a backup access code was used to ensure access was provided in time.

***

### `updating_access_times`

Indicates that the access times for this [access method](/use-cases/granting-access/creating-an-access-grant) are being updated.

***


# Access Method Events
Source: https://docs.seam.co/api/access_methods/events

Webhook events that Seam emits for the Access Method resource, with example payloads and properties.

## `access_method.issued`

An access method was issued.

<ResponseExample>
  ```json Example webhook payload theme={null}
  {
    "access_grant_ids": [],
    "access_grant_keys": [],
    "access_method_id": "00000000-0000-0000-0000-000000000000",
    "code": "1234",
    "created_at": "2025-01-01T00:00:00.000Z",
    "event_description": "An access method was issued.",
    "event_id": "00000000-0000-0000-0000-000000000000",
    "event_type": "access_method.issued",
    "is_backup_code": true,
    "occurred_at": "2025-01-01T00:00:00.000Z",
    "workspace_id": "00000000-0000-0000-0000-000000000000"
  }
  ```
</ResponseExample>

<Accordion title="Properties">
  <ResponseField name="access_grant_ids" type="Array">
    IDs of the access grants associated with this access method.
  </ResponseField>

  <ResponseField name="access_grant_keys" type="Array">
    Keys of the access grants associated with this access method (if present).
  </ResponseField>

  <ResponseField name="access_method_id" type="String (UUID)">
    ID of the affected access method.
  </ResponseField>

  <ResponseField name="code" type="String">
    The actual PIN code for code access methods (only present when mode is 'code').
  </ResponseField>

  <ResponseField name="created_at" type="String (ISO 8601)">
    Date and time at which the event was created.
  </ResponseField>

  <ResponseField name="event_description" type="String">
    Human-readable description of the event. Persisted when the event is created (so the creating code, including a provider, can supply a tailored description) and otherwise derived from the event.
  </ResponseField>

  <ResponseField name="event_id" type="String (UUID)">
    ID of the event.
  </ResponseField>

  <ResponseField name="event_type" type="Enum (String)">
    Value: `access_method.issued`
  </ResponseField>

  <ResponseField name="is_backup_code" type="Boolean">
    Indicates whether the code is a backup code (only present when mode is 'code' and a backup code was used).
  </ResponseField>

  <ResponseField name="occurred_at" type="String (ISO 8601)">
    Date and time at which the event occurred.
  </ResponseField>

  <ResponseField name="workspace_id" type="String (UUID)">
    ID of the workspace associated with the event.
  </ResponseField>
</Accordion>

## `access_method.revoked`

An access method was revoked.

<ResponseExample>
  ```json Example webhook payload theme={null}
  {
    "access_grant_ids": [],
    "access_grant_keys": [],
    "access_method_id": "00000000-0000-0000-0000-000000000000",
    "created_at": "2025-01-01T00:00:00.000Z",
    "event_description": "An access method was revoked.",
    "event_id": "00000000-0000-0000-0000-000000000000",
    "event_type": "access_method.revoked",
    "occurred_at": "2025-01-01T00:00:00.000Z",
    "workspace_id": "00000000-0000-0000-0000-000000000000"
  }
  ```
</ResponseExample>

<Accordion title="Properties">
  <ResponseField name="access_grant_ids" type="Array">
    IDs of the access grants associated with this access method.
  </ResponseField>

  <ResponseField name="access_grant_keys" type="Array">
    Keys of the access grants associated with this access method (if present).
  </ResponseField>

  <ResponseField name="access_method_id" type="String (UUID)">
    ID of the affected access method.
  </ResponseField>

  <ResponseField name="created_at" type="String (ISO 8601)">
    Date and time at which the event was created.
  </ResponseField>

  <ResponseField name="event_description" type="String">
    Human-readable description of the event. Persisted when the event is created (so the creating code, including a provider, can supply a tailored description) and otherwise derived from the event.
  </ResponseField>

  <ResponseField name="event_id" type="String (UUID)">
    ID of the event.
  </ResponseField>

  <ResponseField name="event_type" type="Enum (String)">
    Value: `access_method.revoked`
  </ResponseField>

  <ResponseField name="occurred_at" type="String (ISO 8601)">
    Date and time at which the event occurred.
  </ResponseField>

  <ResponseField name="workspace_id" type="String (UUID)">
    ID of the workspace associated with the event.
  </ResponseField>
</Accordion>

## `access_method.card_encoding_required`

An access method representing a physical card requires encoding.

<ResponseExample>
  ```json Example webhook payload theme={null}
  {
    "access_grant_ids": [],
    "access_grant_keys": [],
    "access_method_id": "00000000-0000-0000-0000-000000000000",
    "created_at": "2025-01-01T00:00:00.000Z",
    "event_description": "An access method representing a physical card requires encoding.",
    "event_id": "00000000-0000-0000-0000-000000000000",
    "event_type": "access_method.card_encoding_required",
    "occurred_at": "2025-01-01T00:00:00.000Z",
    "workspace_id": "00000000-0000-0000-0000-000000000000"
  }
  ```
</ResponseExample>

<Accordion title="Properties">
  <ResponseField name="access_grant_ids" type="Array">
    IDs of the access grants associated with this access method.
  </ResponseField>

  <ResponseField name="access_grant_keys" type="Array">
    Keys of the access grants associated with this access method (if present).
  </ResponseField>

  <ResponseField name="access_method_id" type="String (UUID)">
    ID of the affected access method.
  </ResponseField>

  <ResponseField name="created_at" type="String (ISO 8601)">
    Date and time at which the event was created.
  </ResponseField>

  <ResponseField name="event_description" type="String">
    Human-readable description of the event. Persisted when the event is created (so the creating code, including a provider, can supply a tailored description) and otherwise derived from the event.
  </ResponseField>

  <ResponseField name="event_id" type="String (UUID)">
    ID of the event.
  </ResponseField>

  <ResponseField name="event_type" type="Enum (String)">
    Value: `access_method.card_encoding_required`
  </ResponseField>

  <ResponseField name="occurred_at" type="String (ISO 8601)">
    Date and time at which the event occurred.
  </ResponseField>

  <ResponseField name="workspace_id" type="String (UUID)">
    ID of the workspace associated with the event.
  </ResponseField>
</Accordion>

## `access_method.deleted`

An access method was deleted.

<ResponseExample>
  ```json Example webhook payload theme={null}
  {
    "access_grant_ids": [],
    "access_grant_keys": [],
    "access_method_id": "00000000-0000-0000-0000-000000000000",
    "created_at": "2025-01-01T00:00:00.000Z",
    "event_description": "An access method was deleted.",
    "event_id": "00000000-0000-0000-0000-000000000000",
    "event_type": "access_method.deleted",
    "occurred_at": "2025-01-01T00:00:00.000Z",
    "workspace_id": "00000000-0000-0000-0000-000000000000"
  }
  ```
</ResponseExample>

<Accordion title="Properties">
  <ResponseField name="access_grant_ids" type="Array">
    IDs of the access grants associated with this access method.
  </ResponseField>

  <ResponseField name="access_grant_keys" type="Array">
    Keys of the access grants associated with this access method (if present).
  </ResponseField>

  <ResponseField name="access_method_id" type="String (UUID)">
    ID of the affected access method.
  </ResponseField>

  <ResponseField name="created_at" type="String (ISO 8601)">
    Date and time at which the event was created.
  </ResponseField>

  <ResponseField name="event_description" type="String">
    Human-readable description of the event. Persisted when the event is created (so the creating code, including a provider, can supply a tailored description) and otherwise derived from the event.
  </ResponseField>

  <ResponseField name="event_id" type="String (UUID)">
    ID of the event.
  </ResponseField>

  <ResponseField name="event_type" type="Enum (String)">
    Value: `access_method.deleted`
  </ResponseField>

  <ResponseField name="occurred_at" type="String (ISO 8601)">
    Date and time at which the event occurred.
  </ResponseField>

  <ResponseField name="workspace_id" type="String (UUID)">
    ID of the workspace associated with the event.
  </ResponseField>
</Accordion>

## `access_method.reissued`

An access method was reissued.

<ResponseExample>
  ```json Example webhook payload theme={null}
  {
    "access_grant_ids": [],
    "access_grant_keys": [],
    "access_method_id": "00000000-0000-0000-0000-000000000000",
    "code": "1234",
    "created_at": "2025-01-01T00:00:00.000Z",
    "event_description": "An access method was reissued.",
    "event_id": "00000000-0000-0000-0000-000000000000",
    "event_type": "access_method.reissued",
    "is_backup_code": true,
    "occurred_at": "2025-01-01T00:00:00.000Z",
    "workspace_id": "00000000-0000-0000-0000-000000000000"
  }
  ```
</ResponseExample>

<Accordion title="Properties">
  <ResponseField name="access_grant_ids" type="Array">
    IDs of the access grants associated with this access method.
  </ResponseField>

  <ResponseField name="access_grant_keys" type="Array">
    Keys of the access grants associated with this access method (if present).
  </ResponseField>

  <ResponseField name="access_method_id" type="String (UUID)">
    ID of the affected access method.
  </ResponseField>

  <ResponseField name="code" type="String">
    The actual PIN code for code access methods (only present when mode is 'code').
  </ResponseField>

  <ResponseField name="created_at" type="String (ISO 8601)">
    Date and time at which the event was created.
  </ResponseField>

  <ResponseField name="event_description" type="String">
    Human-readable description of the event. Persisted when the event is created (so the creating code, including a provider, can supply a tailored description) and otherwise derived from the event.
  </ResponseField>

  <ResponseField name="event_id" type="String (UUID)">
    ID of the event.
  </ResponseField>

  <ResponseField name="event_type" type="Enum (String)">
    Value: `access_method.reissued`
  </ResponseField>

  <ResponseField name="is_backup_code" type="Boolean">
    Indicates whether the code is a backup code (only present when mode is 'code' and a backup code was used).
  </ResponseField>

  <ResponseField name="occurred_at" type="String (ISO 8601)">
    Date and time at which the event occurred.
  </ResponseField>

  <ResponseField name="workspace_id" type="String (UUID)">
    ID of the workspace associated with the event.
  </ResponseField>
</Accordion>

## `access_method.created`

An access method was created.

<ResponseExample>
  ```json Example webhook payload theme={null}
  {
    "access_grant_ids": [],
    "access_grant_keys": [],
    "access_method_id": "00000000-0000-0000-0000-000000000000",
    "created_at": "2025-01-01T00:00:00.000Z",
    "event_description": "An access method was created.",
    "event_id": "00000000-0000-0000-0000-000000000000",
    "event_type": "access_method.created",
    "occurred_at": "2025-01-01T00:00:00.000Z",
    "workspace_id": "00000000-0000-0000-0000-000000000000"
  }
  ```
</ResponseExample>

<Accordion title="Properties">
  <ResponseField name="access_grant_ids" type="Array">
    IDs of the access grants associated with this access method.
  </ResponseField>

  <ResponseField name="access_grant_keys" type="Array">
    Keys of the access grants associated with this access method (if present).
  </ResponseField>

  <ResponseField name="access_method_id" type="String (UUID)">
    ID of the affected access method.
  </ResponseField>

  <ResponseField name="created_at" type="String (ISO 8601)">
    Date and time at which the event was created.
  </ResponseField>

  <ResponseField name="event_description" type="String">
    Human-readable description of the event. Persisted when the event is created (so the creating code, including a provider, can supply a tailored description) and otherwise derived from the event.
  </ResponseField>

  <ResponseField name="event_id" type="String (UUID)">
    ID of the event.
  </ResponseField>

  <ResponseField name="event_type" type="Enum (String)">
    Value: `access_method.created`
  </ResponseField>

  <ResponseField name="occurred_at" type="String (ISO 8601)">
    Date and time at which the event occurred.
  </ResponseField>

  <ResponseField name="workspace_id" type="String (UUID)">
    ID of the workspace associated with the event.
  </ResponseField>
</Accordion>

## `access_method.delay_in_issuing`

Seam has not yet issued this access method, even though its access grant is about to begin, so access may not be ready when the recipient arrives. Seam is still attempting to issue it, and the accompanying `delay_in_issuing` warning clears automatically once issuance succeeds.

<ResponseExample>
  ```json Example webhook payload theme={null}
  {
    "access_grant_ids": [],
    "access_grant_keys": [],
    "access_method_id": "00000000-0000-0000-0000-000000000000",
    "created_at": "2025-01-01T00:00:00.000Z",
    "event_description": "Seam has not yet issued this access method, even though its access grant is about to begin, so access may not be ready when the recipient arrives. Seam is still attempting to issue it, and the accompanying `delay_in_issuing` warning clears automatically once issuance succeeds.",
    "event_id": "00000000-0000-0000-0000-000000000000",
    "event_type": "access_method.delay_in_issuing",
    "occurred_at": "2025-01-01T00:00:00.000Z",
    "workspace_id": "00000000-0000-0000-0000-000000000000"
  }
  ```
</ResponseExample>

<Accordion title="Properties">
  <ResponseField name="access_grant_ids" type="Array">
    IDs of the access grants associated with this access method.
  </ResponseField>

  <ResponseField name="access_grant_keys" type="Array">
    Keys of the access grants associated with this access method (if present).
  </ResponseField>

  <ResponseField name="access_method_id" type="String (UUID)">
    ID of the affected access method.
  </ResponseField>

  <ResponseField name="created_at" type="String (ISO 8601)">
    Date and time at which the event was created.
  </ResponseField>

  <ResponseField name="event_description" type="String">
    Human-readable description of the event. Persisted when the event is created (so the creating code, including a provider, can supply a tailored description) and otherwise derived from the event.
  </ResponseField>

  <ResponseField name="event_id" type="String (UUID)">
    ID of the event.
  </ResponseField>

  <ResponseField name="event_type" type="Enum (String)">
    Value: `access_method.delay_in_issuing`
  </ResponseField>

  <ResponseField name="occurred_at" type="String (ISO 8601)">
    Date and time at which the event occurred.
  </ResponseField>

  <ResponseField name="workspace_id" type="String (UUID)">
    ID of the workspace associated with the event.
  </ResponseField>
</Accordion>

## `access_method.failed_to_issue`

Seam was unable to issue this access method before its access grant started, so the recipient may be unable to access the space. This usually points to a problem that needs attention, such as an offline or disconnected device. Seam keeps retrying, and the accompanying `failed_to_issue` error clears automatically if the access method is eventually issued.

<ResponseExample>
  ```json Example webhook payload theme={null}
  {
    "access_grant_ids": [],
    "access_grant_keys": [],
    "access_method_id": "00000000-0000-0000-0000-000000000000",
    "created_at": "2025-01-01T00:00:00.000Z",
    "event_description": "Seam was unable to issue this access method before its access grant started, so the recipient may be unable to access the space. This usually points to a problem that needs attention, such as an offline or disconnected device. Seam keeps retrying, and the accompanying `failed_to_issue` error clears automatically if the access method is eventually issued.",
    "event_id": "00000000-0000-0000-0000-000000000000",
    "event_type": "access_method.failed_to_issue",
    "occurred_at": "2025-01-01T00:00:00.000Z",
    "workspace_id": "00000000-0000-0000-0000-000000000000"
  }
  ```
</ResponseExample>

<Accordion title="Properties">
  <ResponseField name="access_grant_ids" type="Array">
    IDs of the access grants associated with this access method.
  </ResponseField>

  <ResponseField name="access_grant_keys" type="Array">
    Keys of the access grants associated with this access method (if present).
  </ResponseField>

  <ResponseField name="access_method_id" type="String (UUID)">
    ID of the affected access method.
  </ResponseField>

  <ResponseField name="created_at" type="String (ISO 8601)">
    Date and time at which the event was created.
  </ResponseField>

  <ResponseField name="event_description" type="String">
    Human-readable description of the event. Persisted when the event is created (so the creating code, including a provider, can supply a tailored description) and otherwise derived from the event.
  </ResponseField>

  <ResponseField name="event_id" type="String (UUID)">
    ID of the event.
  </ResponseField>

  <ResponseField name="event_type" type="Enum (String)">
    Value: `access_method.failed_to_issue`
  </ResponseField>

  <ResponseField name="occurred_at" type="String (ISO 8601)">
    Date and time at which the event occurred.
  </ResponseField>

  <ResponseField name="workspace_id" type="String (UUID)">
    ID of the workspace associated with the event.
  </ResponseField>
</Accordion>


# Get an Access Method
Source: https://docs.seam.co/api/access_methods/get

/openapi.json post /access_methods/get
Gets an access method.



# Get related Access Method resources
Source: https://docs.seam.co/api/access_methods/get_related

/openapi.json post /access_methods/get_related
Gets all related resources for one or more Access Methods.



# List Access Methods
Source: https://docs.seam.co/api/access_methods/list

/openapi.json post /access_methods/list
Lists all access methods, usually filtered by Access Grant.

You must include at least one request parameter.



# The Access Method Object
Source: https://docs.seam.co/api/access_methods/object

Learn how the access_method object describes the modes of access for an Access Grant, such as PIN codes, plastic cards, and mobile keys.

## The access\_method Object

Represents an access method for an Access Grant. Access methods describe the modes of access, such as PIN codes, plastic cards, and mobile keys. For a mobile key, the access method also stores the URL for the associated Instant Key.

<ResponseExample>
  ```json Card Access Method theme={null}
  {
    "access_method_id": "27d8ad77-55c2-4e20-b5b3-43555926f0e8",
    "created_at": "2025-06-14T16:54:17.946612Z",
    "display_name": "My Card",
    "is_card_encoding_required": true,
    "issued_at": "2025-06-14T16:54:17.946612Z",
    "mode": "card",
    "workspace_id": "661025d3-c1d2-403c-83a8-af153aaedfbc"
  }
  ```

  ```json Mobile Key Access Method theme={null}
  {
    "access_method_id": "27d8ad77-55c2-4e20-b5b3-43555926f0e8",
    "created_at": "2025-06-14T16:54:17.946612Z",
    "display_name": "My Mobile Key",
    "instant_key_url": "https://ik.seam.co/ABCXYZ",
    "is_card_encoding_required": false,
    "mode": "mobile_key",
    "workspace_id": "661025d3-c1d2-403c-83a8-af153aaedfbc"
  }
  ```

  ```json PIN Code Access Method theme={null}
  {
    "access_method_id": "27d8ad77-55c2-4e20-b5b3-43555926f0e8",
    "created_at": "2025-06-14T16:54:17.946612Z",
    "display_name": "My PIN Code",
    "is_card_encoding_required": false,
    "mode": "code",
    "workspace_id": "661025d3-c1d2-403c-83a8-af153aaedfbc"
  }
  ```

  ```json Cloud Key Access Method theme={null}
  {
    "workspace_id": "00000000-0000-0000-0000-000000000000",
    "access_method_id": "00000000-0000-0000-0000-000000000000",
    "display_name": "",
    "mode": "cloud_key",
    "created_at": "2025-01-01T00:00:00.000Z",
    "issued_at": "2025-01-01T00:00:00.000Z",
    "is_issued": false,
    "warnings": [],
    "errors": [],
    "pending_mutations": []
  }
  ```
</ResponseExample>

***

## Properties

<ResponseField name="access_method_id" type="String (UUID)">
  ID of the access method.
</ResponseField>

<ResponseField name="client_session_token" type="String">
  Token of the client session associated with the access method.
</ResponseField>

<ResponseField name="code" type="String">
  The actual PIN code for code access methods.
</ResponseField>

<ResponseField name="created_at" type="String (ISO 8601)">
  Date and time at which the access method was created.
</ResponseField>

<ResponseField name="customization_profile_id" type="String (UUID)">
  ID of the customization profile associated with the access method.
</ResponseField>

<ResponseField name="display_name" type="String">
  Display name of the access method.
</ResponseField>

<ResponseField name="errors" type="Array">
  Errors associated with the [access method](/use-cases/granting-access/creating-an-access-grant).
</ResponseField>

<ResponseField name="instant_key_url" type="String">
  URL of the Instant Key for mobile key access methods.
</ResponseField>

<ResponseField name="is_assignment_required" type="Boolean">
  Indicates whether an existing card credential must be assigned to this access method before it can be issued. Only applies to card-mode access methods on systems that support credential assignment.
</ResponseField>

<ResponseField name="is_encoding_required" type="Boolean">
  Indicates whether encoding with an card encoder is required to issue or reissue the plastic card associated with the access method.
</ResponseField>

<ResponseField name="is_issued" type="Boolean">
  Indicates whether the access method has been issued.
</ResponseField>

<ResponseField name="is_ready_for_assignment" type="Boolean">
  Indicates whether the access method is ready for card assignment. This is true when the access method is in card mode, has not yet been issued, and the system supports credential assignment.
</ResponseField>

<ResponseField name="is_ready_for_encoding" type="Boolean">
  Indicates whether the access method is ready to be encoded. This is true when the credential has been created and the card has not yet been issued.
</ResponseField>

<ResponseField name="issued_at" type="String (ISO 8601)">
  Date and time at which the access method was issued.
</ResponseField>

<ResponseField name="mode" type="Enum (String)">
  Access method mode. Supported values: `code`, `card`, `mobile_key`, `cloud_key`.
</ResponseField>

<ResponseField name="pending_mutations" type="Array">
  Pending mutations for the [access method](/use-cases/granting-access/creating-an-access-grant). Indicates operations that are in progress.
</ResponseField>

<ResponseField name="warnings" type="Array">
  Warnings associated with the [access method](/use-cases/granting-access/creating-an-access-grant).
</ResponseField>

<ResponseField name="workspace_id" type="String (UUID)">
  ID of the Seam workspace associated with the access method.
</ResponseField>


# Unlock a Door with an Access Method
Source: https://docs.seam.co/api/access_methods/unlock_door

/openapi.json post /access_methods/unlock_door
Remotely unlocks a specified [entrance](/low-level-apis/access-systems/retrieving-entrance-details) using the cloud key credential associated with an access method. Returns an action attempt that tracks the progress of the unlock operation.



# Get an Unmanaged Access Method
Source: https://docs.seam.co/api/access_methods/unmanaged/get

/openapi.json post /access_methods/unmanaged/get
Gets an unmanaged access method (where is_managed = false).



# List Unmanaged Access Methods
Source: https://docs.seam.co/api/access_methods/unmanaged/list

/openapi.json post /access_methods/unmanaged/list
Lists all unmanaged access methods (where is_managed = false), usually filtered by Access Grant.



# Add an ACS User to an Access Group
Source: https://docs.seam.co/api/acs/access_groups/add_user

/openapi.json post /acs/access_groups/add_user
Adds a specified [access system user](/low-level-apis/access-systems/user-management) to a specified [access group](/low-level-apis/access-systems/user-management/assigning-users-to-access-groups).



# Delete an Access Group
Source: https://docs.seam.co/api/acs/access_groups/delete

/openapi.json post /acs/access_groups/delete
Deletes a specified [access group](/low-level-apis/access-systems/user-management/assigning-users-to-access-groups).



# Access Group Errors
Source: https://docs.seam.co/api/acs/access_groups/errors

Errors that Seam reports on the Access Group resource, each with its code and meaning.

## Errors

Each error is an object with the following shape:

```json Example error theme={null}
{
  "error_code": "failed_to_create_on_acs_system",
  "message": "Indicates that the access group was not created on the access system. This is likely due to an internal unexpected error. Contact Seam support.",
  "created_at": "2025-01-01T00:00:00.000Z"
}
```

<Accordion title="Error object properties">
  <ResponseField name="error_code" type="Enum (String)">
    Unique identifier of the type of error. Enables quick recognition and categorization of the issue.

    One of the error codes listed below.
  </ResponseField>

  <ResponseField name="message" type="String">
    Detailed description of the error. Provides insights into the issue and potentially how to rectify it.
  </ResponseField>

  <ResponseField name="created_at" type="String (ISO 8601)">
    Date and time at which Seam created the error.
  </ResponseField>
</Accordion>

### `failed_to_create_on_acs_system`

Indicates that the [access group](/low-level-apis/access-systems/user-management/assigning-users-to-access-groups) was not created on the [access system](/low-level-apis/access-systems). This is likely due to an internal unexpected error. Contact Seam [support](mailto:support@seam.co).

***


# Access Group Events
Source: https://docs.seam.co/api/acs/access_groups/events

Webhook events that Seam emits for the Access Group resource, with example payloads and properties.

## `acs_access_group.deleted`

An ACS access group was deleted.

<ResponseExample>
  ```json Example webhook payload theme={null}
  {
    "acs_access_group_id": "00000000-0000-0000-0000-000000000000",
    "acs_system_id": "00000000-0000-0000-0000-000000000000",
    "connected_account_id": "00000000-0000-0000-0000-000000000000",
    "created_at": "2025-01-01T00:00:00.000Z",
    "event_description": "An ACS access group was deleted.",
    "event_id": "00000000-0000-0000-0000-000000000000",
    "event_type": "acs_access_group.deleted",
    "occurred_at": "2025-01-01T00:00:00.000Z",
    "workspace_id": "00000000-0000-0000-0000-000000000000"
  }
  ```
</ResponseExample>

<Accordion title="Properties">
  <ResponseField name="acs_access_group_id" type="String (UUID)">
    ID of the affected access group.
  </ResponseField>

  <ResponseField name="acs_system_id" type="String (UUID)">
    ID of the access system.
  </ResponseField>

  <ResponseField name="connected_account_id" type="String (UUID)">
    ID of the connected account.
  </ResponseField>

  <ResponseField name="created_at" type="String (ISO 8601)">
    Date and time at which the event was created.
  </ResponseField>

  <ResponseField name="event_description" type="String">
    Human-readable description of the event. Persisted when the event is created (so the creating code, including a provider, can supply a tailored description) and otherwise derived from the event.
  </ResponseField>

  <ResponseField name="event_id" type="String (UUID)">
    ID of the event.
  </ResponseField>

  <ResponseField name="event_type" type="Enum (String)">
    Value: `acs_access_group.deleted`
  </ResponseField>

  <ResponseField name="occurred_at" type="String (ISO 8601)">
    Date and time at which the event occurred.
  </ResponseField>

  <ResponseField name="workspace_id" type="String (UUID)">
    ID of the workspace associated with the event.
  </ResponseField>
</Accordion>


# Get an Access Group
Source: https://docs.seam.co/api/acs/access_groups/get

/openapi.json post /acs/access_groups/get
Returns a specified [access group](/low-level-apis/access-systems/user-management/assigning-users-to-access-groups).



# List Access Groups
Source: https://docs.seam.co/api/acs/access_groups/list

/openapi.json post /acs/access_groups/list
Returns a list of all [access groups](/low-level-apis/access-systems/user-management/assigning-users-to-access-groups).



# List Entrances Accessible to an Access Group
Source: https://docs.seam.co/api/acs/access_groups/list_accessible_entrances

/openapi.json post /acs/access_groups/list_accessible_entrances
Returns a list of all accessible entrances for a specified [access group](/low-level-apis/access-systems/user-management/assigning-users-to-access-groups).



# List ACS Users in an Access Group
Source: https://docs.seam.co/api/acs/access_groups/list_users

/openapi.json post /acs/access_groups/list_users
Returns a list of all [access system users](/low-level-apis/access-systems/user-management) in an [access group](/low-level-apis/access-systems/user-management/assigning-users-to-access-groups).



# The Access Group Object
Source: https://docs.seam.co/api/acs/access_groups/object

Learn how the acs_access_group object defines the entrances a set of access system users can reach and, in some systems, their access schedule.

## The acs\_access\_group Object

Group that defines the entrances to which a set of users has access and, in some cases, the access schedule for these entrances and users.

Some access control systems use [access group](/low-level-apis/access-systems/user-management/assigning-users-to-access-groups), which are sets of users, combined with sets of permissions. These permissions include both the set of areas or assets that the users can access and the schedule during which the users can access these areas or assets. Instead of assigning access rights individually to each access control system user, which can be time-consuming and error-prone, administrators can assign users to an access group, thereby ensuring that the users inherit all the permissions associated with the access group. Using access groups streamlines the process of managing large numbers of access control system users, especially in bigger organizations or complexes.

To learn whether your access control system supports access groups, see the corresponding [system integration guide](/device-and-system-integration-guides#access-control-systems).

<ResponseExample>
  ```json ACS Access Group theme={null}
  {
    "access_group_type": "salto_ks_access_group",
    "access_group_type_display_name": "Salto KS Access Group",
    "acs_access_group_id": "3f448826-9875-4947-9519-e468090a4f7d",
    "acs_system_id": "045baa77-6d06-40fe-a2cd-b82eef688f4a",
    "connected_account_id": "daba7bd0-edb6-4bb9-a70b-f9ae08a0e301",
    "created_at": "2025-06-15T16:54:17.946453Z",
    "display_name": "Main Group",
    "errors": [],
    "external_type": "salto_ks_access_group",
    "external_type_display_name": "Salto KS Access Group",
    "is_managed": true,
    "name": "My Access Group",
    "pending_mutations": [],
    "warnings": [],
    "workspace_id": "ac19352c-869a-4209-9ce7-44c740a8b5d0"
  }
  ```
</ResponseExample>

***

## Properties

<ResponseField name="access_group_type" type="Enum (String)">
  **Deprecated**. Use `external_type`.

  The access group type.
</ResponseField>

<ResponseField name="access_group_type_display_name" type="String">
  **Deprecated**. Use `external_type_display_name`.

  The access group type display name.
</ResponseField>

<ResponseField name="access_schedule" type="Object">
  `starts_at` and `ends_at` timestamps for the access group's access.

  <Expandable title="properties">
    <ResponseField name="ends_at" type="String (ISO 8601)">
      Date and time at which the user's access ends, in [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) format.
    </ResponseField>

    <ResponseField name="starts_at" type="String (ISO 8601)">
      Date and time at which the user's access starts, in [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) format.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="acs_access_group_id" type="String (UUID)">
  ID of the access group.
</ResponseField>

<ResponseField name="acs_system_id" type="String (UUID)">
  ID of the access control system that contains the access group.
</ResponseField>

<ResponseField name="connected_account_id" type="String (UUID)">
  ID of the connected account that contains the access group.
</ResponseField>

<ResponseField name="created_at" type="String (ISO 8601)">
  Date and time at which the access group was created.
</ResponseField>

<ResponseField name="display_name" type="String">
  Display name for the access group.
</ResponseField>

<ResponseField name="errors" type="Array">
  Errors associated with the `acs_access_group`.
</ResponseField>

<ResponseField name="external_type" type="Enum (String)">
  Brand-specific terminology for the access group type.
</ResponseField>

<ResponseField name="external_type_display_name" type="String">
  Display name that corresponds to the brand-specific terminology for the access group type.
</ResponseField>

<ResponseField name="is_managed" type="Boolean">
  Indicates whether Seam manages the access group.
</ResponseField>

<ResponseField name="name" type="String">
  Name of the access group.
</ResponseField>

<ResponseField name="pending_mutations" type="Array">
  Collection of pending mutations for the access group. Represents operations that have been requested but not yet completed on the integrated access system.
</ResponseField>

<ResponseField name="warnings" type="Array">
  Warnings associated with the `acs_access_group`.

  <Expandable title="properties">
    <ResponseField name="created_at" type="String (ISO 8601)">
      Date and time at which Seam created the warning.
    </ResponseField>

    <ResponseField name="message" type="String">
      Detailed description of the warning. Provides insights into the issue and potentially how to rectify it.
    </ResponseField>

    <ResponseField name="warning_code" type="Enum (String)">
      Unique identifier of the type of warning. Enables quick recognition and categorization of the issue.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="workspace_id" type="String (UUID)">
  ID of the workspace that contains the access group.
</ResponseField>


# Remove an ACS User from an Access Group
Source: https://docs.seam.co/api/acs/access_groups/remove_user

/openapi.json post /acs/access_groups/remove_user
Removes a specified [access system user](/low-level-apis/access-systems/user-management) from a specified [access group](/low-level-apis/access-systems/user-management/assigning-users-to-access-groups).



# Assign a Credential to an ACS User
Source: https://docs.seam.co/api/acs/credentials/assign

/openapi.json post /acs/credentials/assign
Assigns a specified [credential](/low-level-apis/access-systems/managing-credentials) to a specified [access system user](/low-level-apis/access-systems/user-management).



# Create a Credential for an ACS User
Source: https://docs.seam.co/api/acs/credentials/create

/openapi.json post /acs/credentials/create
Creates a new [credential](/low-level-apis/access-systems/managing-credentials) for a specified [ACS user](/low-level-apis/access-systems/user-management). For granting access, we recommend [Access Grants](/use-cases/granting-access) instead: they create and manage the underlying credentials for you, across access systems and standalone smart locks alike. Use this low-level endpoint only when you need direct control over an individual ACS credential.



# Delete a Credential
Source: https://docs.seam.co/api/acs/credentials/delete

/openapi.json post /acs/credentials/delete
Deletes a specified [credential](/low-level-apis/access-systems/managing-credentials).



# Credential Warnings
Source: https://docs.seam.co/api/acs/credentials/errors

Warnings that Seam reports on the Credential resource, each with its code and meaning.

## Warnings

Each warning is an object with the following shape:

```json Example warning theme={null}
{
  "warning_code": "waiting_to_be_issued",
  "message": "Indicates that the credential is waiting to be issued.",
  "created_at": "2025-01-01T00:00:00.000Z"
}
```

<Accordion title="Warning object properties">
  <ResponseField name="warning_code" type="Enum (String)">
    Unique identifier of the type of warning. Enables quick recognition and categorization of the issue.

    One of the warning codes listed below.
  </ResponseField>

  <ResponseField name="message" type="String">
    Detailed description of the warning. Provides insights into the issue and potentially how to rectify it.
  </ResponseField>

  <ResponseField name="created_at" type="String (ISO 8601)">
    Date and time at which Seam created the warning.
  </ResponseField>
</Accordion>

### `being_deleted`

Indicates that the [credential](/low-level-apis/access-systems/managing-credentials) is being deleted.

***

### `needs_to_be_reissued`

Access permissions for the [credential](/low-level-apis/access-systems/managing-credentials) have changed. [Reissue](/low-level-apis/access-systems/working-with-card-encoders-and-scanners/creating-and-encoding-card-based-credentials) (re-encode) the credential. This issue may affect the proper functioning of the credential.

***

### `schedule_externally_modified`

Indicates that the schedule of one of the [credential](/low-level-apis/access-systems/managing-credentials)'s children was modified externally.

***

### `schedule_modified`

Indicates that the schedule of the [credential](/low-level-apis/access-systems/managing-credentials) was modified to avoid creating a credential with a start date in the past.

***

### `unknown_issue_with_acs_credential`

An unknown issue occurred while syncing the state of the [credential](/low-level-apis/access-systems/managing-credentials) with the provider. This issue may affect the proper functioning of the credential.

***

### `waiting_to_be_issued`

Indicates that the [credential](/low-level-apis/access-systems/managing-credentials) is waiting to be issued.

***


# Credential Events
Source: https://docs.seam.co/api/acs/credentials/events

Webhook events that Seam emits for the Credential resource, with example payloads and properties.

## `acs_credential.deleted`

An [access system credential](/low-level-apis/access-systems/managing-credentials) was deleted.

<ResponseExample>
  ```json Example webhook payload theme={null}
  {
    "acs_credential_id": "00000000-0000-0000-0000-000000000000",
    "acs_system_id": "00000000-0000-0000-0000-000000000000",
    "connected_account_id": "00000000-0000-0000-0000-000000000000",
    "created_at": "2025-01-01T00:00:00.000Z",
    "event_description": "An [access system credential](/low-level-apis/access-systems/managing-credentials) was deleted.",
    "event_id": "00000000-0000-0000-0000-000000000000",
    "event_type": "acs_credential.deleted",
    "occurred_at": "2025-01-01T00:00:00.000Z",
    "workspace_id": "00000000-0000-0000-0000-000000000000"
  }
  ```
</ResponseExample>

<Accordion title="Properties">
  <ResponseField name="acs_credential_id" type="String (UUID)">
    ID of the affected credential.
  </ResponseField>

  <ResponseField name="acs_system_id" type="String (UUID)">
    ID of the access system.
  </ResponseField>

  <ResponseField name="connected_account_id" type="String (UUID)">
    ID of the connected account.
  </ResponseField>

  <ResponseField name="created_at" type="String (ISO 8601)">
    Date and time at which the event was created.
  </ResponseField>

  <ResponseField name="event_description" type="String">
    Human-readable description of the event. Persisted when the event is created (so the creating code, including a provider, can supply a tailored description) and otherwise derived from the event.
  </ResponseField>

  <ResponseField name="event_id" type="String (UUID)">
    ID of the event.
  </ResponseField>

  <ResponseField name="event_type" type="Enum (String)">
    Value: `acs_credential.deleted`
  </ResponseField>

  <ResponseField name="occurred_at" type="String (ISO 8601)">
    Date and time at which the event occurred.
  </ResponseField>

  <ResponseField name="workspace_id" type="String (UUID)">
    ID of the workspace associated with the event.
  </ResponseField>
</Accordion>

## `acs_credential.issued`

An [access system credential](/low-level-apis/access-systems/managing-credentials) was issued.

<ResponseExample>
  ```json Example webhook payload theme={null}
  {
    "acs_credential_id": "00000000-0000-0000-0000-000000000000",
    "acs_system_id": "00000000-0000-0000-0000-000000000000",
    "connected_account_id": "00000000-0000-0000-0000-000000000000",
    "created_at": "2025-01-01T00:00:00.000Z",
    "event_description": "An [access system credential](/low-level-apis/access-systems/managing-credentials) was issued.",
    "event_id": "00000000-0000-0000-0000-000000000000",
    "event_type": "acs_credential.issued",
    "occurred_at": "2025-01-01T00:00:00.000Z",
    "workspace_id": "00000000-0000-0000-0000-000000000000"
  }
  ```
</ResponseExample>

<Accordion title="Properties">
  <ResponseField name="acs_credential_id" type="String (UUID)">
    ID of the affected credential.
  </ResponseField>

  <ResponseField name="acs_system_id" type="String (UUID)">
    ID of the access system.
  </ResponseField>

  <ResponseField name="connected_account_id" type="String (UUID)">
    ID of the connected account.
  </ResponseField>

  <ResponseField name="created_at" type="String (ISO 8601)">
    Date and time at which the event was created.
  </ResponseField>

  <ResponseField name="event_description" type="String">
    Human-readable description of the event. Persisted when the event is created (so the creating code, including a provider, can supply a tailored description) and otherwise derived from the event.
  </ResponseField>

  <ResponseField name="event_id" type="String (UUID)">
    ID of the event.
  </ResponseField>

  <ResponseField name="event_type" type="Enum (String)">
    Value: `acs_credential.issued`
  </ResponseField>

  <ResponseField name="occurred_at" type="String (ISO 8601)">
    Date and time at which the event occurred.
  </ResponseField>

  <ResponseField name="workspace_id" type="String (UUID)">
    ID of the workspace associated with the event.
  </ResponseField>
</Accordion>

## `acs_credential.reissued`

An [access system credential](/low-level-apis/access-systems/managing-credentials) was reissued.

<ResponseExample>
  ```json Example webhook payload theme={null}
  {
    "acs_credential_id": "00000000-0000-0000-0000-000000000000",
    "acs_system_id": "00000000-0000-0000-0000-000000000000",
    "connected_account_id": "00000000-0000-0000-0000-000000000000",
    "created_at": "2025-01-01T00:00:00.000Z",
    "event_description": "An [access system credential](/low-level-apis/access-systems/managing-credentials) was reissued.",
    "event_id": "00000000-0000-0000-0000-000000000000",
    "event_type": "acs_credential.reissued",
    "occurred_at": "2025-01-01T00:00:00.000Z",
    "workspace_id": "00000000-0000-0000-0000-000000000000"
  }
  ```
</ResponseExample>

<Accordion title="Properties">
  <ResponseField name="acs_credential_id" type="String (UUID)">
    ID of the affected credential.
  </ResponseField>

  <ResponseField name="acs_system_id" type="String (UUID)">
    ID of the access system.
  </ResponseField>

  <ResponseField name="connected_account_id" type="String (UUID)">
    ID of the connected account.
  </ResponseField>

  <ResponseField name="created_at" type="String (ISO 8601)">
    Date and time at which the event was created.
  </ResponseField>

  <ResponseField name="event_description" type="String">
    Human-readable description of the event. Persisted when the event is created (so the creating code, including a provider, can supply a tailored description) and otherwise derived from the event.
  </ResponseField>

  <ResponseField name="event_id" type="String (UUID)">
    ID of the event.
  </ResponseField>

  <ResponseField name="event_type" type="Enum (String)">
    Value: `acs_credential.reissued`
  </ResponseField>

  <ResponseField name="occurred_at" type="String (ISO 8601)">
    Date and time at which the event occurred.
  </ResponseField>

  <ResponseField name="workspace_id" type="String (UUID)">
    ID of the workspace associated with the event.
  </ResponseField>
</Accordion>

## `acs_credential.invalidated`

An [access system credential](/low-level-apis/access-systems/managing-credentials) was invalidated. That is, the credential cannot be used anymore.

<ResponseExample>
  ```json Example webhook payload theme={null}
  {
    "acs_credential_id": "00000000-0000-0000-0000-000000000000",
    "acs_system_id": "00000000-0000-0000-0000-000000000000",
    "connected_account_id": "00000000-0000-0000-0000-000000000000",
    "created_at": "2025-01-01T00:00:00.000Z",
    "event_description": "An [access system credential](/low-level-apis/access-systems/managing-credentials) was invalidated. That is, the credential cannot be used anymore.",
    "event_id": "00000000-0000-0000-0000-000000000000",
    "event_type": "acs_credential.invalidated",
    "occurred_at": "2025-01-01T00:00:00.000Z",
    "workspace_id": "00000000-0000-0000-0000-000000000000"
  }
  ```
</ResponseExample>

<Accordion title="Properties">
  <ResponseField name="acs_credential_id" type="String (UUID)">
    ID of the affected credential.
  </ResponseField>

  <ResponseField name="acs_system_id" type="String (UUID)">
    ID of the access system.
  </ResponseField>

  <ResponseField name="connected_account_id" type="String (UUID)">
    ID of the connected account.
  </ResponseField>

  <ResponseField name="created_at" type="String (ISO 8601)">
    Date and time at which the event was created.
  </ResponseField>

  <ResponseField name="event_description" type="String">
    Human-readable description of the event. Persisted when the event is created (so the creating code, including a provider, can supply a tailored description) and otherwise derived from the event.
  </ResponseField>

  <ResponseField name="event_id" type="String (UUID)">
    ID of the event.
  </ResponseField>

  <ResponseField name="event_type" type="Enum (String)">
    Value: `acs_credential.invalidated`
  </ResponseField>

  <ResponseField name="occurred_at" type="String (ISO 8601)">
    Date and time at which the event occurred.
  </ResponseField>

  <ResponseField name="workspace_id" type="String (UUID)">
    ID of the workspace associated with the event.
  </ResponseField>
</Accordion>


# Get a Credential
Source: https://docs.seam.co/api/acs/credentials/get

/openapi.json post /acs/credentials/get
Returns a specified [credential](/low-level-apis/access-systems/managing-credentials).



# List Credentials
Source: https://docs.seam.co/api/acs/credentials/list

/openapi.json post /acs/credentials/list
Returns a list of all [credentials](/low-level-apis/access-systems/managing-credentials).



# List Accessible Entrances
Source: https://docs.seam.co/api/acs/credentials/list_accessible_entrances

/openapi.json post /acs/credentials/list_accessible_entrances
Returns a list of all [entrances](/api/acs/entrances/object) to which a [credential](/api/acs/credentials/object) grants access.



# The Credential Object
Source: https://docs.seam.co/api/acs/credentials/object

Learn how the acs_credential object represents the means—such as key cards, mobile keys, or PIN codes—by which an access system user gains entry.

## The acs\_credential Object

Means by which an [access control system user](/low-level-apis/access-systems/user-management) gains access at an [entrance](/low-level-apis/access-systems/retrieving-entrance-details). The `acs_credential` object represents a [credential](/low-level-apis/access-systems/managing-credentials) that provides an ACS user access within an [access control system](/low-level-apis/access-systems).

An access control system generally uses digital means of access to authorize a user trying to get through a specific entrance. Examples of credentials include plastic key cards, mobile keys, biometric identifiers, and PIN codes. The electronic nature of these credentials, as well as the fact that access is centralized, enables both the rapid provisioning and rescinding of access and the ability to compile access audit logs.

For each `acs_credential`, you define the access method. You can also specify additional properties, such as a PIN code, depending on the credential type.

For granting a person access to a space, [Access Grants](/use-cases/granting-access) are the default and recommended approach. Use the lower-level ACS credential API directly only when you specifically need to manage individual credentials.

<ResponseExample>
  ```json ACS Card Credential theme={null}
  {
    "access_method": "card",
    "acs_credential_id": "73a0a199-024f-454d-a916-9bbda8502c12",
    "acs_system_id": "b1d03165-2759-474b-a342-e02223f27b39",
    "acs_user_id": "0fc82df4-391b-4d00-a234-86378f1c3952",
    "connected_account_id": "daba7bd0-edb6-4bb9-a70b-f9ae08a0e301",
    "card_number": "164d29dc4a09b65f",
    "created_at": "2025-06-16T16:54:17.946514Z",
    "display_name": "Guest Lock 1, Vingcard Lock 2",
    "ends_at": "2025-07-12T16:54:17.946512Z",
    "errors": [],
    "external_type": "visionline_card",
    "external_type_display_name": "Visionline Card",
    "is_issued": true,
    "is_latest_desired_state_synced_with_provider": true,
    "is_managed": true,
    "is_multi_phone_sync_credential": false,
    "issued_at": "2025-06-16T16:54:17.946512Z",
    "latest_desired_state_synced_with_provider_at": "2025-06-18T16:54:17.946514Z",
    "starts_at": "2025-07-10T16:54:17.946512Z",
    "visionline_metadata": {
      "card_function_type": "guest",
      "card_id": "5",
      "common_acs_entrance_ids": [
        "5f4e3d2c-1b0a-9f8e-7d6c-5b4a3c2d1e0f"
      ],
      "credential_id": "15",
      "guest_acs_entrance_ids": [
        "a1b2c3d4-e5f6-4a3b-2c1d-0e9f8a7b6c5d"
      ],
      "is_valid": true
    },
    "warnings": [],
    "workspace_id": "005f1e54-5360-40db-8c31-4ef6baaad1fd"
  }
  ```

  ```json ACS Mobile Key Credential theme={null}
  {
    "access_method": "mobile_key",
    "acs_credential_id": "73a0a199-024f-454d-a916-9bbda8502c12",
    "acs_system_id": "b1d03165-2759-474b-a342-e02223f27b39",
    "acs_user_id": "0fc82df4-391b-4d00-a234-86378f1c3952",
    "connected_account_id": "1b9a3e0d-443f-4063-b619-4ca7e2a97751",
    "created_at": "2025-06-16T16:54:17.946514Z",
    "display_name": "Front Door",
    "errors": [],
    "is_managed": true,
    "is_multi_phone_sync_credential": true,
    "is_one_time_use": false,
    "warnings": [],
    "workspace_id": "005f1e54-5360-40db-8c31-4ef6baaad1fd"
  }
  ```

  ```json ACS PIN Code Credential theme={null}
  {
    "access_method": "code",
    "acs_credential_id": "73a0a199-024f-454d-a916-9bbda8502c12",
    "acs_system_id": "b1d03165-2759-474b-a342-e02223f27b39",
    "acs_user_id": "0fc82df4-391b-4d00-a234-86378f1c3952",
    "connected_account_id": "1b9a3e0d-443f-4063-b619-4ca7e2a97751",
    "code": "123456",
    "created_at": "2025-06-16T16:54:17.946514Z",
    "display_name": "FRONT_DOOR",
    "errors": [],
    "external_type": "salto_ks_credential",
    "external_type_display_name": "Salto KS Credential",
    "is_latest_desired_state_synced_with_provider": true,
    "is_managed": true,
    "is_multi_phone_sync_credential": false,
    "is_one_time_use": false,
    "latest_desired_state_synced_with_provider_at": "2025-06-18T16:54:17.946514Z",
    "starts_at": "2025-07-10T16:54:17.946512Z",
    "warnings": [],
    "workspace_id": "005f1e54-5360-40db-8c31-4ef6baaad1fd"
  }
  ```
</ResponseExample>

***

## Properties

<ResponseField name="access_method" type="Enum (String)">
  Access method for the [credential](/low-level-apis/access-systems/managing-credentials). Supported values: `code`, `card`, `mobile_key`, `cloud_key`.
</ResponseField>

<ResponseField name="acs_credential_id" type="String (UUID)">
  ID of the [credential](/low-level-apis/access-systems/managing-credentials).
</ResponseField>

<ResponseField name="acs_credential_pool_id" type="String (UUID)">
  ID of the credential pool to which the credential belongs.
</ResponseField>

<ResponseField name="acs_system_id" type="String (UUID)">
  ID of the [access control system](/low-level-apis/access-systems) that contains the [credential](/low-level-apis/access-systems/managing-credentials).
</ResponseField>

<ResponseField name="acs_user_id" type="String (UUID)">
  ID of the [ACS user](/low-level-apis/access-systems/user-management) to whom the [credential](/low-level-apis/access-systems/managing-credentials) belongs.
</ResponseField>

<ResponseField name="akiles_metadata" type="Object">
  Akiles-specific metadata for the [credential](/low-level-apis/access-systems/managing-credentials).

  <Expandable title="properties">
    <ResponseField name="member_pin_id" type="String">
      ID of the Akiles member PIN.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="assa_abloy_vostio_metadata" type="Object">
  Vostio-specific metadata for the [credential](/low-level-apis/access-systems/managing-credentials).

  <Expandable title="properties">
    <ResponseField name="auto_join" type="Boolean">
      Indicates whether the credential should auto-join. For an auto-join credential, Seam automatically issues an override card if there are no other cards and a joiner card if there are existing cards on the doors.
    </ResponseField>

    <ResponseField name="door_names" type="Array">
      Names of the doors to which to grant access in the Vostio access system.
    </ResponseField>

    <ResponseField name="endpoint_id" type="String">
      Endpoint ID in the Vostio access system.
    </ResponseField>

    <ResponseField name="key_id" type="String">
      Key ID in the Vostio access system.
    </ResponseField>

    <ResponseField name="key_issuing_request_id" type="String">
      Key issuing request ID in the Vostio access system.
    </ResponseField>

    <ResponseField name="override_guest_acs_entrance_ids" type="Array">
      IDs of the guest entrances to override in the Vostio access system.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="card_number" type="String">
  Number of the card associated with the [credential](/low-level-apis/access-systems/managing-credentials).
</ResponseField>

<ResponseField name="code" type="String">
  Access (PIN) code for the [credential](/low-level-apis/access-systems/managing-credentials).
</ResponseField>

<ResponseField name="connected_account_id" type="String (UUID)">
  ID of the [connected account](/core-concepts/connected-accounts) to which the [credential](/low-level-apis/access-systems/managing-credentials) belongs.
</ResponseField>

<ResponseField name="created_at" type="String (ISO 8601)">
  Date and time at which the [credential](/low-level-apis/access-systems/managing-credentials) was created.
</ResponseField>

<ResponseField name="display_name" type="String">
  Display name that corresponds to the [credential](/low-level-apis/access-systems/managing-credentials) type.
</ResponseField>

<ResponseField name="ends_at" type="String">
  Date and time at which the [credential](/low-level-apis/access-systems/managing-credentials) validity ends, in [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) format. Must be a time in the future and after `starts_at`.
</ResponseField>

<ResponseField name="errors" type="Array">
  Errors associated with the [credential](/low-level-apis/access-systems/managing-credentials).

  <Expandable title="properties">
    <ResponseField name="created_at" type="String (ISO 8601)">
      Date and time at which Seam created the error.
    </ResponseField>

    <ResponseField name="error_code" type="String">
      The error code.
    </ResponseField>

    <ResponseField name="message" type="String">
      The message.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="external_type" type="Enum (String)">
  Brand-specific terminology for the [credential](/low-level-apis/access-systems/managing-credentials) type. Supported values: `pti_card`, `brivo_credential`, `hid_credential`, `visionline_card`.
</ResponseField>

<ResponseField name="external_type_display_name" type="String">
  Display name that corresponds to the brand-specific terminology for the [credential](/low-level-apis/access-systems/managing-credentials) type.
</ResponseField>

<ResponseField name="is_issued" type="Boolean">
  Indicates whether the [credential](/low-level-apis/access-systems/managing-credentials) has been encoded onto a card.
</ResponseField>

<ResponseField name="is_latest_desired_state_synced_with_provider" type="Boolean">
  Indicates whether the latest state of the [credential](/low-level-apis/access-systems/managing-credentials) has been synced from Seam to the provider.
</ResponseField>

<ResponseField name="is_managed" type="Boolean">
  Indicates whether Seam manages the credential.
</ResponseField>

<ResponseField name="is_multi_phone_sync_credential" type="Boolean">
  Indicates whether the [credential](/low-level-apis/access-systems/managing-credentials) is a [multi-phone sync credential](/capability-guides/mobile-access/issuing-mobile-credentials-from-an-access-control-system#what-are-multi-phone-sync-credentials).
</ResponseField>

<ResponseField name="is_one_time_use" type="Boolean">
  Indicates whether the [credential](/low-level-apis/access-systems/managing-credentials) can only be used once. If `true`, the code becomes invalid after the first use.
</ResponseField>

<ResponseField name="issued_at" type="String (ISO 8601)">
  Date and time at which the [credential](/low-level-apis/access-systems/managing-credentials) was encoded onto a card.
</ResponseField>

<ResponseField name="latest_desired_state_synced_with_provider_at" type="String (ISO 8601)">
  Date and time at which the state of the [credential](/low-level-apis/access-systems/managing-credentials) was most recently synced from Seam to the provider.
</ResponseField>

<ResponseField name="parent_acs_credential_id" type="String (UUID)">
  ID of the parent [credential](/low-level-apis/access-systems/managing-credentials).
</ResponseField>

<ResponseField name="starts_at" type="String">
  Date and time at which the [credential](/low-level-apis/access-systems/managing-credentials) validity starts, in [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) format.
</ResponseField>

<ResponseField name="user_identity_id" type="String (UUID)">
  ID of the [user identity](/api/user_identities/object) to whom the [credential](/low-level-apis/access-systems/managing-credentials) belongs.
</ResponseField>

<ResponseField name="visionline_metadata" type="Object">
  Visionline-specific metadata for the [credential](/low-level-apis/access-systems/managing-credentials).

  <Expandable title="properties">
    <ResponseField name="auto_join" type="Boolean">
      Indicates whether the credential should auto-join. For an auto-join credential, Seam automatically issues an override card if there are no other cards and a joiner card if there are existing cards on the doors.
    </ResponseField>

    <ResponseField name="card_function_type" type="Enum (String)">
      Card function type in the Visionline access system.
    </ResponseField>

    <ResponseField name="card_id" type="String">
      ID of the card in the Visionline access system.
    </ResponseField>

    <ResponseField name="common_acs_entrance_ids" type="Array">
      Common entrance IDs in the Visionline access system.
    </ResponseField>

    <ResponseField name="credential_id" type="String">
      ID of the credential in the Visionline access system.
    </ResponseField>

    <ResponseField name="guest_acs_entrance_ids" type="Array">
      Guest entrance IDs in the Visionline access system.
    </ResponseField>

    <ResponseField name="is_valid" type="Boolean">
      Indicates whether the credential is valid.
    </ResponseField>

    <ResponseField name="joiner_acs_credential_ids" type="Array">
      IDs of the credentials to which you want to join.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="warnings" type="Array">
  Warnings associated with the [credential](/low-level-apis/access-systems/managing-credentials).
</ResponseField>

<ResponseField name="workspace_id" type="String (UUID)">
  ID of the workspace that contains the [credential](/low-level-apis/access-systems/managing-credentials).
</ResponseField>


# Unassign a Credential from an ACS User
Source: https://docs.seam.co/api/acs/credentials/unassign

/openapi.json post /acs/credentials/unassign
Unassigns a specified [credential](/low-level-apis/access-systems/managing-credentials) from a specified [access system user](/low-level-apis/access-systems/user-management).



# Update a Credential
Source: https://docs.seam.co/api/acs/credentials/update

/openapi.json post /acs/credentials/update
Updates the code and ends at date and time for a specified [credential](/low-level-apis/access-systems/managing-credentials).



# Encode a Credential
Source: https://docs.seam.co/api/acs/encoders/encode_credential

/openapi.json post /acs/encoders/encode_credential
Encodes an existing [credential](/low-level-apis/access-systems/managing-credentials) onto a plastic card placed on the specified [encoder](/low-level-apis/access-systems/working-with-card-encoders-and-scanners). Either provide an `acs_credential_id` or an `access_method_id`



# Encoder Events
Source: https://docs.seam.co/api/acs/encoders/events

Webhook events that Seam emits for the Encoder resource, with example payloads and properties.

## `acs_encoder.added`

An [access system encoder](/low-level-apis/access-systems/working-with-card-encoders-and-scanners) was added.

<ResponseExample>
  ```json Example webhook payload theme={null}
  {
    "acs_encoder_id": "00000000-0000-0000-0000-000000000000",
    "acs_system_id": "00000000-0000-0000-0000-000000000000",
    "connected_account_id": "00000000-0000-0000-0000-000000000000",
    "created_at": "2025-01-01T00:00:00.000Z",
    "event_description": "An [access system encoder](/low-level-apis/access-systems/working-with-card-encoders-and-scanners) was added.",
    "event_id": "00000000-0000-0000-0000-000000000000",
    "event_type": "acs_encoder.added",
    "occurred_at": "2025-01-01T00:00:00.000Z",
    "workspace_id": "00000000-0000-0000-0000-000000000000"
  }
  ```
</ResponseExample>

<Accordion title="Properties">
  <ResponseField name="acs_encoder_id" type="String (UUID)">
    ID of the affected encoder.
  </ResponseField>

  <ResponseField name="acs_system_id" type="String (UUID)">
    ID of the access system.
  </ResponseField>

  <ResponseField name="connected_account_id" type="String (UUID)">
    ID of the connected account.
  </ResponseField>

  <ResponseField name="created_at" type="String (ISO 8601)">
    Date and time at which the event was created.
  </ResponseField>

  <ResponseField name="event_description" type="String">
    Human-readable description of the event. Persisted when the event is created (so the creating code, including a provider, can supply a tailored description) and otherwise derived from the event.
  </ResponseField>

  <ResponseField name="event_id" type="String (UUID)">
    ID of the event.
  </ResponseField>

  <ResponseField name="event_type" type="Enum (String)">
    Value: `acs_encoder.added`
  </ResponseField>

  <ResponseField name="occurred_at" type="String (ISO 8601)">
    Date and time at which the event occurred.
  </ResponseField>

  <ResponseField name="workspace_id" type="String (UUID)">
    ID of the workspace associated with the event.
  </ResponseField>
</Accordion>

## `acs_encoder.removed`

An [access system encoder](/low-level-apis/access-systems/working-with-card-encoders-and-scanners) was removed.

<ResponseExample>
  ```json Example webhook payload theme={null}
  {
    "acs_encoder_id": "00000000-0000-0000-0000-000000000000",
    "acs_system_id": "00000000-0000-0000-0000-000000000000",
    "connected_account_id": "00000000-0000-0000-0000-000000000000",
    "created_at": "2025-01-01T00:00:00.000Z",
    "event_description": "An [access system encoder](/low-level-apis/access-systems/working-with-card-encoders-and-scanners) was removed.",
    "event_id": "00000000-0000-0000-0000-000000000000",
    "event_type": "acs_encoder.removed",
    "occurred_at": "2025-01-01T00:00:00.000Z",
    "workspace_id": "00000000-0000-0000-0000-000000000000"
  }
  ```
</ResponseExample>

<Accordion title="Properties">
  <ResponseField name="acs_encoder_id" type="String (UUID)">
    ID of the affected encoder.
  </ResponseField>

  <ResponseField name="acs_system_id" type="String (UUID)">
    ID of the access system.
  </ResponseField>

  <ResponseField name="connected_account_id" type="String (UUID)">
    ID of the connected account.
  </ResponseField>

  <ResponseField name="created_at" type="String (ISO 8601)">
    Date and time at which the event was created.
  </ResponseField>

  <ResponseField name="event_description" type="String">
    Human-readable description of the event. Persisted when the event is created (so the creating code, including a provider, can supply a tailored description) and otherwise derived from the event.
  </ResponseField>

  <ResponseField name="event_id" type="String (UUID)">
    ID of the event.
  </ResponseField>

  <ResponseField name="event_type" type="Enum (String)">
    Value: `acs_encoder.removed`
  </ResponseField>

  <ResponseField name="occurred_at" type="String (ISO 8601)">
    Date and time at which the event occurred.
  </ResponseField>

  <ResponseField name="workspace_id" type="String (UUID)">
    ID of the workspace associated with the event.
  </ResponseField>
</Accordion>


# Get an Encoder
Source: https://docs.seam.co/api/acs/encoders/get

/openapi.json post /acs/encoders/get
Returns a specified [encoder](/low-level-apis/access-systems/working-with-card-encoders-and-scanners).



# List Encoders
Source: https://docs.seam.co/api/acs/encoders/list

/openapi.json post /acs/encoders/list
Returns a list of all [encoders](/low-level-apis/access-systems/working-with-card-encoders-and-scanners).



# The Encoder Object
Source: https://docs.seam.co/api/acs/encoders/object

Learn how the acs_encoder object represents a hardware device that encodes credential data onto physical key cards within an access control system.

## The acs\_encoder Object

Represents a hardware device that encodes [credential](/low-level-apis/access-systems/managing-credentials) data onto physical cards within an [access control system](/low-level-apis/access-systems).

Some access control systems require credentials to be encoded onto plastic key cards using a card encoder. This process involves the following two key steps:

1. Credential creation
   Configure the access parameters for the credential.
2. Card encoding
   Write the credential data onto the card using a compatible card encoder.

Separately, the Seam API also supports card scanning, which enables you to scan and read the encoded data on a card. You can use this action to confirm consistency with access control system records or diagnose discrepancies if needed.

See [Working with Card Encoders and Scanners](/low-level-apis/access-systems/working-with-card-encoders-and-scanners).

To verify if your access control system requires a card encoder, see the corresponding [system integration guide](/device-and-system-integration-guides#access-control-systems).

<ResponseExample>
  ```json ACS Encoder theme={null}
  {
    "acs_encoder_id": "681da2d6-4ac6-4b33-8c03-86281b761325",
    "acs_system_id": "c85406d2-214f-4e11-8000-a2e5b5a362a4",
    "connected_account_id": "1b9a3e0d-443f-4063-b619-4ca7e2a97750",
    "created_at": "2025-06-16T16:54:17.946527Z",
    "display_name": "Encoder 1",
    "errors": [],
    "workspace_id": "f863ac85-2c4e-49ae-8679-3ec2417f1d62"
  }
  ```
</ResponseExample>

***

## Properties

<ResponseField name="acs_encoder_id" type="String (UUID)">
  ID of the [encoder](/low-level-apis/access-systems/working-with-card-encoders-and-scanners).
</ResponseField>

<ResponseField name="acs_system_id" type="String (UUID)">
  ID of the [access control system](/low-level-apis/access-systems) that contains the [encoder](/low-level-apis/access-systems/working-with-card-encoders-and-scanners).
</ResponseField>

<ResponseField name="connected_account_id" type="String (UUID)">
  ID of the connected account that contains the [encoder](/low-level-apis/access-systems/working-with-card-encoders-and-scanners).
</ResponseField>

<ResponseField name="created_at" type="String (ISO 8601)">
  Date and time at which the [encoder](/low-level-apis/access-systems/working-with-card-encoders-and-scanners) was created.
</ResponseField>

<ResponseField name="display_name" type="String">
  Display name for the [encoder](/low-level-apis/access-systems/working-with-card-encoders-and-scanners).
</ResponseField>

<ResponseField name="errors" type="Array">
  Errors associated with the [encoder](/low-level-apis/access-systems/working-with-card-encoders-and-scanners).

  <Expandable title="properties">
    <ResponseField name="created_at" type="String (ISO 8601)">
      Date and time at which Seam created the error.
    </ResponseField>

    <ResponseField name="error_code" type="Enum (String)">
      Unique identifier of the type of error. Enables quick recognition and categorization of the issue.
    </ResponseField>

    <ResponseField name="message" type="String">
      Detailed description of the error. Provides insights into the issue and potentially how to rectify it.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="workspace_id" type="String (UUID)">
  ID of the workspace that contains the [encoder](/low-level-apis/access-systems/working-with-card-encoders-and-scanners).
</ResponseField>


# Scan a Credential
Source: https://docs.seam.co/api/acs/encoders/scan_credential

/openapi.json post /acs/encoders/scan_credential
Scans an encoded [acs_credential](/low-level-apis/access-systems/managing-credentials) from a plastic card placed on the specified [encoder](/low-level-apis/access-systems/working-with-card-encoders-and-scanners).



# Scan to Assign a Credential
Source: https://docs.seam.co/api/acs/encoders/scan_to_assign_credential

/openapi.json post /acs/encoders/scan_to_assign_credential
Scans a physical card placed on the specified [encoder](/low-level-apis/access-systems/working-with-card-encoders-and-scanners) and assigns the scanned credential to an ACS user. Provide either an `acs_user_id` or a `user_identity_id`.



# Simulate that the Next Credential Encoding Will Fail
Source: https://docs.seam.co/api/acs/encoders/simulate/next_credential_encode_will_fail

/openapi.json post /acs/encoders/simulate/next_credential_encode_will_fail
Simulates that the next attempt to encode a [credential](/low-level-apis/access-systems/managing-credentials) using the specified [encoder](/low-level-apis/access-systems/working-with-card-encoders-and-scanners) will fail. You can only perform this action within a [sandbox workspace](/core-concepts/workspaces#sandbox-workspaces).



# Simulate that the Next Credential Encoding Will Succeed
Source: https://docs.seam.co/api/acs/encoders/simulate/next_credential_encode_will_succeed

/openapi.json post /acs/encoders/simulate/next_credential_encode_will_succeed
Simulates that the next attempt to encode a [credential](/low-level-apis/access-systems/managing-credentials) using the specified [encoder](/low-level-apis/access-systems/working-with-card-encoders-and-scanners) will succeed. You can only perform this action within a [sandbox workspace](/core-concepts/workspaces#sandbox-workspaces).



# Simulate that the Next Credential Scan Will Fail
Source: https://docs.seam.co/api/acs/encoders/simulate/next_credential_scan_will_fail

/openapi.json post /acs/encoders/simulate/next_credential_scan_will_fail
Simulates that the next attempt to scan a [credential](/low-level-apis/access-systems/managing-credentials) using the specified [encoder](/low-level-apis/access-systems/working-with-card-encoders-and-scanners) will fail. You can only perform this action within a [sandbox workspace](/core-concepts/workspaces#sandbox-workspaces).



# Simulate that the Next Credential Scan Will Succeed
Source: https://docs.seam.co/api/acs/encoders/simulate/next_credential_scan_will_succeed

/openapi.json post /acs/encoders/simulate/next_credential_scan_will_succeed
Simulates that the next attempt to scan a [credential](/low-level-apis/access-systems/managing-credentials) using the specified [encoder](/low-level-apis/access-systems/working-with-card-encoders-and-scanners) will succeed. You can only perform this action within a [sandbox workspace](/core-concepts/workspaces#sandbox-workspaces).



# Entrance Warnings
Source: https://docs.seam.co/api/acs/entrances/errors

Warnings that Seam reports on the Entrance resource, each with its code and meaning.

## Warnings

Each warning is an object with the following shape:

```json Example warning theme={null}
{
  "warning_code": "salto_ks_entrance_access_code_support_removed",
  "message": "Indicates that a change in the reported device model has been detected for this Salto KS entrance, which may occur after an IQ hub reset. Access code support may be affected. See https://help.getseam.com/articles/5098842588-salto-ks-lock-loses-access-code-support for troubleshooting steps.",
  "created_at": "2025-01-01T00:00:00.000Z"
}
```

<Accordion title="Warning object properties">
  <ResponseField name="warning_code" type="Enum (String)">
    Unique identifier of the type of warning. Enables quick recognition and categorization of the issue.

    One of the warning codes listed below.
  </ResponseField>

  <ResponseField name="message" type="String">
    Detailed description of the warning. Provides insights into the issue and potentially how to rectify it.
  </ResponseField>

  <ResponseField name="created_at" type="String (ISO 8601)">
    Date and time at which Seam created the warning.
  </ResponseField>
</Accordion>

### `entrance_setup_required`

Indicates that this entrance requires additional configuration in the access control system before Seam can fully manage it.

***

### `entrance_shares_zone`

Indicates that this entrance shares a zone with other entrances in Avigilon Alta and cannot be added to an access group individually.

***

### `privacy_mode`

Indicates that this entrance is in privacy mode. When privacy mode is enabled, access codes, mobile keys, and remote unlocks will not work unless the user has admin access.

***

### `salto_ks_entrance_access_code_support_removed`

Indicates that a change in the reported device model has been detected for this Salto KS entrance, which may occur after an IQ hub reset. Access code support may be affected. See [https://help.getseam.com/articles/5098842588-salto-ks-lock-loses-access-code-support](https://help.getseam.com/articles/5098842588-salto-ks-lock-loses-access-code-support) for troubleshooting steps.

***

### `salto_ks_privacy_mode`

Indicates that this entrance is in privacy mode. When privacy mode is enabled, access codes, mobile keys, and remote unlocks will not work unless the user has admin access.

***


# Entrance Events
Source: https://docs.seam.co/api/acs/entrances/events

Webhook events that Seam emits for the Entrance resource, with example payloads and properties.

## `acs_entrance.added`

An [access system entrance](/low-level-apis/access-systems/retrieving-entrance-details) was added.

<ResponseExample>
  ```json Example webhook payload theme={null}
  {
    "acs_entrance_id": "00000000-0000-0000-0000-000000000000",
    "acs_system_id": "00000000-0000-0000-0000-000000000000",
    "connected_account_id": "00000000-0000-0000-0000-000000000000",
    "created_at": "2025-01-01T00:00:00.000Z",
    "event_description": "An [access system entrance](/low-level-apis/access-systems/retrieving-entrance-details) was added.",
    "event_id": "00000000-0000-0000-0000-000000000000",
    "event_type": "acs_entrance.added",
    "occurred_at": "2025-01-01T00:00:00.000Z",
    "workspace_id": "00000000-0000-0000-0000-000000000000"
  }
  ```
</ResponseExample>

<Accordion title="Properties">
  <ResponseField name="acs_entrance_id" type="String (UUID)">
    ID of the affected entrance.
  </ResponseField>

  <ResponseField name="acs_system_id" type="String (UUID)">
    ID of the access system.
  </ResponseField>

  <ResponseField name="connected_account_id" type="String (UUID)">
    ID of the connected account.
  </ResponseField>

  <ResponseField name="created_at" type="String (ISO 8601)">
    Date and time at which the event was created.
  </ResponseField>

  <ResponseField name="event_description" type="String">
    Human-readable description of the event. Persisted when the event is created (so the creating code, including a provider, can supply a tailored description) and otherwise derived from the event.
  </ResponseField>

  <ResponseField name="event_id" type="String (UUID)">
    ID of the event.
  </ResponseField>

  <ResponseField name="event_type" type="Enum (String)">
    Value: `acs_entrance.added`
  </ResponseField>

  <ResponseField name="occurred_at" type="String (ISO 8601)">
    Date and time at which the event occurred.
  </ResponseField>

  <ResponseField name="workspace_id" type="String (UUID)">
    ID of the workspace associated with the event.
  </ResponseField>
</Accordion>

## `acs_entrance.removed`

An [access system entrance](/low-level-apis/access-systems/retrieving-entrance-details) was removed.

<ResponseExample>
  ```json Example webhook payload theme={null}
  {
    "acs_entrance_id": "00000000-0000-0000-0000-000000000000",
    "acs_system_id": "00000000-0000-0000-0000-000000000000",
    "connected_account_id": "00000000-0000-0000-0000-000000000000",
    "created_at": "2025-01-01T00:00:00.000Z",
    "event_description": "An [access system entrance](/low-level-apis/access-systems/retrieving-entrance-details) was removed.",
    "event_id": "00000000-0000-0000-0000-000000000000",
    "event_type": "acs_entrance.removed",
    "occurred_at": "2025-01-01T00:00:00.000Z",
    "workspace_id": "00000000-0000-0000-0000-000000000000"
  }
  ```
</ResponseExample>

<Accordion title="Properties">
  <ResponseField name="acs_entrance_id" type="String (UUID)">
    ID of the affected entrance.
  </ResponseField>

  <ResponseField name="acs_system_id" type="String (UUID)">
    ID of the access system.
  </ResponseField>

  <ResponseField name="connected_account_id" type="String (UUID)">
    ID of the connected account.
  </ResponseField>

  <ResponseField name="created_at" type="String (ISO 8601)">
    Date and time at which the event was created.
  </ResponseField>

  <ResponseField name="event_description" type="String">
    Human-readable description of the event. Persisted when the event is created (so the creating code, including a provider, can supply a tailored description) and otherwise derived from the event.
  </ResponseField>

  <ResponseField name="event_id" type="String (UUID)">
    ID of the event.
  </ResponseField>

  <ResponseField name="event_type" type="Enum (String)">
    Value: `acs_entrance.removed`
  </ResponseField>

  <ResponseField name="occurred_at" type="String (ISO 8601)">
    Date and time at which the event occurred.
  </ResponseField>

  <ResponseField name="workspace_id" type="String (UUID)">
    ID of the workspace associated with the event.
  </ResponseField>
</Accordion>


# Get an Entrance
Source: https://docs.seam.co/api/acs/entrances/get

/openapi.json post /acs/entrances/get
Returns a specified [access system entrance](/low-level-apis/access-systems/retrieving-entrance-details).



# Grant an ACS User Access to an Entrance
Source: https://docs.seam.co/api/acs/entrances/grant_access

/openapi.json post /acs/entrances/grant_access
Grants a specified [access system user](/low-level-apis/access-systems/user-management) access to a specified [access system entrance](/low-level-apis/access-systems/retrieving-entrance-details).



# List Entrances
Source: https://docs.seam.co/api/acs/entrances/list

/openapi.json post /acs/entrances/list
Returns a list of all [access system entrances](/low-level-apis/access-systems/retrieving-entrance-details).



# List Credentials with Access to an Entrance
Source: https://docs.seam.co/api/acs/entrances/list_credentials_with_access

/openapi.json post /acs/entrances/list_credentials_with_access
Returns a list of all [credentials](/low-level-apis/access-systems/managing-credentials) with access to a specified [entrance](/low-level-apis/access-systems/retrieving-entrance-details).



# The Entrance Object
Source: https://docs.seam.co/api/acs/entrances/object

Learn how the acs_entrance object represents a secured door, gate, or zone within an access control system, and how to list its credentials.

## The acs\_entrance Object

Represents an [entrance](/low-level-apis/access-systems/retrieving-entrance-details) within an [access control system](/low-level-apis/access-systems).

In an access control system, an entrance is a secured door, gate, zone, or other method of entry. You can list details for all the `acs_entrance` resources in your workspace or get these details for a specific `acs_entrance`. You can also list all entrances associated with a specific credential, and you can list all credentials associated with a specific entrance.

<ResponseExample>
  ```json ACS Entrance theme={null}
  {
    "acs_entrance_id": "f74e4879-5991-4e2f-a368-888983dcfbfc",
    "acs_system_id": "6a74a969-94ea-4383-b5cf-5e7da8c113d1",
    "connected_account_id": "1b9a3e0d-443f-4063-b619-4ca7e2a97751",
    "created_at": "2025-06-15T16:54:17.946495Z",
    "display_name": "Main Entrance",
    "errors": [],
    "space_ids": [],
    "visionline_metadata": {
      "door_category": "guest",
      "door_name": "Main Entrance",
      "profiles": [
        {
          "visionline_door_profile_id": "7f8e9d0a-1b2c-3d4e-5f6a-7b8c9d0e1f2a",
          "visionline_door_profile_type": "BLE"
        }
      ]
    },
    "warnings": []
  }
  ```
</ResponseExample>

***

## Properties

<ResponseField name="acs_entrance_id" type="String (UUID)">
  ID of the [entrance](/low-level-apis/access-systems/retrieving-entrance-details).
</ResponseField>

<ResponseField name="acs_system_id" type="String (UUID)">
  ID of the [access control system](/low-level-apis/access-systems) that contains the [entrance](/low-level-apis/access-systems/retrieving-entrance-details).
</ResponseField>

<ResponseField name="akiles_metadata" type="Object">
  Akiles-specific metadata associated with the [entrance](/low-level-apis/access-systems/retrieving-entrance-details).

  <Expandable title="properties">
    <ResponseField name="actions" type="Array">
      Actions the gadget exposes (for example, open).

      <Expandable title="properties">
        <ResponseField name="id" type="String">
          ID of the gadget action.
        </ResponseField>

        <ResponseField name="name" type="String">
          Name of the gadget action.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="gadget_id" type="String">
      ID of the Akiles gadget.
    </ResponseField>

    <ResponseField name="site_id" type="String">
      ID of the Akiles site the gadget belongs to.
    </ResponseField>

    <ResponseField name="site_name" type="String">
      Name of the Akiles site the gadget belongs to.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="assa_abloy_vostio_metadata" type="Object">
  ASSA ABLOY Vostio-specific metadata associated with the [entrance](/low-level-apis/access-systems/retrieving-entrance-details).

  <Expandable title="properties">
    <ResponseField name="door_name" type="String">
      Name of the door in the Vostio access system.
    </ResponseField>

    <ResponseField name="door_number" type="number">
      Number of the door in the Vostio access system.
    </ResponseField>

    <ResponseField name="door_type" type="Enum (String)">
      Type of the door in the Vostio access system.
    </ResponseField>

    <ResponseField name="pms_id" type="String">
      PMS ID of the door in the Vostio access system.
    </ResponseField>

    <ResponseField name="stand_open" type="Boolean">
      Indicates whether keys are allowed to set the door in stand open mode in the Vostio access system.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="avigilon_alta_metadata" type="Object">
  Avigilon Alta-specific metadata associated with the [entrance](/low-level-apis/access-systems/retrieving-entrance-details).

  <Expandable title="properties">
    <ResponseField name="entry_name" type="String">
      Entry name for an Avigilon Alta system.
    </ResponseField>

    <ResponseField name="entry_relays_total_count" type="number">
      Total count of entry relays for an Avigilon Alta system.
    </ResponseField>

    <ResponseField name="org_name" type="String">
      Organization name for an Avigilon Alta system.
    </ResponseField>

    <ResponseField name="site_id" type="number">
      Site ID for an Avigilon Alta system.
    </ResponseField>

    <ResponseField name="site_name" type="String">
      Site name for an Avigilon Alta system.
    </ResponseField>

    <ResponseField name="zone_id" type="number">
      Zone ID for an Avigilon Alta system.
    </ResponseField>

    <ResponseField name="zone_name" type="String">
      Zone name for an Avigilon Alta system.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="brivo_metadata" type="Object">
  Brivo-specific metadata associated with the [entrance](/low-level-apis/access-systems/retrieving-entrance-details).

  <Expandable title="properties">
    <ResponseField name="access_point_id" type="String">
      ID of the access point in the Brivo access system.
    </ResponseField>

    <ResponseField name="site_id" type="number">
      ID of the site that the access point belongs to.
    </ResponseField>

    <ResponseField name="site_name" type="String">
      Name of the site that the access point belongs to.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="can_belong_to_reservation" type="Boolean">
  Indicates whether the ACS entrance can belong to a reservation via an access\_grant.reservation\_key.
</ResponseField>

<ResponseField name="can_unlock_with_card" type="Boolean">
  Indicates whether the ACS entrance can be unlocked with card credentials.
</ResponseField>

<ResponseField name="can_unlock_with_cloud_key" type="Boolean">
  Indicates whether the ACS entrance can be unlocked with cloud key credentials.
</ResponseField>

<ResponseField name="can_unlock_with_code" type="Boolean">
  Indicates whether the ACS entrance can be unlocked with pin codes.
</ResponseField>

<ResponseField name="can_unlock_with_mobile_key" type="Boolean">
  Indicates whether the ACS entrance can be unlocked with mobile key credentials.
</ResponseField>

<ResponseField name="connected_account_id" type="String (UUID)">
  ID of the [connected account](/low-level-apis/access-systems/retrieving-entrance-details) associated with the [entrance](/low-level-apis/access-systems/retrieving-entrance-details).
</ResponseField>

<ResponseField name="created_at" type="String (ISO 8601)">
  Date and time at which the [entrance](/low-level-apis/access-systems/retrieving-entrance-details) was created.
</ResponseField>

<ResponseField name="display_name" type="String">
  Display name for the [entrance](/low-level-apis/access-systems/retrieving-entrance-details).
</ResponseField>

<ResponseField name="dormakaba_ambiance_metadata" type="Object">
  dormakaba Ambiance-specific metadata associated with the [entrance](/low-level-apis/access-systems/retrieving-entrance-details).

  <Expandable title="properties">
    <ResponseField name="access_point_name" type="String">
      Name of the access point in the dormakaba Ambiance access system.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="dormakaba_community_metadata" type="Object">
  dormakaba Community-specific metadata associated with the [entrance](/low-level-apis/access-systems/retrieving-entrance-details).

  <Expandable title="properties">
    <ResponseField name="access_point_profile" type="String">
      Type of access point profile in the dormakaba Community access system.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="errors" type="Array">
  Errors associated with the [entrance](/low-level-apis/access-systems/retrieving-entrance-details).

  <Expandable title="properties">
    <ResponseField name="created_at" type="String (ISO 8601)">
      Date and time at which Seam created the error.
    </ResponseField>

    <ResponseField name="error_code" type="String">
      Unique identifier of the type of error. Enables quick recognition and categorization of the issue.
    </ResponseField>

    <ResponseField name="message" type="String">
      Detailed description of the error. Provides insights into the issue and potentially how to rectify it.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="hotek_metadata" type="Object">
  Hotek-specific metadata associated with the [entrance](/low-level-apis/access-systems/retrieving-entrance-details).

  <Expandable title="properties">
    <ResponseField name="common_area_name" type="String">
      Display name of the entrance.
    </ResponseField>

    <ResponseField name="common_area_number" type="String">
      Display name of the entrance.
    </ResponseField>

    <ResponseField name="room_number" type="String">
      Room number of the entrance.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="is_locked" type="Boolean">
  Indicates whether the [entrance](/low-level-apis/access-systems/retrieving-entrance-details) is currently locked.
</ResponseField>

<ResponseField name="latch_metadata" type="Object">
  Latch-specific metadata associated with the [entrance](/low-level-apis/access-systems/retrieving-entrance-details).

  <Expandable title="properties">
    <ResponseField name="accessibility_type" type="String">
      Accessibility type in the Latch access system.
    </ResponseField>

    <ResponseField name="door_name" type="String">
      Name of the door in the Latch access system.
    </ResponseField>

    <ResponseField name="door_type" type="String">
      Type of the door in the Latch access system.
    </ResponseField>

    <ResponseField name="is_connected" type="Boolean">
      Indicates whether the entrance is connected.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="salto_ks_metadata" type="Object">
  Salto KS-specific metadata associated with the [entrance](/low-level-apis/access-systems/retrieving-entrance-details).

  <Expandable title="properties">
    <ResponseField name="battery_level" type="String">
      Battery level of the door access device.
    </ResponseField>

    <ResponseField name="door_name" type="String">
      Name of the door in the Salto KS access system.
    </ResponseField>

    <ResponseField name="intrusion_alarm" type="Boolean">
      Indicates whether an intrusion alarm is active on the door.
    </ResponseField>

    <ResponseField name="left_open_alarm" type="Boolean">
      Indicates whether the door is left open.
    </ResponseField>

    <ResponseField name="lock_type" type="String">
      Type of the lock in the Salto KS access system.
    </ResponseField>

    <ResponseField name="locked_state" type="String">
      Locked state of the door in the Salto KS access system.
    </ResponseField>

    <ResponseField name="online" type="Boolean">
      Indicates whether the door access device is online.
    </ResponseField>

    <ResponseField name="privacy_mode" type="Boolean">
      Indicates whether privacy mode is enabled for the lock.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="salto_space_metadata" type="Object">
  Salto Space-specific metadata associated with the [entrance](/low-level-apis/access-systems/retrieving-entrance-details).

  <Expandable title="properties">
    <ResponseField name="audit_on_keys" type="Boolean">
      Indicates whether AuditOnKeys is enabled for the door in the Salto Space access system.
    </ResponseField>

    <ResponseField name="door_description" type="String">
      Description of the door in the Salto Space access system.
    </ResponseField>

    <ResponseField name="door_id" type="String">
      Door ID in the Salto Space access system.
    </ResponseField>

    <ResponseField name="door_name" type="String">
      Name of the door in the Salto Space access system.
    </ResponseField>

    <ResponseField name="room_description" type="String">
      Description of the room in the Salto Space access system.
    </ResponseField>

    <ResponseField name="room_name" type="String">
      Name of the room in the Salto Space access system.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="space_ids" type="Array">
  IDs of the spaces that the entrance is in.
</ResponseField>

<ResponseField name="visionline_metadata" type="Object">
  Visionline-specific metadata associated with the [entrance](/low-level-apis/access-systems/retrieving-entrance-details).

  <Expandable title="properties">
    <ResponseField name="door_category" type="Enum (String)">
      Category of the door in the Visionline access system.
    </ResponseField>

    <ResponseField name="door_name" type="String">
      Name of the door in the Visionline access system.
    </ResponseField>

    <ResponseField name="profiles" type="Array">
      Profile for the door in the Visionline access system.

      <Expandable title="properties">
        <ResponseField name="visionline_door_profile_id" type="String">
          Door profile ID in the Visionline access system.
        </ResponseField>

        <ResponseField name="visionline_door_profile_type" type="Enum (String)">
          Door profile type in the Visionline access system.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="warnings" type="Array">
  Warnings associated with the [entrance](/low-level-apis/access-systems/retrieving-entrance-details).
</ResponseField>


# Unlock an Entrance
Source: https://docs.seam.co/api/acs/entrances/unlock

/openapi.json post /acs/entrances/unlock
Remotely unlocks a specified [entrance](/low-level-apis/access-systems/retrieving-entrance-details) using a cloud_key credential. Returns an action attempt that tracks the progress of the unlock operation.



# Access Control Systems
Source: https://docs.seam.co/api/acs/object

Systems for managing and monitoring access to physical spaces

Access control systems centralize access authorization for buildings, which means that you can use a single system to grant users access to one or more entrances. An access control system manages the following elements:

* Who has access
* The entrances to which users have access
* The access schedule for each user and entrance
* The access mechanism—PIN codes, mobile keys, or plastic cards—for each access grant

To grant access using the Seam access control system API, use the following basic process:

1. Create `acs_user`s.
2. Configure access for these users.
   For some access control systems, configure the allowed entrances and access schedule. For other systems, use `acs_access_group`s. For details, see the [system integration guide](/device-and-system-integration-guides#access-control-systems) for your access control system.
3. Create `acs_credential`s, which are the digital means of granting access to users, such as PIN codes, mobile keys, and plastic (RFID) cards.
   If you are developing a mobile app to provide access for your users, you can also use [Seam's iOS and Android SDKs](/capability-guides/mobile-access/mobile-device-sdks) that pair with the Seam API to create and manage mobile keys.

## Resources

The Access Control Systems (ACS) namespace contains the following resources:

### [`acs_access_group`](/api/acs/access_groups/object)

Group that defines the entrances to which a set of users has access and, in some cases, the access schedule for these entrances and users.

Some access control systems use [access group](/low-level-apis/access-systems/user-management/assigning-users-to-access-groups), which are sets of users, combined with sets of permissions. These permissions include both the set of areas or assets that the users can access and the schedule during which the users can access these areas or assets. Instead of assigning access rights individually to each access control system user, which can be time-consuming and error-prone, administrators can assign users to an access group, thereby ensuring that the users inherit all the permissions associated with the access group. Using access groups streamlines the process of managing large numbers of access control system users, especially in bigger organizations or complexes.

To learn whether your access control system supports access groups, see the corresponding [system integration guide](/device-and-system-integration-guides#access-control-systems).

***

### [`acs_credential`](/api/acs/credentials/object)

Means by which an [access control system user](/low-level-apis/access-systems/user-management) gains access at an [entrance](/low-level-apis/access-systems/retrieving-entrance-details). The `acs_credential` object represents a [credential](/low-level-apis/access-systems/managing-credentials) that provides an ACS user access within an [access control system](/low-level-apis/access-systems).

An access control system generally uses digital means of access to authorize a user trying to get through a specific entrance. Examples of credentials include plastic key cards, mobile keys, biometric identifiers, and PIN codes. The electronic nature of these credentials, as well as the fact that access is centralized, enables both the rapid provisioning and rescinding of access and the ability to compile access audit logs.

For each `acs_credential`, you define the access method. You can also specify additional properties, such as a PIN code, depending on the credential type.

For granting a person access to a space, [Access Grants](/use-cases/granting-access) are the default and recommended approach. Use the lower-level ACS credential API directly only when you specifically need to manage individual credentials.

***

### [`acs_encoder`](/api/acs/encoders/object)

Represents a hardware device that encodes [credential](/low-level-apis/access-systems/managing-credentials) data onto physical cards within an [access control system](/low-level-apis/access-systems).

Some access control systems require credentials to be encoded onto plastic key cards using a card encoder. This process involves the following two key steps:

1. Credential creation
   Configure the access parameters for the credential.
2. Card encoding
   Write the credential data onto the card using a compatible card encoder.

Separately, the Seam API also supports card scanning, which enables you to scan and read the encoded data on a card. You can use this action to confirm consistency with access control system records or diagnose discrepancies if needed.

See [Working with Card Encoders and Scanners](/low-level-apis/access-systems/working-with-card-encoders-and-scanners).

To verify if your access control system requires a card encoder, see the corresponding [system integration guide](/device-and-system-integration-guides#access-control-systems).

***

### [`acs_entrance`](/api/acs/entrances/object)

Represents an [entrance](/low-level-apis/access-systems/retrieving-entrance-details) within an [access control system](/low-level-apis/access-systems).

In an access control system, an entrance is a secured door, gate, zone, or other method of entry. You can list details for all the `acs_entrance` resources in your workspace or get these details for a specific `acs_entrance`. You can also list all entrances associated with a specific credential, and you can list all credentials associated with a specific entrance.

***

### [`acs_system`](/api/acs/systems/object)

Represents an [access control system](/low-level-apis/access-systems).

Within an `acs_system`, create [`acs_user`s](/api/acs/users/object) and [`acs_credential`s](/api/acs/credentials/object) to grant access to the `acs_user`s.

For details about the resources associated with an access control system, see the [access control systems namespace](/api/acs/object).

***

### [`acs_user`](/api/acs/users/object)

Represents a [user](/low-level-apis/access-systems/user-management) in an [access system](/low-level-apis/access-systems).

An access system user typically refers to an individual who requires access, like an employee or resident. Each user can possess multiple credentials that serve as their keys or identifiers for access. The type of credential can vary widely. For example, in the Salto system, a user can have a PIN code, a mobile app account, and a fob. In other platforms, it is not uncommon for a user to have more than one of the same credential type, such as multiple key cards. Additionally, these credentials can have a schedule or validity period.

For details about how to configure users in your access system, see the corresponding [system integration guide](/device-and-system-integration-guides#access-control-systems).

***


# ACS System Errors and Warnings
Source: https://docs.seam.co/api/acs/systems/errors

Errors and warnings that Seam reports on the ACS System resource, each with its code and meaning.

## Errors

Each error is an object with the following shape:

```json Example error theme={null}
{
  "error_code": "seam_bridge_disconnected",
  "message": "Indicates that the Seam API cannot communicate with Seam Bridge, for example, if Seam Bridge executable has stopped or if the computer running the Seam Bridge executable is offline.\nThis error might also occur if Seam Bridge is connected to the wrong workspace.\nSee also Troubleshooting Your Access Control System.",
  "created_at": "2025-01-01T00:00:00.000Z"
}
```

<Accordion title="Error object properties">
  <ResponseField name="error_code" type="Enum (String)">
    Unique identifier of the type of error. Enables quick recognition and categorization of the issue.

    One of the error codes listed below.
  </ResponseField>

  <ResponseField name="message" type="String">
    Detailed description of the error. Provides insights into the issue and potentially how to rectify it.
  </ResponseField>

  <ResponseField name="created_at" type="String (ISO 8601)">
    Date and time at which Seam created the error.
  </ResponseField>

  <ResponseField name="is_bridge_error" type="Boolean">
    Indicates whether the error is related to the [Seam Bridge](/capability-guides/seam-bridge).
  </ResponseField>
</Accordion>

### `account_disconnected`

Indicates that the login credentials are invalid. Reconnect the account using a [Connect Webview](/core-concepts/connect-webviews) to restore access.

***

### `acs_system_disconnected`

Indicates that the [access control system](/low-level-apis/access-systems) has been disconnected. See [Troubleshooting Your Access Control System](/low-level-apis/access-systems/troubleshooting-your-access-control-system) to resolve the issue.

***

### `bridge_disconnected`

Indicates that the Seam API cannot communicate with [Seam Bridge](/capability-guides/seam-bridge), for example, if Seam Bridge executable has stopped or if the computer running the Seam Bridge executable is offline.
See also [Troubleshooting Your Access Control System](/low-level-apis/access-systems/troubleshooting-your-access-control-system#acs_system-errors-seam_bridge_disconnected).

***

### `insufficient_permissions`

Indicates that Seam's integration user does not have sufficient permissions on the provider's system backing this [access control system](/low-level-apis/access-systems). Access cannot be managed until permissions are restored. See the error message for specifics, then either reauthorize the connected account in Seam or grant the integration user the required permissions in the provider's system.

***

### `provider_service_unavailable`

Indicates that the access control system provider's service is temporarily unavailable. Seam will automatically retry and reconnect when the service becomes available again.

***

### `salto_ks_certification_expired`

Indicates that the [access control system](/low-level-apis/access-systems) has lost its Salto KS certification. Contact [support](mailto:support@seam.co) to regain access.

***

### `salto_ks_subscription_limit_exceeded`

Indicates that the maximum number of users allowed for the site has been reached. This means that new access codes cannot be created. Contact Salto support to increase the user limit.

***

### `seam_bridge_disconnected`

Indicates that the Seam API cannot communicate with [Seam Bridge](/capability-guides/seam-bridge), for example, if Seam Bridge executable has stopped or if the computer running the Seam Bridge executable is offline.
This error might also occur if Seam Bridge is connected to the wrong [workspace](/core-concepts/workspaces).
See also [Troubleshooting Your Access Control System](/low-level-apis/access-systems/troubleshooting-your-access-control-system#acs_system-errors-seam_bridge_disconnected).

***

### `visionline_instance_unreachable`

Indicates that [Seam Bridge](/capability-guides/seam-bridge) is functioning correctly and the Seam API can communicate with Seam Bridge, but the Seam API cannot connect to the on-premises [Visionline access control system](/device-and-system-integration-guides/assa-abloy-visionline-access-control-system).
For example, the IP address of the on-premises access control system may be set incorrectly within the Seam [workspace](/core-concepts/workspaces).
See also [Troubleshooting Your Access Control System](/low-level-apis/access-systems/troubleshooting-your-access-control-system#acs_system-errors-visionline_instance_unreachable).

***

## Warnings

Each warning is an object with the following shape:

```json Example warning theme={null}
{
  "warning_code": "salto_ks_subscription_limit_almost_reached",
  "message": "Indicates that the Salto KS site has exceeded 80% of the maximum number of allowed users. Increase your subscription limit or delete some users from your site to rectify the issue.",
  "created_at": "2025-01-01T00:00:00.000Z"
}
```

<Accordion title="Warning object properties">
  <ResponseField name="warning_code" type="Enum (String)">
    Unique identifier of the type of warning. Enables quick recognition and categorization of the issue.

    One of the warning codes listed below.
  </ResponseField>

  <ResponseField name="message" type="String">
    Detailed description of the warning. Provides insights into the issue and potentially how to rectify it.
  </ResponseField>

  <ResponseField name="created_at" type="String (ISO 8601)">
    Date and time at which Seam created the warning.
  </ResponseField>

  <ResponseField name="misconfigured_acs_entrance_ids" type="Array">
    The misconfigured acs entrance ids.
  </ResponseField>
</Accordion>

### `salto_ks_subscription_limit_almost_reached`

Indicates that the Salto KS site has exceeded 80% of the maximum number of allowed users. Increase your subscription limit or delete some users from your site to rectify the issue.

***

### `setup_required`

Indicates that the access control system requires additional setup before it can be fully operational. Follow the instructions in the warning message to complete the setup.

***

### `time_zone_does_not_match_location`

Indicates the [access control system](/low-level-apis/access-systems) time zone could not be determined because the reported physical location does not match the time zone configured on the physical [ACS entrances](/low-level-apis/access-systems/retrieving-entrance-details).

***


# ACS System Events
Source: https://docs.seam.co/api/acs/systems/events

Webhook events that Seam emits for the ACS System resource, with example payloads and properties.

## `acs_system.connected`

An [access system](/low-level-apis/access-systems) was connected.

<ResponseExample>
  ```json Example webhook payload theme={null}
  {
    "acs_system_id": "00000000-0000-0000-0000-000000000000",
    "connected_account_id": "00000000-0000-0000-0000-000000000000",
    "created_at": "2025-01-01T00:00:00.000Z",
    "event_description": "An [access system](/low-level-apis/access-systems) was connected.",
    "event_id": "00000000-0000-0000-0000-000000000000",
    "event_type": "acs_system.connected",
    "occurred_at": "2025-01-01T00:00:00.000Z",
    "workspace_id": "00000000-0000-0000-0000-000000000000"
  }
  ```
</ResponseExample>

<Accordion title="Properties">
  <ResponseField name="acs_system_id" type="String (UUID)">
    ID of the access system.
  </ResponseField>

  <ResponseField name="connected_account_id" type="String (UUID)">
    ID of the connected account.
  </ResponseField>

  <ResponseField name="created_at" type="String (ISO 8601)">
    Date and time at which the event was created.
  </ResponseField>

  <ResponseField name="event_description" type="String">
    Human-readable description of the event. Persisted when the event is created (so the creating code, including a provider, can supply a tailored description) and otherwise derived from the event.
  </ResponseField>

  <ResponseField name="event_id" type="String (UUID)">
    ID of the event.
  </ResponseField>

  <ResponseField name="event_type" type="Enum (String)">
    Value: `acs_system.connected`
  </ResponseField>

  <ResponseField name="occurred_at" type="String (ISO 8601)">
    Date and time at which the event occurred.
  </ResponseField>

  <ResponseField name="workspace_id" type="String (UUID)">
    ID of the workspace associated with the event.
  </ResponseField>
</Accordion>

## `acs_system.added`

An [access system](/low-level-apis/access-systems) was added.

<ResponseExample>
  ```json Example webhook payload theme={null}
  {
    "acs_system_id": "00000000-0000-0000-0000-000000000000",
    "connected_account_id": "00000000-0000-0000-0000-000000000000",
    "created_at": "2025-01-01T00:00:00.000Z",
    "event_description": "An [access system](/low-level-apis/access-systems) was added.",
    "event_id": "00000000-0000-0000-0000-000000000000",
    "event_type": "acs_system.added",
    "occurred_at": "2025-01-01T00:00:00.000Z",
    "workspace_id": "00000000-0000-0000-0000-000000000000"
  }
  ```
</ResponseExample>

<Accordion title="Properties">
  <ResponseField name="acs_system_id" type="String (UUID)">
    ID of the access system.
  </ResponseField>

  <ResponseField name="connected_account_id" type="String (UUID)">
    ID of the connected account.
  </ResponseField>

  <ResponseField name="created_at" type="String (ISO 8601)">
    Date and time at which the event was created.
  </ResponseField>

  <ResponseField name="event_description" type="String">
    Human-readable description of the event. Persisted when the event is created (so the creating code, including a provider, can supply a tailored description) and otherwise derived from the event.
  </ResponseField>

  <ResponseField name="event_id" type="String (UUID)">
    ID of the event.
  </ResponseField>

  <ResponseField name="event_type" type="Enum (String)">
    Value: `acs_system.added`
  </ResponseField>

  <ResponseField name="occurred_at" type="String (ISO 8601)">
    Date and time at which the event occurred.
  </ResponseField>

  <ResponseField name="workspace_id" type="String (UUID)">
    ID of the workspace associated with the event.
  </ResponseField>
</Accordion>

## `acs_system.disconnected`

An [access system](/low-level-apis/access-systems) was disconnected.

<ResponseExample>
  ```json Example webhook payload theme={null}
  {
    "acs_system_errors": [],
    "acs_system_id": "00000000-0000-0000-0000-000000000000",
    "acs_system_warnings": [],
    "connected_account_errors": [],
    "connected_account_id": "00000000-0000-0000-0000-000000000000",
    "connected_account_warnings": [],
    "created_at": "2025-01-01T00:00:00.000Z",
    "event_description": "An [access system](/low-level-apis/access-systems) was disconnected.",
    "event_id": "00000000-0000-0000-0000-000000000000",
    "event_type": "acs_system.disconnected",
    "occurred_at": "2025-01-01T00:00:00.000Z",
    "workspace_id": "00000000-0000-0000-0000-000000000000"
  }
  ```
</ResponseExample>

<Accordion title="Properties">
  <ResponseField name="acs_system_errors" type="Array">
    Errors associated with the access control system.
  </ResponseField>

  <ResponseField name="acs_system_id" type="String (UUID)">
    ID of the access system.
  </ResponseField>

  <ResponseField name="acs_system_warnings" type="Array">
    Warnings associated with the access control system.
  </ResponseField>

  <ResponseField name="connected_account_errors" type="Array">
    Errors associated with the connected account.
  </ResponseField>

  <ResponseField name="connected_account_id" type="String (UUID)">
    ID of the connected account.
  </ResponseField>

  <ResponseField name="connected_account_warnings" type="Array">
    Warnings associated with the connected account.
  </ResponseField>

  <ResponseField name="created_at" type="String (ISO 8601)">
    Date and time at which the event was created.
  </ResponseField>

  <ResponseField name="event_description" type="String">
    Human-readable description of the event. Persisted when the event is created (so the creating code, including a provider, can supply a tailored description) and otherwise derived from the event.
  </ResponseField>

  <ResponseField name="event_id" type="String (UUID)">
    ID of the event.
  </ResponseField>

  <ResponseField name="event_type" type="Enum (String)">
    Value: `acs_system.disconnected`
  </ResponseField>

  <ResponseField name="occurred_at" type="String (ISO 8601)">
    Date and time at which the event occurred.
  </ResponseField>

  <ResponseField name="workspace_id" type="String (UUID)">
    ID of the workspace associated with the event.
  </ResponseField>
</Accordion>


# Get an ACS System
Source: https://docs.seam.co/api/acs/systems/get

/openapi.json post /acs/systems/get
Returns a specified [access system](/low-level-apis/access-systems).



# List ACS Systems
Source: https://docs.seam.co/api/acs/systems/list

/openapi.json post /acs/systems/list
Returns a list of all [access systems](/low-level-apis/access-systems).

To filter the list of returned access systems by a specific connected account ID, include the `connected_account_id` in the request body. If you omit the `connected_account_id` parameter, the response includes all access systems connected to your workspace.



# List Compatible Credential Manager ACS Systems
Source: https://docs.seam.co/api/acs/systems/list_compatible_credential_manager_acs_systems

/openapi.json post /acs/systems/list_compatible_credential_manager_acs_systems
Returns a list of all credential manager systems that are compatible with a specified [access system](/low-level-apis/access-systems).

Specify the access system for which you want to retrieve all compatible credential manager systems by including the corresponding `acs_system_id` in the request body.



# The ACS System Object
Source: https://docs.seam.co/api/acs/systems/object

Learn how the acs_system object represents an access control system in which you create users and credentials to grant them access at entrances.

## The acs\_system Object

Represents an [access control system](/low-level-apis/access-systems).

Within an `acs_system`, create [`acs_user`s](/api/acs/users/object) and [`acs_credential`s](/api/acs/credentials/object) to grant access to the `acs_user`s.

For details about the resources associated with an access control system, see the [access control systems namespace](/api/acs/object).

<ResponseExample>
  ```json ACS System theme={null}
  {
    "acs_access_group_count": 5,
    "acs_system_id": "dbed811f-a8c7-4dab-a3cb-1a734ebd6ac7",
    "acs_user_count": 20,
    "connected_account_id": "a94aeed0-1ae0-4e49-9c23-8444c7ceba09",
    "connected_account_ids": [
      "a94aeed0-1ae0-4e49-9c23-8444c7ceba09"
    ],
    "created_at": "2025-06-15T16:54:17.946425Z",
    "default_credential_manager_acs_system_id": "5dde2def-3507-44f5-9521-7ca96aa4cd18",
    "errors": [],
    "external_type": "salto_ks_site",
    "external_type_display_name": "Salto KS site",
    "image_alt_text": "Salto KS site Logo",
    "image_url": "https://connect.getseam.com/_next/image?url=https://connect.getseam.com/assets/images/acs_systems/salto_ks_site.png&q=75&w=128",
    "is_credential_manager": false,
    "location": {
      "time_zone": "America/New_York"
    },
    "name": "My ACS System",
    "warnings": [],
    "workspace_id": "172920be-1f4d-45d4-8519-ecc3bdee638f"
  }
  ```
</ResponseExample>

***

## Properties

<ResponseField name="acs_access_group_count" type="number">
  Number of access groups in the [access control system](/low-level-apis/access-systems).
</ResponseField>

<ResponseField name="acs_system_id" type="String (UUID)">
  ID of the [access control system](/low-level-apis/access-systems).
</ResponseField>

<ResponseField name="acs_user_count" type="number">
  Number of users in the [access control system](/low-level-apis/access-systems).
</ResponseField>

<ResponseField name="connected_account_id" type="String (UUID)">
  ID of the connected account associated with the [access control system](/low-level-apis/access-systems).
</ResponseField>

<ResponseField name="connected_account_ids" type="Array">
  **Deprecated**. Use `connected_account_id`.

  IDs of the [connected accounts](/core-concepts/connected-accounts) associated with the [access control system](/low-level-apis/access-systems).
</ResponseField>

<ResponseField name="created_at" type="String (ISO 8601)">
  Date and time at which the [access control system](/low-level-apis/access-systems) was created.
</ResponseField>

<ResponseField name="default_credential_manager_acs_system_id" type="String (UUID)">
  ID of the default credential manager `acs_system` for this [access control system](/low-level-apis/access-systems).
</ResponseField>

<ResponseField name="errors" type="Array">
  Errors associated with the [access control system](/low-level-apis/access-systems).
</ResponseField>

<ResponseField name="external_type" type="Enum (String)">
  Brand-specific terminology for the [access control system](/low-level-apis/access-systems) type.
</ResponseField>

<ResponseField name="external_type_display_name" type="String">
  Display name that corresponds to the brand-specific terminology for the [access control system](/low-level-apis/access-systems) type.
</ResponseField>

<ResponseField name="image_alt_text" type="String">
  Alternative text for the [access control system](/low-level-apis/access-systems) image.
</ResponseField>

<ResponseField name="image_url" type="String">
  URL for the image that represents the [access control system](/low-level-apis/access-systems).
</ResponseField>

<ResponseField name="is_credential_manager" type="Boolean">
  Indicates whether the `acs_system` is a credential manager.
</ResponseField>

<ResponseField name="location" type="Object">
  Location information for the [access control system](/low-level-apis/access-systems).

  <Expandable title="properties">
    <ResponseField name="time_zone" type="String">
      Time zone in which the [access control system](/low-level-apis/access-systems) is located.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="name" type="String">
  Name of the [access control system](/low-level-apis/access-systems).
</ResponseField>

<ResponseField name="system_type" type="Enum (String)">
  **Deprecated**. Use `external_type`.

  The system type.
</ResponseField>

<ResponseField name="system_type_display_name" type="String">
  **Deprecated**. Use `external_type_display_name`.

  The system type display name.
</ResponseField>

<ResponseField name="visionline_metadata" type="Object">
  Visionline-specific metadata for the [access control system](/low-level-apis/access-systems).

  <Expandable title="properties">
    <ResponseField name="lan_address" type="String">
      IP address or hostname of the main Visionline server relative to [Seam Bridge](/capability-guides/seam-bridge) on the local network.
    </ResponseField>

    <ResponseField name="mobile_access_uuid" type="String">
      Keyset loaded into a reader. Mobile keys and reader administration tools securely authenticate only with readers programmed with a matching keyset.
    </ResponseField>

    <ResponseField name="system_id" type="String">
      Unique ID assigned by the ASSA ABLOY licensing team that identifies each hotel in your credential manager.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="warnings" type="Array">
  Warnings associated with the [access control system](/low-level-apis/access-systems).
</ResponseField>

<ResponseField name="workspace_id" type="String (UUID)">
  ID of the workspace that contains the [access control system](/low-level-apis/access-systems).
</ResponseField>


# Report Devices
Source: https://docs.seam.co/api/acs/systems/report_devices

/openapi.json post /acs/systems/report_devices
Reports ACS system device status including encoders and entrances.



# Add an ACS User to an Access Group
Source: https://docs.seam.co/api/acs/users/add_to_access_group

/openapi.json post /acs/users/add_to_access_group
Adds a specified [access system user](/low-level-apis/access-systems/user-management) to a specified [access group](/low-level-apis/access-systems/user-management/assigning-users-to-access-groups).



# Create an ACS User
Source: https://docs.seam.co/api/acs/users/create

/openapi.json post /acs/users/create
Creates a new [access system user](/low-level-apis/access-systems/user-management).



# Delete an ACS User
Source: https://docs.seam.co/api/acs/users/delete

/openapi.json post /acs/users/delete
Deletes a specified [access system user](/low-level-apis/access-systems/user-management) and invalidates the access system user's [credentials](/low-level-apis/access-systems/managing-credentials).

You must include at least one request parameter.



# ACS User Errors and Warnings
Source: https://docs.seam.co/api/acs/users/errors

Errors and warnings that Seam reports on the ACS User resource, each with its code and meaning.

## Errors

Each error is an object with the following shape:

```json Example error theme={null}
{
  "error_code": "deleted_externally",
  "message": "Indicates that the access system user was deleted from the access system outside of Seam.",
  "created_at": "2025-01-01T00:00:00.000Z"
}
```

<Accordion title="Error object properties">
  <ResponseField name="error_code" type="Enum (String)">
    The error code.

    One of the error codes listed below.
  </ResponseField>

  <ResponseField name="message" type="String">
    Detailed description of the error. Provides insights into the issue and potentially how to rectify it.
  </ResponseField>

  <ResponseField name="created_at" type="String (ISO 8601)">
    Date and time at which Seam created the error.
  </ResponseField>
</Accordion>

### `deleted_externally`

Indicates that the [access system user](/low-level-apis/access-systems/user-management) was deleted from the [access system](/low-level-apis/access-systems) outside of Seam.

***

### `failed_to_create_on_acs_system`

Indicates that the [access system user](/low-level-apis/access-systems/user-management) was not created on the [access system](/low-level-apis/access-systems). This is likely due to an internal unexpected error. Contact Seam [support](mailto:support@seam.co).

***

### `failed_to_delete_on_acs_system`

Indicates that the [access system user](/low-level-apis/access-systems/user-management) was not deleted on the [access system](/low-level-apis/access-systems). This is likely due to an internal unexpected error. Contact Seam [support](mailto:support@seam.co).

***

### `failed_to_update_on_acs_system`

Indicates that the [access system user](/low-level-apis/access-systems/user-management) was not updated on the [access system](/low-level-apis/access-systems). This is likely due to an internal unexpected error. Contact Seam [support](mailto:support@seam.co).

***

### `latch_conflict_with_resident_user`

Indicates that the [access system user](/low-level-apis/access-systems/user-management) was created from the Seam API but also exists on Mission Control. This is unsupported. Contact Seam [support](mailto:support@seam.co).

***

### `salto_ks_subscription_limit_exceeded`

Indicates that the [access system user](/low-level-apis/access-systems/user-management) could not be subscribed on Salto KS because the subscription limit has been exceeded.

***

## Warnings

Each warning is an object with the following shape:

```json Example warning theme={null}
{
  "warning_code": "being_deleted",
  "message": "Indicates that the access system user is being deleted from the access system. This is a temporary state, and the access system user will be deleted shortly.",
  "created_at": "2025-01-01T00:00:00.000Z"
}
```

<Accordion title="Warning object properties">
  <ResponseField name="warning_code" type="Enum (String)">
    The warning code.

    One of the warning codes listed below.
  </ResponseField>

  <ResponseField name="message" type="String">
    Detailed description of the warning. Provides insights into the issue and potentially how to rectify it.
  </ResponseField>

  <ResponseField name="created_at" type="String (ISO 8601)">
    Date and time at which Seam created the warning.
  </ResponseField>
</Accordion>

### `acs_user_inactive`

Indicates that the [access system user](/low-level-apis/access-systems/user-management) exists but is not currently able to gain access—for example, because their access schedule has not started yet or has ended, the access system has reached its limit for active users, or they have been unsubscribed or deactivated. Refer to the warning message for the provider-specific reason. This is distinct from `is_suspended`, which indicates the user has been explicitly blocked.

***

### `being_deleted`

Indicates that the [access system user](/low-level-apis/access-systems/user-management) is being deleted from the [access system](/low-level-apis/access-systems). This is a temporary state, and the access system user will be deleted shortly.

***

### `latch_resident_user`

Indicates that the [access system user](/low-level-apis/access-systems/user-management) was created on Latch Mission Control. Please use the Latch Mission Control to manage this user.

***

### `salto_ks_user_not_subscribed`

Indicates that the [access system user](/low-level-apis/access-systems/user-management) is not subscribed on Salto KS, so they cannot unlock doors or perform any actions. This occurs when the their access schedule hasn’t started yet, if their access schedule has ended, if the site has reached its limit for active users (subscription slots), or if they have been manually unsubscribed.

***

### `unknown_issue_with_acs_user`

An unknown issue occurred while syncing the state of this [access system user](/low-level-apis/access-systems/user-management) with the provider. This issue may affect the proper functioning of this user.

***


# ACS User Events
Source: https://docs.seam.co/api/acs/users/events

Webhook events that Seam emits for the ACS User resource, with example payloads and properties.

## `acs_user.created`

An [access system user](/low-level-apis/access-systems/user-management) was created.

<ResponseExample>
  ```json Example webhook payload theme={null}
  {
    "acs_system_id": "00000000-0000-0000-0000-000000000000",
    "acs_user_id": "00000000-0000-0000-0000-000000000000",
    "connected_account_id": "00000000-0000-0000-0000-000000000000",
    "created_at": "2025-01-01T00:00:00.000Z",
    "event_description": "An [access system user](/low-level-apis/access-systems/user-management) was created.",
    "event_id": "00000000-0000-0000-0000-000000000000",
    "event_type": "acs_user.created",
    "occurred_at": "2025-01-01T00:00:00.000Z",
    "workspace_id": "00000000-0000-0000-0000-000000000000"
  }
  ```
</ResponseExample>

<Accordion title="Properties">
  <ResponseField name="acs_system_id" type="String (UUID)">
    ID of the access system.
  </ResponseField>

  <ResponseField name="acs_user_id" type="String (UUID)">
    ID of the affected access system user.
  </ResponseField>

  <ResponseField name="connected_account_id" type="String (UUID)">
    ID of the connected account.
  </ResponseField>

  <ResponseField name="created_at" type="String (ISO 8601)">
    Date and time at which the event was created.
  </ResponseField>

  <ResponseField name="event_description" type="String">
    Human-readable description of the event. Persisted when the event is created (so the creating code, including a provider, can supply a tailored description) and otherwise derived from the event.
  </ResponseField>

  <ResponseField name="event_id" type="String (UUID)">
    ID of the event.
  </ResponseField>

  <ResponseField name="event_type" type="Enum (String)">
    Value: `acs_user.created`
  </ResponseField>

  <ResponseField name="occurred_at" type="String (ISO 8601)">
    Date and time at which the event occurred.
  </ResponseField>

  <ResponseField name="workspace_id" type="String (UUID)">
    ID of the workspace associated with the event.
  </ResponseField>
</Accordion>

## `acs_user.deleted`

An [access system user](/low-level-apis/access-systems/user-management) was deleted.

<ResponseExample>
  ```json Example webhook payload theme={null}
  {
    "acs_system_id": "00000000-0000-0000-0000-000000000000",
    "acs_user_id": "00000000-0000-0000-0000-000000000000",
    "connected_account_id": "00000000-0000-0000-0000-000000000000",
    "created_at": "2025-01-01T00:00:00.000Z",
    "event_description": "An [access system user](/low-level-apis/access-systems/user-management) was deleted.",
    "event_id": "00000000-0000-0000-0000-000000000000",
    "event_type": "acs_user.deleted",
    "occurred_at": "2025-01-01T00:00:00.000Z",
    "workspace_id": "00000000-0000-0000-0000-000000000000"
  }
  ```
</ResponseExample>

<Accordion title="Properties">
  <ResponseField name="acs_system_id" type="String (UUID)">
    ID of the access system.
  </ResponseField>

  <ResponseField name="acs_user_id" type="String (UUID)">
    ID of the affected access system user.
  </ResponseField>

  <ResponseField name="connected_account_id" type="String (UUID)">
    ID of the connected account.
  </ResponseField>

  <ResponseField name="created_at" type="String (ISO 8601)">
    Date and time at which the event was created.
  </ResponseField>

  <ResponseField name="event_description" type="String">
    Human-readable description of the event. Persisted when the event is created (so the creating code, including a provider, can supply a tailored description) and otherwise derived from the event.
  </ResponseField>

  <ResponseField name="event_id" type="String (UUID)">
    ID of the event.
  </ResponseField>

  <ResponseField name="event_type" type="Enum (String)">
    Value: `acs_user.deleted`
  </ResponseField>

  <ResponseField name="occurred_at" type="String (ISO 8601)">
    Date and time at which the event occurred.
  </ResponseField>

  <ResponseField name="workspace_id" type="String (UUID)">
    ID of the workspace associated with the event.
  </ResponseField>
</Accordion>


# Get an ACS User
Source: https://docs.seam.co/api/acs/users/get

/openapi.json post /acs/users/get
Returns a specified [access system user](/low-level-apis/access-systems/user-management).

You must include at least one request parameter.



# List ACS Users
Source: https://docs.seam.co/api/acs/users/list

/openapi.json post /acs/users/list
Returns a list of all [access system users](/low-level-apis/access-systems/user-management).



# List ACS User-Accessible Entrances
Source: https://docs.seam.co/api/acs/users/list_accessible_entrances

/openapi.json post /acs/users/list_accessible_entrances
Lists the [entrances](/api/acs/entrances/object) to which a specified [access system user](/low-level-apis/access-systems/user-management) has access.

You must include at least one request parameter.



# The ACS User Object
Source: https://docs.seam.co/api/acs/users/object

Learn how the acs_user object represents an individual—such as an employee or resident—who holds one or more credentials in an access control system.

## The acs\_user Object

Represents a [user](/low-level-apis/access-systems/user-management) in an [access system](/low-level-apis/access-systems).

An access system user typically refers to an individual who requires access, like an employee or resident. Each user can possess multiple credentials that serve as their keys or identifiers for access. The type of credential can vary widely. For example, in the Salto system, a user can have a PIN code, a mobile app account, and a fob. In other platforms, it is not uncommon for a user to have more than one of the same credential type, such as multiple key cards. Additionally, these credentials can have a schedule or validity period.

For details about how to configure users in your access system, see the corresponding [system integration guide](/device-and-system-integration-guides#access-control-systems).

<ResponseExample>
  ```json ACS User theme={null}
  {
    "access_schedule": {
      "ends_at": "2025-06-12T11:00:00.000Z",
      "starts_at": "2025-06-10T15:00:00.000Z"
    },
    "acs_system_id": "62d3384f-267f-4a4a-a946-d35819ec9981",
    "acs_user_id": "6a5d9697-3cc4-436a-8165-4375ff424870",
    "connected_account_id": "c0175797-30f0-49f7-a228-2df115443ca7",
    "created_at": "2025-06-15T16:54:17.946482Z",
    "display_name": "Jane Doe",
    "email_address": "jane@example.com",
    "errors": [],
    "external_type": "salto_site_user",
    "external_type_display_name": "Salto site user",
    "full_name": "Jane Doe",
    "hid_acs_system_id": "2acbe47f-612c-422a-9205-7af292f74e7f",
    "is_managed": true,
    "is_suspended": false,
    "last_successful_sync_at": "2025-06-18T17:45:00.582Z",
    "pending_mutations": [
      {
        "to": {
          "acs_access_group_id": "2c0fb4a0-2b42-4651-926e-1a10bedbf6ce"
        },
        "from": {
          "acs_access_group_id": "f1e2d3c4-b5a6-4d7c-8e9f-0a1b2c3d4e5f"
        },
        "message": "This user's access membership is being updated.",
        "created_at": "2025-06-18T17:57:01.867Z",
        "mutation_code": "updating_group_membership"
      }
    ],
    "phone_number": "+1555551000",
    "user_identity_email_address": "jane@example.com",
    "user_identity_full_name": "Jane Doe",
    "user_identity_id": "a23b3e02-e394-4e5f-b21c-b366b8bc0dd3",
    "user_identity_phone_number": "+1555551000",
    "warnings": [],
    "workspace_id": "8d4868e3-2f95-4f33-8689-19420b3101cd"
  }
  ```
</ResponseExample>

***

## Properties

<ResponseField name="access_schedule" type="Object">
  `starts_at` and `ends_at` timestamps for the [access system user's](/low-level-apis/access-systems/user-management) access.

  <Expandable title="properties">
    <ResponseField name="ends_at" type="String (ISO 8601)">
      Date and time at which the user's access ends, in [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) format.
    </ResponseField>

    <ResponseField name="starts_at" type="String (ISO 8601)">
      Date and time at which the user's access starts, in [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) format.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="acs_system_id" type="String (UUID)">
  ID of the [access system](/low-level-apis/access-systems) that contains the [access system user](/low-level-apis/access-systems/user-management).
</ResponseField>

<ResponseField name="acs_user_id" type="String (UUID)">
  ID of the [access system user](/low-level-apis/access-systems/user-management).
</ResponseField>

<ResponseField name="connected_account_id" type="String (UUID)">
  The ID of the connected account that is associated with the [access system user](/low-level-apis/access-systems/user-management).
</ResponseField>

<ResponseField name="created_at" type="String (ISO 8601)">
  Date and time at which the [access system user](/low-level-apis/access-systems/user-management) was created.
</ResponseField>

<ResponseField name="display_name" type="String">
  Display name for the [access system user](/low-level-apis/access-systems/user-management).
</ResponseField>

<ResponseField name="email" type="String">
  **Deprecated**. use email\_address.

  The email.
</ResponseField>

<ResponseField name="email_address" type="String">
  Email address of the [access system user](/low-level-apis/access-systems/user-management).
</ResponseField>

<ResponseField name="errors" type="Array">
  Errors associated with the [access system user](/low-level-apis/access-systems/user-management).
</ResponseField>

<ResponseField name="external_type" type="Enum (String)">
  Brand-specific terminology for the [access system user](/low-level-apis/access-systems/user-management) type.
</ResponseField>

<ResponseField name="external_type_display_name" type="String">
  Display name that corresponds to the brand-specific terminology for the [access system user](/low-level-apis/access-systems/user-management) type.
</ResponseField>

<ResponseField name="full_name" type="String">
  Full name of the [access system user](/low-level-apis/access-systems/user-management).
</ResponseField>

<ResponseField name="hid_acs_system_id" type="String (UUID)">
  ID of the HID access control system associated with the user.
</ResponseField>

<ResponseField name="is_managed" type="Boolean">
  Indicates whether Seam manages the access system user.
</ResponseField>

<ResponseField name="is_suspended" type="Boolean">
  Indicates whether the [access system user](/low-level-apis/access-systems/user-management) is currently [suspended](/low-level-apis/access-systems/user-management/suspending-and-unsuspending-users).
</ResponseField>

<ResponseField name="pending_mutations" type="Array">
  Pending mutations associated with the [access system user](/low-level-apis/access-systems/user-management). Seam is in the process of pushing these mutations to the integrated access system.
</ResponseField>

<ResponseField name="phone_number" type="String">
  Phone number of the [access system user](/low-level-apis/access-systems/user-management) in E.164 format (for example, `+15555550100`).
</ResponseField>

<ResponseField name="salto_ks_metadata" type="Object">
  Salto KS-specific metadata associated with the [access system user](/low-level-apis/access-systems/user-management).

  <Expandable title="properties">
    <ResponseField name="is_subscribed" type="Boolean">
      Indicates whether the user holds an active subscription slot on the Salto KS site. Only subscribed users can unlock doors and count against the site's user-subscription limit. A user may not be subscribed because their access schedule has not started or has ended, the site has reached its subscription limit, or they were manually unsubscribed. This is distinct from `is_suspended`, which reflects whether the user has been explicitly blocked.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="salto_space_metadata" type="Object">
  Salto Space-specific metadata associated with the [access system user](/low-level-apis/access-systems/user-management).

  <Expandable title="properties">
    <ResponseField name="audit_openings" type="Boolean">
      Indicates whether AuditOpenings is enabled for the user in the Salto Space access system.
    </ResponseField>

    <ResponseField name="user_id" type="String">
      User ID in the Salto Space access system.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="user_identity_email_address" type="String">
  Email address of the user identity associated with the [access system user](/low-level-apis/access-systems/user-management).
</ResponseField>

<ResponseField name="user_identity_full_name" type="String">
  Full name of the user identity associated with the [access system user](/low-level-apis/access-systems/user-management).
</ResponseField>

<ResponseField name="user_identity_id" type="String">
  ID of the user identity associated with the [access system user](/low-level-apis/access-systems/user-management).
</ResponseField>

<ResponseField name="user_identity_phone_number" type="String">
  Phone number of the user identity associated with the [access system user](/low-level-apis/access-systems/user-management) in E.164 format (for example, `+15555550100`).
</ResponseField>

<ResponseField name="warnings" type="Array">
  Warnings associated with the [access system user](/low-level-apis/access-systems/user-management).
</ResponseField>

<ResponseField name="workspace_id" type="String (UUID)">
  ID of the workspace that contains the [access system user](/low-level-apis/access-systems/user-management).
</ResponseField>


# Remove an ACS User from an Access Group
Source: https://docs.seam.co/api/acs/users/remove_from_access_group

/openapi.json post /acs/users/remove_from_access_group
Removes a specified [access system user](/low-level-apis/access-systems/user-management) from a specified [access group](/low-level-apis/access-systems/user-management/assigning-users-to-access-groups).



# Revoke ACS User Access to All Entrances
Source: https://docs.seam.co/api/acs/users/revoke_access_to_all_entrances

/openapi.json post /acs/users/revoke_access_to_all_entrances
Revokes access to all [entrances](/api/acs/entrances/object) for a specified [access system user](/low-level-apis/access-systems/user-management).

You must include at least one request parameter.



# Suspend an ACS User
Source: https://docs.seam.co/api/acs/users/suspend

/openapi.json post /acs/users/suspend
[Suspends](/low-level-apis/access-systems/user-management/suspending-and-unsuspending-users#suspend-an-acs-user) a specified [access system user](/low-level-apis/access-systems/user-management). Suspending an access system user revokes their access temporarily. To restore an access system user's access, you can [unsuspend](/api/acs/users/unsuspend) them.

You must include at least one request parameter.



# Unsuspend an ACS User
Source: https://docs.seam.co/api/acs/users/unsuspend

/openapi.json post /acs/users/unsuspend
[Unsuspends](/low-level-apis/access-systems/user-management/suspending-and-unsuspending-users#unsuspend-an-acs-user) a specified suspended [access system user](/low-level-apis/access-systems/user-management). While [suspending an access system user](/api/acs/users/suspend) revokes their access temporarily, unsuspending the access system user restores their access.

You must include at least one request parameter.



# Update an ACS User
Source: https://docs.seam.co/api/acs/users/update

/openapi.json post /acs/users/update
Updates the properties of a specified [access system user](/low-level-apis/access-systems/user-management).

You must include at least one request parameter.



# Action Attempt Events
Source: https://docs.seam.co/api/action_attempts/events

Webhook events that Seam emits for the Action Attempt resource, with example payloads and properties.

## `action_attempt.lock_door.succeeded`

A lock door action attempt succeeded.

<ResponseExample>
  ```json Example webhook payload theme={null}
  {
    "action_attempt_id": "00000000-0000-0000-0000-000000000000",
    "action_type": "",
    "connected_account_id": "00000000-0000-0000-0000-000000000000",
    "created_at": "2025-01-01T00:00:00.000Z",
    "device_id": "00000000-0000-0000-0000-000000000000",
    "event_description": "A lock door action attempt succeeded.",
    "event_id": "00000000-0000-0000-0000-000000000000",
    "event_type": "action_attempt.lock_door.succeeded",
    "occurred_at": "2025-01-01T00:00:00.000Z",
    "status": "",
    "workspace_id": "00000000-0000-0000-0000-000000000000"
  }
  ```
</ResponseExample>

<Accordion title="Properties">
  <ResponseField name="action_attempt_id" type="String (UUID)">
    ID of the affected action attempt.
  </ResponseField>

  <ResponseField name="action_type" type="String">
    Type of the action.
  </ResponseField>

  <ResponseField name="connected_account_id" type="String (UUID)">
    ID of the connected account associated with the action attempt, if applicable.
  </ResponseField>

  <ResponseField name="created_at" type="String (ISO 8601)">
    Date and time at which the event was created.
  </ResponseField>

  <ResponseField name="device_id" type="String (UUID)">
    ID of the device associated with the action attempt, if applicable.
  </ResponseField>

  <ResponseField name="event_description" type="String">
    Human-readable description of the event. Persisted when the event is created (so the creating code, including a provider, can supply a tailored description) and otherwise derived from the event.
  </ResponseField>

  <ResponseField name="event_id" type="String (UUID)">
    ID of the event.
  </ResponseField>

  <ResponseField name="event_type" type="Enum (String)">
    Value: `action_attempt.lock_door.succeeded`
  </ResponseField>

  <ResponseField name="occurred_at" type="String (ISO 8601)">
    Date and time at which the event occurred.
  </ResponseField>

  <ResponseField name="status" type="String">
    Status of the action.
  </ResponseField>

  <ResponseField name="workspace_id" type="String (UUID)">
    ID of the workspace associated with the event.
  </ResponseField>
</Accordion>

## `action_attempt.lock_door.failed`

A lock door action attempt failed.

<ResponseExample>
  ```json Example webhook payload theme={null}
  {
    "action_attempt_id": "00000000-0000-0000-0000-000000000000",
    "action_type": "",
    "connected_account_id": "00000000-0000-0000-0000-000000000000",
    "created_at": "2025-01-01T00:00:00.000Z",
    "device_id": "00000000-0000-0000-0000-000000000000",
    "event_description": "A lock door action attempt failed.",
    "event_id": "00000000-0000-0000-0000-000000000000",
    "event_type": "action_attempt.lock_door.failed",
    "occurred_at": "2025-01-01T00:00:00.000Z",
    "status": "",
    "workspace_id": "00000000-0000-0000-0000-000000000000"
  }
  ```
</ResponseExample>

<Accordion title="Properties">
  <ResponseField name="action_attempt_id" type="String (UUID)">
    ID of the affected action attempt.
  </ResponseField>

  <ResponseField name="action_type" type="String">
    Type of the action.
  </ResponseField>

  <ResponseField name="connected_account_id" type="String (UUID)">
    ID of the connected account associated with the action attempt, if applicable.
  </ResponseField>

  <ResponseField name="created_at" type="String (ISO 8601)">
    Date and time at which the event was created.
  </ResponseField>

  <ResponseField name="device_id" type="String (UUID)">
    ID of the device associated with the action attempt, if applicable.
  </ResponseField>

  <ResponseField name="event_description" type="String">
    Human-readable description of the event. Persisted when the event is created (so the creating code, including a provider, can supply a tailored description) and otherwise derived from the event.
  </ResponseField>

  <ResponseField name="event_id" type="String (UUID)">
    ID of the event.
  </ResponseField>

  <ResponseField name="event_type" type="Enum (String)">
    Value: `action_attempt.lock_door.failed`
  </ResponseField>

  <ResponseField name="occurred_at" type="String (ISO 8601)">
    Date and time at which the event occurred.
  </ResponseField>

  <ResponseField name="status" type="String">
    Status of the action.
  </ResponseField>

  <ResponseField name="workspace_id" type="String (UUID)">
    ID of the workspace associated with the event.
  </ResponseField>
</Accordion>

## `action_attempt.unlock_door.succeeded`

An unlock door action attempt succeeded.

<ResponseExample>
  ```json Example webhook payload theme={null}
  {
    "action_attempt_id": "00000000-0000-0000-0000-000000000000",
    "action_type": "",
    "connected_account_id": "00000000-0000-0000-0000-000000000000",
    "created_at": "2025-01-01T00:00:00.000Z",
    "device_id": "00000000-0000-0000-0000-000000000000",
    "event_description": "An unlock door action attempt succeeded.",
    "event_id": "00000000-0000-0000-0000-000000000000",
    "event_type": "action_attempt.unlock_door.succeeded",
    "occurred_at": "2025-01-01T00:00:00.000Z",
    "status": "",
    "workspace_id": "00000000-0000-0000-0000-000000000000"
  }
  ```
</ResponseExample>

<Accordion title="Properties">
  <ResponseField name="action_attempt_id" type="String (UUID)">
    ID of the affected action attempt.
  </ResponseField>

  <ResponseField name="action_type" type="String">
    Type of the action.
  </ResponseField>

  <ResponseField name="connected_account_id" type="String (UUID)">
    ID of the connected account associated with the action attempt, if applicable.
  </ResponseField>

  <ResponseField name="created_at" type="String (ISO 8601)">
    Date and time at which the event was created.
  </ResponseField>

  <ResponseField name="device_id" type="String (UUID)">
    ID of the device associated with the action attempt, if applicable.
  </ResponseField>

  <ResponseField name="event_description" type="String">
    Human-readable description of the event. Persisted when the event is created (so the creating code, including a provider, can supply a tailored description) and otherwise derived from the event.
  </ResponseField>

  <ResponseField name="event_id" type="String (UUID)">
    ID of the event.
  </ResponseField>

  <ResponseField name="event_type" type="Enum (String)">
    Value: `action_attempt.unlock_door.succeeded`
  </ResponseField>

  <ResponseField name="occurred_at" type="String (ISO 8601)">
    Date and time at which the event occurred.
  </ResponseField>

  <ResponseField name="status" type="String">
    Status of the action.
  </ResponseField>

  <ResponseField name="workspace_id" type="String (UUID)">
    ID of the workspace associated with the event.
  </ResponseField>
</Accordion>

## `action_attempt.unlock_door.failed`

An unlock door action attempt failed.

<ResponseExample>
  ```json Example webhook payload theme={null}
  {
    "action_attempt_id": "00000000-0000-0000-0000-000000000000",
    "action_type": "",
    "connected_account_id": "00000000-0000-0000-0000-000000000000",
    "created_at": "2025-01-01T00:00:00.000Z",
    "device_id": "00000000-0000-0000-0000-000000000000",
    "event_description": "An unlock door action attempt failed.",
    "event_id": "00000000-0000-0000-0000-000000000000",
    "event_type": "action_attempt.unlock_door.failed",
    "occurred_at": "2025-01-01T00:00:00.000Z",
    "status": "",
    "workspace_id": "00000000-0000-0000-0000-000000000000"
  }
  ```
</ResponseExample>

<Accordion title="Properties">
  <ResponseField name="action_attempt_id" type="String (UUID)">
    ID of the affected action attempt.
  </ResponseField>

  <ResponseField name="action_type" type="String">
    Type of the action.
  </ResponseField>

  <ResponseField name="connected_account_id" type="String (UUID)">
    ID of the connected account associated with the action attempt, if applicable.
  </ResponseField>

  <ResponseField name="created_at" type="String (ISO 8601)">
    Date and time at which the event was created.
  </ResponseField>

  <ResponseField name="device_id" type="String (UUID)">
    ID of the device associated with the action attempt, if applicable.
  </ResponseField>

  <ResponseField name="event_description" type="String">
    Human-readable description of the event. Persisted when the event is created (so the creating code, including a provider, can supply a tailored description) and otherwise derived from the event.
  </ResponseField>

  <ResponseField name="event_id" type="String (UUID)">
    ID of the event.
  </ResponseField>

  <ResponseField name="event_type" type="Enum (String)">
    Value: `action_attempt.unlock_door.failed`
  </ResponseField>

  <ResponseField name="occurred_at" type="String (ISO 8601)">
    Date and time at which the event occurred.
  </ResponseField>

  <ResponseField name="status" type="String">
    Status of the action.
  </ResponseField>

  <ResponseField name="workspace_id" type="String (UUID)">
    ID of the workspace associated with the event.
  </ResponseField>
</Accordion>

## `action_attempt.simulate_keypad_code_entry.succeeded`

A simulate keypad code entry action attempt succeeded.

<ResponseExample>
  ```json Example webhook payload theme={null}
  {
    "action_attempt_id": "00000000-0000-0000-0000-000000000000",
    "action_type": "",
    "connected_account_id": "00000000-0000-0000-0000-000000000000",
    "created_at": "2025-01-01T00:00:00.000Z",
    "device_id": "00000000-0000-0000-0000-000000000000",
    "event_description": "A simulate keypad code entry action attempt succeeded.",
    "event_id": "00000000-0000-0000-0000-000000000000",
    "event_type": "action_attempt.simulate_keypad_code_entry.succeeded",
    "occurred_at": "2025-01-01T00:00:00.000Z",
    "status": "",
    "workspace_id": "00000000-0000-0000-0000-000000000000"
  }
  ```
</ResponseExample>

<Accordion title="Properties">
  <ResponseField name="action_attempt_id" type="String (UUID)">
    ID of the affected action attempt.
  </ResponseField>

  <ResponseField name="action_type" type="String">
    Type of the action.
  </ResponseField>

  <ResponseField name="connected_account_id" type="String (UUID)">
    ID of the connected account associated with the action attempt, if applicable.
  </ResponseField>

  <ResponseField name="created_at" type="String (ISO 8601)">
    Date and time at which the event was created.
  </ResponseField>

  <ResponseField name="device_id" type="String (UUID)">
    ID of the device associated with the action attempt, if applicable.
  </ResponseField>

  <ResponseField name="event_description" type="String">
    Human-readable description of the event. Persisted when the event is created (so the creating code, including a provider, can supply a tailored description) and otherwise derived from the event.
  </ResponseField>

  <ResponseField name="event_id" type="String (UUID)">
    ID of the event.
  </ResponseField>

  <ResponseField name="event_type" type="Enum (String)">
    Value: `action_attempt.simulate_keypad_code_entry.succeeded`
  </ResponseField>

  <ResponseField name="occurred_at" type="String (ISO 8601)">
    Date and time at which the event occurred.
  </ResponseField>

  <ResponseField name="status" type="String">
    Status of the action.
  </ResponseField>

  <ResponseField name="workspace_id" type="String (UUID)">
    ID of the workspace associated with the event.
  </ResponseField>
</Accordion>

## `action_attempt.simulate_keypad_code_entry.failed`

A simulate keypad code entry action attempt failed.

<ResponseExample>
  ```json Example webhook payload theme={null}
  {
    "action_attempt_id": "00000000-0000-0000-0000-000000000000",
    "action_type": "",
    "connected_account_id": "00000000-0000-0000-0000-000000000000",
    "created_at": "2025-01-01T00:00:00.000Z",
    "device_id": "00000000-0000-0000-0000-000000000000",
    "event_description": "A simulate keypad code entry action attempt failed.",
    "event_id": "00000000-0000-0000-0000-000000000000",
    "event_type": "action_attempt.simulate_keypad_code_entry.failed",
    "occurred_at": "2025-01-01T00:00:00.000Z",
    "status": "",
    "workspace_id": "00000000-0000-0000-0000-000000000000"
  }
  ```
</ResponseExample>

<Accordion title="Properties">
  <ResponseField name="action_attempt_id" type="String (UUID)">
    ID of the affected action attempt.
  </ResponseField>

  <ResponseField name="action_type" type="String">
    Type of the action.
  </ResponseField>

  <ResponseField name="connected_account_id" type="String (UUID)">
    ID of the connected account associated with the action attempt, if applicable.
  </ResponseField>

  <ResponseField name="created_at" type="String (ISO 8601)">
    Date and time at which the event was created.
  </ResponseField>

  <ResponseField name="device_id" type="String (UUID)">
    ID of the device associated with the action attempt, if applicable.
  </ResponseField>

  <ResponseField name="event_description" type="String">
    Human-readable description of the event. Persisted when the event is created (so the creating code, including a provider, can supply a tailored description) and otherwise derived from the event.
  </ResponseField>

  <ResponseField name="event_id" type="String (UUID)">
    ID of the event.
  </ResponseField>

  <ResponseField name="event_type" type="Enum (String)">
    Value: `action_attempt.simulate_keypad_code_entry.failed`
  </ResponseField>

  <ResponseField name="occurred_at" type="String (ISO 8601)">
    Date and time at which the event occurred.
  </ResponseField>

  <ResponseField name="status" type="String">
    Status of the action.
  </ResponseField>

  <ResponseField name="workspace_id" type="String (UUID)">
    ID of the workspace associated with the event.
  </ResponseField>
</Accordion>

## `action_attempt.simulate_manual_lock_via_keypad.succeeded`

A simulate manual lock via keypad action attempt succeeded.

<ResponseExample>
  ```json Example webhook payload theme={null}
  {
    "action_attempt_id": "00000000-0000-0000-0000-000000000000",
    "action_type": "",
    "connected_account_id": "00000000-0000-0000-0000-000000000000",
    "created_at": "2025-01-01T00:00:00.000Z",
    "device_id": "00000000-0000-0000-0000-000000000000",
    "event_description": "A simulate manual lock via keypad action attempt succeeded.",
    "event_id": "00000000-0000-0000-0000-000000000000",
    "event_type": "action_attempt.simulate_manual_lock_via_keypad.succeeded",
    "occurred_at": "2025-01-01T00:00:00.000Z",
    "status": "",
    "workspace_id": "00000000-0000-0000-0000-000000000000"
  }
  ```
</ResponseExample>

<Accordion title="Properties">
  <ResponseField name="action_attempt_id" type="String (UUID)">
    ID of the affected action attempt.
  </ResponseField>

  <ResponseField name="action_type" type="String">
    Type of the action.
  </ResponseField>

  <ResponseField name="connected_account_id" type="String (UUID)">
    ID of the connected account associated with the action attempt, if applicable.
  </ResponseField>

  <ResponseField name="created_at" type="String (ISO 8601)">
    Date and time at which the event was created.
  </ResponseField>

  <ResponseField name="device_id" type="String (UUID)">
    ID of the device associated with the action attempt, if applicable.
  </ResponseField>

  <ResponseField name="event_description" type="String">
    Human-readable description of the event. Persisted when the event is created (so the creating code, including a provider, can supply a tailored description) and otherwise derived from the event.
  </ResponseField>

  <ResponseField name="event_id" type="String (UUID)">
    ID of the event.
  </ResponseField>

  <ResponseField name="event_type" type="Enum (String)">
    Value: `action_attempt.simulate_manual_lock_via_keypad.succeeded`
  </ResponseField>

  <ResponseField name="occurred_at" type="String (ISO 8601)">
    Date and time at which the event occurred.
  </ResponseField>

  <ResponseField name="status" type="String">
    Status of the action.
  </ResponseField>

  <ResponseField name="workspace_id" type="String (UUID)">
    ID of the workspace associated with the event.
  </ResponseField>
</Accordion>

## `action_attempt.simulate_manual_lock_via_keypad.failed`

A simulate manual lock via keypad action attempt failed.

<ResponseExample>
  ```json Example webhook payload theme={null}
  {
    "action_attempt_id": "00000000-0000-0000-0000-000000000000",
    "action_type": "",
    "connected_account_id": "00000000-0000-0000-0000-000000000000",
    "created_at": "2025-01-01T00:00:00.000Z",
    "device_id": "00000000-0000-0000-0000-000000000000",
    "event_description": "A simulate manual lock via keypad action attempt failed.",
    "event_id": "00000000-0000-0000-0000-000000000000",
    "event_type": "action_attempt.simulate_manual_lock_via_keypad.failed",
    "occurred_at": "2025-01-01T00:00:00.000Z",
    "status": "",
    "workspace_id": "00000000-0000-0000-0000-000000000000"
  }
  ```
</ResponseExample>

<Accordion title="Properties">
  <ResponseField name="action_attempt_id" type="String (UUID)">
    ID of the affected action attempt.
  </ResponseField>

  <ResponseField name="action_type" type="String">
    Type of the action.
  </ResponseField>

  <ResponseField name="connected_account_id" type="String (UUID)">
    ID of the connected account associated with the action attempt, if applicable.
  </ResponseField>

  <ResponseField name="created_at" type="String (ISO 8601)">
    Date and time at which the event was created.
  </ResponseField>

  <ResponseField name="device_id" type="String (UUID)">
    ID of the device associated with the action attempt, if applicable.
  </ResponseField>

  <ResponseField name="event_description" type="String">
    Human-readable description of the event. Persisted when the event is created (so the creating code, including a provider, can supply a tailored description) and otherwise derived from the event.
  </ResponseField>

  <ResponseField name="event_id" type="String (UUID)">
    ID of the event.
  </ResponseField>

  <ResponseField name="event_type" type="Enum (String)">
    Value: `action_attempt.simulate_manual_lock_via_keypad.failed`
  </ResponseField>

  <ResponseField name="occurred_at" type="String (ISO 8601)">
    Date and time at which the event occurred.
  </ResponseField>

  <ResponseField name="status" type="String">
    Status of the action.
  </ResponseField>

  <ResponseField name="workspace_id" type="String (UUID)">
    ID of the workspace associated with the event.
  </ResponseField>
</Accordion>


# Get an Action Attempt
Source: https://docs.seam.co/api/action_attempts/get

/openapi.json post /action_attempts/get
Returns a specified [action attempt](/core-concepts/action-attempts).



# List Action Attempts
Source: https://docs.seam.co/api/action_attempts/list

/openapi.json post /action_attempts/list
Returns a list of the [action attempts](/core-concepts/action-attempts) that you specify as an array of `action_attempt_id`s.



# The Action Attempt Object
Source: https://docs.seam.co/api/action_attempts/object

Learn how the action_attempt object tracks an attempt to perform an action against a device, letting you monitor its status and final result.

## The action\_attempt Object

Represents an attempt to perform an action against a device.

<ResponseExample>
  ```json Action Attempt theme={null}
  {
    "action_attempt_id": "3f2b1c8d-1b5e-4f8c-9c7d-9a8b7c6d5e4f",
    "action_type": "LOCK_DOOR",
    "error": null,
    "result": {},
    "status": "success"
  }
  ```
</ResponseExample>

***

## Properties

<ResponseField name="action_attempt_id" type="String (UUID)">
  ID of the action attempt.
</ResponseField>

<ResponseField name="status" type="Enum (String)">
  Status of the action attempt.

  <Accordion title="Enum values">
    * `pending`
    * `success`
    * `error`
  </Accordion>
</ResponseField>

<ResponseField name="action_type" type="Enum (String)">
  Type of the action attempt.

  <Accordion title="Enum values">
    * `LOCK_DOOR`
    * `UNLOCK_DOOR`
    * `SCAN_CREDENTIAL`
    * `ENCODE_CREDENTIAL`
    * `SCAN_TO_ASSIGN_CREDENTIAL`
    * `ASSIGN_CREDENTIAL`
    * `RESET_SANDBOX_WORKSPACE`
    * `SET_FAN_MODE`
    * `SET_HVAC_MODE`
    * `ACTIVATE_CLIMATE_PRESET`
    * `SIMULATE_KEYPAD_CODE_ENTRY`
    * `SIMULATE_MANUAL_LOCK_VIA_KEYPAD`
    * `PUSH_THERMOSTAT_PROGRAMS`
    * `CONFIGURE_AUTO_LOCK`
  </Accordion>
</ResponseField>

<ResponseField name="error" type="Object">
  Error associated with the action attempt. Null for pending and successful action attempts.
</ResponseField>

<ResponseField name="result" type="Object">
  Result of the action attempt. Null for pending and errored action attempts.
</ResponseField>


# Authentication
Source: https://docs.seam.co/api/authentication

Learn how to authenticate with the Seam API by exporting your API key as an environment variable that the Seam client libraries pick up automatically.

Export your API key as an environment variable. Seam client libraries automatically pick up this exported key. For example:

```
$ export SEAM_API_KEY=seam_test2bMS_94SrGUXuNR2JmJkjtvBQDg5c
```

Next, run the following code to confirm that you are correctly authenticated:

<Tabs>
  <Tab title="JavaScript">
    **Code:**

    ```javascript theme={null}
    import { Seam } from 'seam'

    const seam = new Seam() // Seam automatically uses your exported SEAM_API_KEY.

    const checkAuth = async () => {
      const workspace = await seam.workspaces.get()
      console.log(workspace)
    }

    checkAuth()
    ```

    **Output:**

    ```json theme={null}
    {
      workspace_id: '00000000-0000-0000-0000-000000000000',
      name: 'Sandbox',
      company_name: 'Acme',
      connect_partner_name: 'Acme',
      is_sandbox": true
    }
    ```
  </Tab>

  <Tab title="cURL">
    **Code:**

    ```bash theme={null}
    curl -X 'POST' \
      'https://connect.getseam.com/workspaces/get' \
      -H 'accept: application/json' \
      -H "Authorization: Bearer ${SEAM_API_KEY}" \
      -H 'Content-Type: application/json' \
      -d '{}'
    ```

    **Output:**

    ```json theme={null}
    {
      "workspace": {
        "workspace_id": "00000000-0000-0000-0000-000000000000",
        "name": "Sandbox",
        "company_name": "Acme",
        "connect_partner_name": "Acme",
        "is_sandbox": true
      },
      "ok": true
    }
    ```
  </Tab>

  <Tab title="Python">
    **Code:**

    ```python theme={null}
    from seam import Seam

    seam = Seam()  # Seam automatically uses your exported SEAM_API_KEY.

    workspace = seam.workspaces.get()
    pprint(workspace)
    ```

    **Output:**

    ```
    Workspace(
      workspace_id='00000000-0000-0000-0000-000000000000',
      name='Sandbox',
      company_name='Acme',
      connect_partner_name='Acme',
      is_sandbox=True
    )
    ```
  </Tab>

  <Tab title="Ruby">
    **Code:**

    ```ruby theme={null}
    require "seam"

    seam = Seam.new() # Seam automatically uses your exported SEAM_API_KEY.

    workspace = seam.workspaces.get()

    puts workspace.inspect
    ```

    **Output:**

    ```
    <
      Seam::Workspace:0x0070328
        workspace_id="00000000-0000-0000-0000-000000000000"
        name="Sandbox"
        company_name="Acme"
        connect_partner_name="Acme"
        is_sandbox=true
    >
    ```
  </Tab>

  <Tab title="PHP">
    **Code:**

    ```php theme={null}
    <?php
    require 'vendor/autoload.php';

    $seam = new Seam\SeamClient(); // Seam automatically uses your exported SEAM_API_KEY.

    $workspace = $seam->workspaces->get();

    echo json_encode($workspace, JSON_PRETTY_PRINT);
    ```

    **Output:**

    ```json theme={null}
    {
      "workspace_id": "00000000-0000-0000-0000-000000000000",
      "name": "Sandbox",
      "company_name": "Acme",
      "connect_partner_name": "Acme",
      "is_sandbox": true
    }
    ```
  </Tab>

  <Tab title="C#">
    **Code:**

    ```csharp theme={null}
    using Seam.Client;

    var seam = new SeamClient(apiToken: SEAM_API_KEY);

    var workspace = seam.Workspaces.Get();

    Console.WriteLine(workspace);
    ```

    **Output:**

    ```json theme={null}
    {
      "workspace_id": "00000000-0000-0000-0000-000000000000",
      "name": "Sandbox",
      "company_name": "Acme",
      "connect_partner_name": "Acme",
      "is_sandbox": true
    }
    ```
  </Tab>
</Tabs>


# Create a Client Session
Source: https://docs.seam.co/api/client_sessions/create

/openapi.json post /client_sessions/create
Creates a new [client session](/core-concepts/authentication/client-session-tokens).



# Delete a Client Session
Source: https://docs.seam.co/api/client_sessions/delete

/openapi.json post /client_sessions/delete
Deletes a [client session](/core-concepts/authentication/client-session-tokens).



# Client Session Events
Source: https://docs.seam.co/api/client_sessions/events

Webhook events that Seam emits for the Client Session resource, with example payloads and properties.

## `client_session.deleted`

A client session was deleted.

<ResponseExample>
  ```json Example webhook payload theme={null}
  {
    "client_session_id": "00000000-0000-0000-0000-000000000000",
    "created_at": "2025-01-01T00:00:00.000Z",
    "event_description": "A client session was deleted.",
    "event_id": "00000000-0000-0000-0000-000000000000",
    "event_type": "client_session.deleted",
    "occurred_at": "2025-01-01T00:00:00.000Z",
    "workspace_id": "00000000-0000-0000-0000-000000000000"
  }
  ```
</ResponseExample>

<Accordion title="Properties">
  <ResponseField name="client_session_id" type="String (UUID)">
    ID of the affected client session.
  </ResponseField>

  <ResponseField name="created_at" type="String (ISO 8601)">
    Date and time at which the event was created.
  </ResponseField>

  <ResponseField name="event_description" type="String">
    Human-readable description of the event. Persisted when the event is created (so the creating code, including a provider, can supply a tailored description) and otherwise derived from the event.
  </ResponseField>

  <ResponseField name="event_id" type="String (UUID)">
    ID of the event.
  </ResponseField>

  <ResponseField name="event_type" type="Enum (String)">
    Value: `client_session.deleted`
  </ResponseField>

  <ResponseField name="occurred_at" type="String (ISO 8601)">
    Date and time at which the event occurred.
  </ResponseField>

  <ResponseField name="workspace_id" type="String (UUID)">
    ID of the workspace associated with the event.
  </ResponseField>
</Accordion>


# Get a Client Session
Source: https://docs.seam.co/api/client_sessions/get

/openapi.json post /client_sessions/get
Returns a specified [client session](/core-concepts/authentication/client-session-tokens).



# Get or Create a Client Session
Source: https://docs.seam.co/api/client_sessions/get_or_create

/openapi.json post /client_sessions/get_or_create
Returns a [client session](/core-concepts/authentication/client-session-tokens) with specific characteristics or creates a new client session with these characteristics if it does not yet exist.



# Grant Access to a Client Session
Source: https://docs.seam.co/api/client_sessions/grant_access

/openapi.json post /client_sessions/grant_access
Grants a [client session](/core-concepts/authentication/client-session-tokens) access to one or more resources, such as [Connect Webviews](/core-concepts/connect-webviews), [user identities](/capability-guides/mobile-access/managing-mobile-app-user-accounts-with-user-identities#what-is-a-user-identity), and so on.

You must include at least one request parameter.



# List Client Sessions
Source: https://docs.seam.co/api/client_sessions/list

/openapi.json post /client_sessions/list
Returns a list of all [client sessions](/core-concepts/authentication/client-session-tokens).



# The Client Session Object
Source: https://docs.seam.co/api/client_sessions/object

Learn how the client_session object restricts your users to their own devices using a custom user_identifier_key that scopes Seam API results.

## The client\_session Object

Represents a [client session](/core-concepts/authentication/client-session-tokens). If you want to restrict your users' access to their own devices, use client sessions.

You create each client session with a custom `user_identifier_key`. Normally, the `user_identifier_key` is a user ID that your application provides.

When calling the Seam API from your backend using an API key, you can pass the `user_identifier_key` as a parameter to limit results to the associated client session. For example, `/devices/list?user_identifier_key=123` only returns devices associated with the client session created with the `user_identifier_key` `123`.

A client session has a token that you can use with the Seam JavaScript SDK to make requests from the client (browser) directly to the Seam API. The token restricts the user's access to only the devices that they own.

See also [Get Started with React](/ui-components/overview/getting-started-with-seam-components/get-started-with-react-components-and-client-session-tokens).

<ResponseExample>
  ```json Client Session theme={null}
  {
    "client_session_id": "c2cbd177-1ace-414b-bb1e-9f129e4a05c1",
    "connect_webview_ids": [
      "550e8400-e29b-41d4-a716-446655440000"
    ],
    "connected_account_ids": [
      "f47ac10b-58cc-4372-a567-0e02b2c3d479"
    ],
    "created_at": "2025-06-15T16:54:17.946309Z",
    "customer_id": "77eccc4e-c8bc-4c7d-b83c-cb853ed3bade",
    "device_count": 1,
    "expires_at": "2025-06-17T16:54:17.946309Z",
    "token": "seam_cst1891oqCmB_6dBwV8PJ2Fsoe9dWYVyMfVHq",
    "user_identifier_key": "user_id_1",
    "user_identity_id": "a6e93f84-565e-47d7-8908-1ca71ada373c",
    "user_identity_ids": [
      "a6e93f84-565e-47d7-8908-1ca71ada373c"
    ],
    "workspace_id": "b887bf84-9849-4454-a562-cf84293d9781"
  }
  ```
</ResponseExample>

***

## Properties

<ResponseField name="client_session_id" type="String (UUID)">
  ID of the client session.
</ResponseField>

<ResponseField name="connect_webview_ids" type="Array">
  IDs of the [Connect Webviews](/core-concepts/connect-webviews) associated with the [client session](/core-concepts/authentication/client-session-tokens).
</ResponseField>

<ResponseField name="connected_account_ids" type="Array">
  IDs of the [connected accounts](/core-concepts/connected-accounts) associated with the [client session](/core-concepts/authentication/client-session-tokens).
</ResponseField>

<ResponseField name="created_at" type="String (ISO 8601)">
  Date and time at which the [client session](/core-concepts/authentication/client-session-tokens) was created.
</ResponseField>

<ResponseField name="customer_key" type="String">
  Customer key associated with the [client session](/core-concepts/authentication/client-session-tokens).
</ResponseField>

<ResponseField name="device_count" type="number">
  Number of devices associated with the [client session](/core-concepts/authentication/client-session-tokens).
</ResponseField>

<ResponseField name="expires_at" type="String (ISO 8601)">
  Date and time at which the [client session](/core-concepts/authentication/client-session-tokens) expires.
</ResponseField>

<ResponseField name="token" type="String">
  Client session token associated with the [client session](/core-concepts/authentication/client-session-tokens).
</ResponseField>

<ResponseField name="user_identifier_key" type="String">
  Your user ID for the user associated with the [client session](/core-concepts/authentication/client-session-tokens).
</ResponseField>

<ResponseField name="user_identity_id" type="String (UUID)">
  ID of the [user identity](/capability-guides/mobile-access/managing-mobile-app-user-accounts-with-user-identities#what-is-a-user-identity) associated with the client session.
</ResponseField>

<ResponseField name="user_identity_ids" type="Array">
  **Deprecated**. Use `user_identity_id` instead.

  IDs of the [user identities](/capability-guides/mobile-access/managing-mobile-app-user-accounts-with-user-identities#what-is-a-user-identity) associated with the client session.
</ResponseField>

<ResponseField name="workspace_id" type="String (UUID)">
  ID of the workspace associated with the client session.
</ResponseField>


# Revoke a Client Session
Source: https://docs.seam.co/api/client_sessions/revoke

/openapi.json post /client_sessions/revoke
Revokes a [client session](/core-concepts/authentication/client-session-tokens).

Note that [deleting a client session](/api/client_sessions/delete) is a separate action.



# Create a Connect Webview
Source: https://docs.seam.co/api/connect_webviews/create

/openapi.json post /connect_webviews/create
Creates a new [Connect Webview](/core-concepts/connect-webviews).

To enable a user to connect their devices or systems to Seam, they must sign in to their device or system account. To enable a user to sign in, you create a `connect_webview`. After creating the Connect Webview, you receive a URL that you can use to display the visual component of this Connect Webview for your user. You can open an iframe or new window to display the Connect Webview.

You should make a new `connect_webview` for each unique login request. Each `connect_webview` tracks the user that signed in with it. You receive an error if you reuse a Connect Webview for the same user twice or if you use the same Connect Webview for multiple users.

See also: [Connect Webview Process](/core-concepts/connect-webviews/connect-webview-process).



# Delete a Connect Webview
Source: https://docs.seam.co/api/connect_webviews/delete

/openapi.json post /connect_webviews/delete
Deletes a [Connect Webview](/core-concepts/connect-webviews).

You do not need to delete a Connect Webview once a user completes it. Instead, you can simply ignore completed Connect Webviews.



# Connect Webview Events
Source: https://docs.seam.co/api/connect_webviews/events

Webhook events that Seam emits for the Connect Webview resource, with example payloads and properties.

## `connect_webview.login_succeeded`

A Connect Webview login succeeded.

<ResponseExample>
  ```json Example webhook payload theme={null}
  {
    "connect_webview_id": "00000000-0000-0000-0000-000000000000",
    "connected_account_custom_metadata": {},
    "connected_account_id": "00000000-0000-0000-0000-000000000000",
    "created_at": "2025-01-01T00:00:00.000Z",
    "customer_key": "",
    "event_description": "A Connect Webview login succeeded.",
    "event_id": "00000000-0000-0000-0000-000000000000",
    "event_type": "connect_webview.login_succeeded",
    "occurred_at": "2025-01-01T00:00:00.000Z",
    "workspace_id": "00000000-0000-0000-0000-000000000000"
  }
  ```
</ResponseExample>

<Accordion title="Properties">
  <ResponseField name="connect_webview_id" type="String (UUID)">
    ID of the affected Connect Webview.
  </ResponseField>

  <ResponseField name="connected_account_custom_metadata" type="Object">
    Custom metadata of the connected account; present when connected\_account\_id is provided.
  </ResponseField>

  <ResponseField name="connected_account_id" type="String (UUID)">
    ID of the connected account associated with the event.
  </ResponseField>

  <ResponseField name="created_at" type="String (ISO 8601)">
    Date and time at which the event was created.
  </ResponseField>

  <ResponseField name="customer_key" type="String">
    The customer key associated with this connect webview, if any.
  </ResponseField>

  <ResponseField name="event_description" type="String">
    Human-readable description of the event. Persisted when the event is created (so the creating code, including a provider, can supply a tailored description) and otherwise derived from the event.
  </ResponseField>

  <ResponseField name="event_id" type="String (UUID)">
    ID of the event.
  </ResponseField>

  <ResponseField name="event_type" type="Enum (String)">
    Value: `connect_webview.login_succeeded`
  </ResponseField>

  <ResponseField name="occurred_at" type="String (ISO 8601)">
    Date and time at which the event occurred.
  </ResponseField>

  <ResponseField name="workspace_id" type="String (UUID)">
    ID of the workspace associated with the event.
  </ResponseField>
</Accordion>

## `connect_webview.login_failed`

A Connect Webview login failed.

<ResponseExample>
  ```json Example webhook payload theme={null}
  {
    "connect_webview_id": "00000000-0000-0000-0000-000000000000",
    "created_at": "2025-01-01T00:00:00.000Z",
    "event_description": "A Connect Webview login failed.",
    "event_id": "00000000-0000-0000-0000-000000000000",
    "event_type": "connect_webview.login_failed",
    "occurred_at": "2025-01-01T00:00:00.000Z",
    "workspace_id": "00000000-0000-0000-0000-000000000000"
  }
  ```
</ResponseExample>

<Accordion title="Properties">
  <ResponseField name="connect_webview_id" type="String (UUID)">
    ID of the affected Connect Webview.
  </ResponseField>

  <ResponseField name="created_at" type="String (ISO 8601)">
    Date and time at which the event was created.
  </ResponseField>

  <ResponseField name="event_description" type="String">
    Human-readable description of the event. Persisted when the event is created (so the creating code, including a provider, can supply a tailored description) and otherwise derived from the event.
  </ResponseField>

  <ResponseField name="event_id" type="String (UUID)">
    ID of the event.
  </ResponseField>

  <ResponseField name="event_type" type="Enum (String)">
    Value: `connect_webview.login_failed`
  </ResponseField>

  <ResponseField name="occurred_at" type="String (ISO 8601)">
    Date and time at which the event occurred.
  </ResponseField>

  <ResponseField name="workspace_id" type="String (UUID)">
    ID of the workspace associated with the event.
  </ResponseField>
</Accordion>


# Get a Connect Webview
Source: https://docs.seam.co/api/connect_webviews/get

/openapi.json post /connect_webviews/get
Returns a specified [Connect Webview](/core-concepts/connect-webviews).

Unless you're using a `custom_redirect_url`, you should poll a newly-created `connect_webview` to find out if the user has signed in or to get details about what devices they've connected.



# List Connect Webviews
Source: https://docs.seam.co/api/connect_webviews/list

/openapi.json post /connect_webviews/list
Returns a list of all [Connect Webviews](/core-concepts/connect-webviews).



# The Connect Webview Object
Source: https://docs.seam.co/api/connect_webviews/object

Learn how the connect_webview object embeds a client-side flow that walks your users through linking their device or system accounts to Seam.

## The connect\_webview Object

Represents a [Connect Webview](/core-concepts/connect-webviews).

Connect Webviews are fully-embedded client-side components that you add to your app. Your users interact with your embedded Connect Webviews to link their IoT device or system accounts to Seam. That is, Connect Webviews walk your users through the process of logging in to their device or system accounts. Seam handles all the authentication steps, and—once your user has completed the authorization through your app—you can access and control their devices or systems using the Seam API.

Connect Webviews perform credential validation, multifactor authentication (when applicable), and error handling for each brand that Seam supports. Further, Connect Webviews work across all modern browsers and platforms, including Chrome, Safari, and Firefox.

To enable a user to connect their device or system account to Seam through your app, first create a `connect_webview`. Once created, this `connect_webview` includes a URL that you can use to open an [iframe](https://www.w3schools.com/html/html_iframe.asp) or new window containing the Connect Webview for your user.

When you create a Connect Webview, specify the desired provider category key in the `provider_category` parameter. Alternately, to specify a list of providers explicitly, use the `accepted_providers` parameter with a list of device provider keys.

To list all providers within a category, use `/devices/list_device_providers` with the desired `provider_category` filter. To list all provider keys, use `/devices/list_device_providers` with no filters.

<ResponseExample>
  ```json Connect Webview theme={null}
  {
    "accepted_capabilities": [
      "lock",
      "thermostat"
    ],
    "accepted_devices": [],
    "accepted_providers": [
      "schlage",
      "kwikset",
      "yale",
      "smartthings"
    ],
    "any_device_allowed": false,
    "any_provider_allowed": false,
    "authorized_at": "2025-06-14T16:54:17.946323Z",
    "automatically_manage_new_devices": true,
    "connect_webview_id": "c4c30885-ec87-4b31-8d7b-9bc0678fa028",
    "connected_account_id": "5d2fe05f-4f5b-4b91-909c-96e2601dccbe",
    "created_at": "2025-06-14T16:54:17.946323Z",
    "custom_metadata": {
      "id": "internalId1"
    },
    "custom_redirect_failure_url": "https://example.com/failure-redirect",
    "custom_redirect_url": "https://example.com/redirect",
    "device_selection_mode": "single",
    "login_successful": true,
    "selected_provider": "schlage",
    "status": "authorized",
    "url": "https://connect.getseam.com/connect_webviews/view?connect_webview_id=12345678-1234-1234-1234-123456789012&auth_token=2r2Rn8V5QUtxE79gNsTmLK58KkuqrwU8d",
    "wait_for_device_creation": true,
    "workspace_id": "9db95105-e77d-4577-b1b7-0a20b360d5e0"
  }
  ```
</ResponseExample>

***

## Properties

<ResponseField name="accepted_capabilities" type="Array">
  High-level device capabilities that the Connect Webview can accept. When creating a Connect Webview, you can specify the types of devices that it can connect to Seam. If you do not set custom `accepted_capabilities`, Seam uses a default set of `accepted_capabilities` for each provider. For example, if you create a Connect Webview that accepts SmartThing devices, without specifying `accepted_capabilities`, Seam accepts only SmartThings locks. To connect SmartThings thermostats and locks to Seam, create a Connect Webview and include both `thermostat` and `lock` in the `accepted_capabilities`.
</ResponseField>

<ResponseField name="accepted_providers" type="Array">
  List of accepted [provider keys](/core-concepts/connect-webviews/customizing-connect-webviews#customize-the-brands-to-display-in-your-connect-webviews).
</ResponseField>

<ResponseField name="any_provider_allowed" type="Boolean">
  Indicates whether any provider is allowed.
</ResponseField>

<ResponseField name="authorized_at" type="String (ISO 8601)">
  Date and time at which the user authorized (through the Connect Webview) the management of their devices.
</ResponseField>

<ResponseField name="automatically_manage_new_devices" type="Boolean">
  Indicates whether Seam should [import all new devices](/core-concepts/connect-webviews/customizing-connect-webviews#automatically_manage_new_devices) for the connected account to make these devices available for use and management by the Seam API.
</ResponseField>

<ResponseField name="connect_webview_id" type="String (UUID)">
  ID of the Connect Webview.
</ResponseField>

<ResponseField name="connected_account_id" type="String (UUID)">
  ID of the connected account associated with the Connect Webview.
</ResponseField>

<ResponseField name="created_at" type="String (ISO 8601)">
  Date and time at which the Connect Webview was created.
</ResponseField>

<ResponseField name="custom_metadata" type="Object">
  Set of key:value pairs. Adding custom metadata to a resource, such as a [Connect Webview](/core-concepts/connect-webviews/attaching-custom-data-to-the-connect-webview), [connected account](/core-concepts/connected-accounts/adding-custom-metadata-to-a-connected-account), or [device](/core-concepts/devices/adding-custom-metadata-to-a-device), enables you to store custom information, like customer details or internal IDs from your application.
</ResponseField>

<ResponseField name="custom_redirect_failure_url" type="String">
  URL to which the Connect Webview should redirect when an unexpected error occurs.
</ResponseField>

<ResponseField name="custom_redirect_url" type="String">
  URL to which the Connect Webview should redirect when the user successfully pairs a device or system. If you do not set the `custom_redirect_failure_url`, the Connect Webview redirects to the `custom_redirect_url` when an unexpected error occurs.
</ResponseField>

<ResponseField name="customer_key" type="String">
  The customer key associated with this webview, if any.
</ResponseField>

<ResponseField name="device_selection_mode" type="Enum (String)">
  Device selection mode of the Connect Webview. Supported values: `none`, `single`, `multiple`.
</ResponseField>

<ResponseField name="login_successful" type="Boolean">
  Indicates whether the user logged in successfully using the Connect Webview.
</ResponseField>

<ResponseField name="selected_provider" type="String">
  Selected provider of the Connect Webview, one of the [provider keys](/core-concepts/connect-webviews/customizing-connect-webviews#customize-the-brands-to-display-in-your-connect-webviews).
</ResponseField>

<ResponseField name="status" type="Enum (String)">
  Status of the Connect Webview. `authorized` indicates that the user has successfully logged into their device or system account, thereby completing the Connect Webview.
</ResponseField>

<ResponseField name="url" type="String">
  URL for the Connect Webview. You use the URL to display the Connect Webview flow to your user.
</ResponseField>

<ResponseField name="wait_for_device_creation" type="Boolean">
  Indicates whether Seam should [finish syncing all devices](/core-concepts/connect-webviews/customizing-connect-webviews#wait_for_device_creation) in a newly-connected account before completing the associated Connect Webview.
</ResponseField>

<ResponseField name="workspace_id" type="String (UUID)">
  ID of the workspace that contains the Connect Webview.
</ResponseField>


# Delete a Connected Account
Source: https://docs.seam.co/api/connected_accounts/delete

/openapi.json post /connected_accounts/delete
Deletes a specified [connected account](/core-concepts/connected-accounts).

Deleting a connected account triggers a `connected_account.deleted` event and removes the connected account and all data associated with the connected account from Seam, including devices, events, access codes, and so on. For every deleted resource, Seam sends a corresponding deleted event, but the resource is not deleted from the provider.

For example, if you delete a connected account with a device that has an access code, Seam sends a `connected_account.deleted` event, a `device.deleted` event, and an `access_code.deleted` event, but Seam does not remove the access code from the device.



# Connected Account Errors and Warnings
Source: https://docs.seam.co/api/connected_accounts/errors

Errors and warnings that Seam reports on the Connected Account resource, each with its code and meaning.

## Errors

Each error is an object with the following shape:

```json Example error theme={null}
{
  "error_code": "account_disconnected",
  "message": "Indicates that the account is disconnected.",
  "created_at": "2025-01-01T00:00:00.000Z",
  "is_bridge_error": true,
  "is_connected_account_error": true
}
```

<Accordion title="Error object properties">
  <ResponseField name="error_code" type="Enum (String)">
    Unique identifier of the type of error. Enables quick recognition and categorization of the issue.

    One of the error codes listed below.
  </ResponseField>

  <ResponseField name="message" type="String">
    Detailed description of the error. Provides insights into the issue and potentially how to rectify it.
  </ResponseField>

  <ResponseField name="created_at" type="String (ISO 8601)">
    Date and time at which Seam created the error.
  </ResponseField>

  <ResponseField name="is_bridge_error" type="Boolean">
    Indicates whether the error is related to [Seam Bridge](/capability-guides/seam-bridge).
  </ResponseField>

  <ResponseField name="is_connected_account_error" type="Boolean">
    Indicates whether the error is related specifically to the connected account.
  </ResponseField>

  <ResponseField name="salto_ks_metadata" type="Object">
    Salto KS metadata associated with the connected account that has an error.
  </ResponseField>
</Accordion>

### `account_disconnected`

Indicates that the account is disconnected.

***

### `bridge_disconnected`

Indicates that the Seam API cannot communicate with [Seam Bridge](/capability-guides/seam-bridge), for example, if the Seam Bridge executable has stopped or if the computer running the Seam Bridge executable is offline. See also [Troubleshooting Your Access Control System](/low-level-apis/access-systems/troubleshooting-your-access-control-system#acs_system-errors-seam_bridge_disconnected).

***

### `dormakaba_sites_disconnected`

Indicates that one or more dormakaba sites associated with the connected account could not be connected. Contact dormakaba support.

***

### `salto_ks_subscription_limit_exceeded`

Indicates that the maximum number of users allowed for the site has been reached. This means that new access codes cannot be created. Contact Salto support to increase the user limit.

***

## Warnings

Each warning is an object with the following shape:

```json Example warning theme={null}
{
  "warning_code": "scheduled_maintenance_window",
  "message": "Indicates that scheduled downtime is planned for the connected account.",
  "created_at": "2025-01-01T00:00:00.000Z"
}
```

<Accordion title="Warning object properties">
  <ResponseField name="warning_code" type="Enum (String)">
    Unique identifier of the type of warning. Enables quick recognition and categorization of the issue.

    One of the warning codes listed below.
  </ResponseField>

  <ResponseField name="message" type="String">
    Detailed description of the warning. Provides insights into the issue and potentially how to rectify it.
  </ResponseField>

  <ResponseField name="created_at" type="String (ISO 8601)">
    Date and time at which Seam created the warning.
  </ResponseField>

  <ResponseField name="salto_ks_metadata" type="Object">
    Salto KS metadata associated with the connected account that has a warning.
  </ResponseField>
</Accordion>

### `account_reauthorization_requested`

Indicates that the Connected Account requires reauthorization using a new Connect Webview. The account is still connected, but cannot access new features. Delaying reauthorization too long will eventually cause the Connected Account to become disconnected.

***

### `being_deleted`

Indicates that the connected account is currently being deleted. All devices, access codes, and other resources associated with this account are in the process of being removed from Seam.

***

### `dormakaba_sites_unapproved`

Indicates that one or more dormakaba sites associated with the connected account are not approved. Contact [support@getseam.com](mailto:support@getseam.com) to finish setting up your account.

***

### `provider_service_unavailable`

Indicates that the connected account's provider service is temporarily unavailable. Seam will automatically retry and reconnect when the service becomes available again.

***

### `salto_ks_subscription_limit_almost_reached`

Indicates that the Salto KS site has exceeded 80% of the maximum number of allowed users. Increase your subscription limit or delete some users from your site.

***

### `scheduled_maintenance_window`

Indicates that scheduled downtime is planned for the connected account.

***

### `setup_required`

Indicates that the connected account requires additional setup before it can be fully operational. Follow the instructions in the warning message to complete the setup.

***

### `unknown_issue_with_connected_account`

Indicates that an unknown issue occurred while syncing the state of the connected account with the provider. This issue may affect the proper functioning of one or more resources in the account.

***


# Connected Account Events
Source: https://docs.seam.co/api/connected_accounts/events

Webhook events that Seam emits for the Connected Account resource, with example payloads and properties.

## `connected_account.connected`

A connected account was connected for the first time or was reconnected after being disconnected.

<ResponseExample>
  ```json Example webhook payload theme={null}
  {
    "connect_webview_id": "00000000-0000-0000-0000-000000000000",
    "connected_account_custom_metadata": {},
    "connected_account_id": "00000000-0000-0000-0000-000000000000",
    "created_at": "2025-01-01T00:00:00.000Z",
    "customer_key": "",
    "event_description": "A connected account was connected for the first time or was reconnected after being disconnected.",
    "event_id": "00000000-0000-0000-0000-000000000000",
    "event_type": "connected_account.connected",
    "occurred_at": "2025-01-01T00:00:00.000Z",
    "workspace_id": "00000000-0000-0000-0000-000000000000"
  }
  ```
</ResponseExample>

<Accordion title="Properties">
  <ResponseField name="connect_webview_id" type="String (UUID)">
    ID of the Connect Webview associated with the event.
  </ResponseField>

  <ResponseField name="connected_account_custom_metadata" type="Object">
    Custom metadata of the connected account, present when connected\_account\_id is provided.
  </ResponseField>

  <ResponseField name="connected_account_id" type="String (UUID)">
    ID of the affected connected account.
  </ResponseField>

  <ResponseField name="created_at" type="String (ISO 8601)">
    Date and time at which the event was created.
  </ResponseField>

  <ResponseField name="customer_key" type="String">
    The customer key associated with this connected account, if any.
  </ResponseField>

  <ResponseField name="event_description" type="String">
    Human-readable description of the event. Persisted when the event is created (so the creating code, including a provider, can supply a tailored description) and otherwise derived from the event.
  </ResponseField>

  <ResponseField name="event_id" type="String (UUID)">
    ID of the event.
  </ResponseField>

  <ResponseField name="event_type" type="Enum (String)">
    Value: `connected_account.connected`
  </ResponseField>

  <ResponseField name="occurred_at" type="String (ISO 8601)">
    Date and time at which the event occurred.
  </ResponseField>

  <ResponseField name="workspace_id" type="String (UUID)">
    ID of the workspace associated with the event.
  </ResponseField>
</Accordion>

## `connected_account.created`

A connected account was created.

<ResponseExample>
  ```json Example webhook payload theme={null}
  {
    "connect_webview_id": "00000000-0000-0000-0000-000000000000",
    "connected_account_custom_metadata": {},
    "connected_account_id": "00000000-0000-0000-0000-000000000000",
    "created_at": "2025-01-01T00:00:00.000Z",
    "event_description": "A connected account was created.",
    "event_id": "00000000-0000-0000-0000-000000000000",
    "event_type": "connected_account.created",
    "occurred_at": "2025-01-01T00:00:00.000Z",
    "workspace_id": "00000000-0000-0000-0000-000000000000"
  }
  ```
</ResponseExample>

<Accordion title="Properties">
  <ResponseField name="connect_webview_id" type="String (UUID)">
    ID of the Connect Webview associated with the event.
  </ResponseField>

  <ResponseField name="connected_account_custom_metadata" type="Object">
    Custom metadata of the connected account, present when connected\_account\_id is provided.
  </ResponseField>

  <ResponseField name="connected_account_id" type="String (UUID)">
    ID of the affected connected account.
  </ResponseField>

  <ResponseField name="created_at" type="String (ISO 8601)">
    Date and time at which the event was created.
  </ResponseField>

  <ResponseField name="event_description" type="String">
    Human-readable description of the event. Persisted when the event is created (so the creating code, including a provider, can supply a tailored description) and otherwise derived from the event.
  </ResponseField>

  <ResponseField name="event_id" type="String (UUID)">
    ID of the event.
  </ResponseField>

  <ResponseField name="event_type" type="Enum (String)">
    Value: `connected_account.created`
  </ResponseField>

  <ResponseField name="occurred_at" type="String (ISO 8601)">
    Date and time at which the event occurred.
  </ResponseField>

  <ResponseField name="workspace_id" type="String (UUID)">
    ID of the workspace associated with the event.
  </ResponseField>
</Accordion>

## `connected_account.successful_login`

A connected account had a successful login using a Connect Webview.

<ResponseExample>
  ```json Example webhook payload theme={null}
  {
    "connect_webview_id": "00000000-0000-0000-0000-000000000000",
    "connected_account_custom_metadata": {},
    "connected_account_id": "00000000-0000-0000-0000-000000000000",
    "created_at": "2025-01-01T00:00:00.000Z",
    "event_description": "A connected account had a successful login using a Connect Webview.",
    "event_id": "00000000-0000-0000-0000-000000000000",
    "event_type": "connected_account.successful_login",
    "occurred_at": "2025-01-01T00:00:00.000Z",
    "workspace_id": "00000000-0000-0000-0000-000000000000"
  }
  ```
</ResponseExample>

<Accordion title="Properties">
  <ResponseField name="connect_webview_id" type="String (UUID)">
    ID of the Connect Webview associated with the event.
  </ResponseField>

  <ResponseField name="connected_account_custom_metadata" type="Object">
    Custom metadata of the connected account, present when connected\_account\_id is provided.
  </ResponseField>

  <ResponseField name="connected_account_id" type="String (UUID)">
    ID of the affected connected account.
  </ResponseField>

  <ResponseField name="created_at" type="String (ISO 8601)">
    Date and time at which the event was created.
  </ResponseField>

  <ResponseField name="event_description" type="String">
    Human-readable description of the event. Persisted when the event is created (so the creating code, including a provider, can supply a tailored description) and otherwise derived from the event.
  </ResponseField>

  <ResponseField name="event_id" type="String (UUID)">
    ID of the event.
  </ResponseField>

  <ResponseField name="event_type" type="Enum (String)">
    Value: `connected_account.successful_login`
  </ResponseField>

  <ResponseField name="occurred_at" type="String (ISO 8601)">
    Date and time at which the event occurred.
  </ResponseField>

  <ResponseField name="workspace_id" type="String (UUID)">
    ID of the workspace associated with the event.
  </ResponseField>
</Accordion>

## `connected_account.disconnected`

A connected account was disconnected.

<ResponseExample>
  ```json Example webhook payload theme={null}
  {
    "connected_account_custom_metadata": {},
    "connected_account_errors": [],
    "connected_account_id": "00000000-0000-0000-0000-000000000000",
    "connected_account_warnings": [],
    "created_at": "2025-01-01T00:00:00.000Z",
    "event_description": "A connected account was disconnected.",
    "event_id": "00000000-0000-0000-0000-000000000000",
    "event_type": "connected_account.disconnected",
    "occurred_at": "2025-01-01T00:00:00.000Z",
    "workspace_id": "00000000-0000-0000-0000-000000000000"
  }
  ```
</ResponseExample>

<Accordion title="Properties">
  <ResponseField name="connected_account_custom_metadata" type="Object">
    Custom metadata of the connected account, present when connected\_account\_id is provided.
  </ResponseField>

  <ResponseField name="connected_account_errors" type="Array">
    Errors associated with the connected account.
  </ResponseField>

  <ResponseField name="connected_account_id" type="String (UUID)">
    ID of the affected connected account.
  </ResponseField>

  <ResponseField name="connected_account_warnings" type="Array">
    Warnings associated with the connected account.
  </ResponseField>

  <ResponseField name="created_at" type="String (ISO 8601)">
    Date and time at which the event was created.
  </ResponseField>

  <ResponseField name="event_description" type="String">
    Human-readable description of the event. Persisted when the event is created (so the creating code, including a provider, can supply a tailored description) and otherwise derived from the event.
  </ResponseField>

  <ResponseField name="event_id" type="String (UUID)">
    ID of the event.
  </ResponseField>

  <ResponseField name="event_type" type="Enum (String)">
    Value: `connected_account.disconnected`
  </ResponseField>

  <ResponseField name="occurred_at" type="String (ISO 8601)">
    Date and time at which the event occurred.
  </ResponseField>

  <ResponseField name="workspace_id" type="String (UUID)">
    ID of the workspace associated with the event.
  </ResponseField>
</Accordion>

## `connected_account.completed_first_sync`

A connected account completed the first sync with Seam, and the corresponding devices or systems are now available.

<ResponseExample>
  ```json Example webhook payload theme={null}
  {
    "connected_account_custom_metadata": {},
    "connected_account_id": "00000000-0000-0000-0000-000000000000",
    "created_at": "2025-01-01T00:00:00.000Z",
    "event_description": "A connected account completed the first sync with Seam, and the corresponding devices or systems are now available.",
    "event_id": "00000000-0000-0000-0000-000000000000",
    "event_type": "connected_account.completed_first_sync",
    "occurred_at": "2025-01-01T00:00:00.000Z",
    "workspace_id": "00000000-0000-0000-0000-000000000000"
  }
  ```
</ResponseExample>

<Accordion title="Properties">
  <ResponseField name="connected_account_custom_metadata" type="Object">
    Custom metadata of the connected account, present when connected\_account\_id is provided.
  </ResponseField>

  <ResponseField name="connected_account_id" type="String (UUID)">
    ID of the affected connected account.
  </ResponseField>

  <ResponseField name="created_at" type="String (ISO 8601)">
    Date and time at which the event was created.
  </ResponseField>

  <ResponseField name="event_description" type="String">
    Human-readable description of the event. Persisted when the event is created (so the creating code, including a provider, can supply a tailored description) and otherwise derived from the event.
  </ResponseField>

  <ResponseField name="event_id" type="String (UUID)">
    ID of the event.
  </ResponseField>

  <ResponseField name="event_type" type="Enum (String)">
    Value: `connected_account.completed_first_sync`
  </ResponseField>

  <ResponseField name="occurred_at" type="String (ISO 8601)">
    Date and time at which the event occurred.
  </ResponseField>

  <ResponseField name="workspace_id" type="String (UUID)">
    ID of the workspace associated with the event.
  </ResponseField>
</Accordion>

## `connected_account.deleted`

A connected account was deleted.

<ResponseExample>
  ```json Example webhook payload theme={null}
  {
    "connected_account_custom_metadata": {},
    "connected_account_id": "00000000-0000-0000-0000-000000000000",
    "created_at": "2025-01-01T00:00:00.000Z",
    "customer_key": "",
    "event_description": "A connected account was deleted.",
    "event_id": "00000000-0000-0000-0000-000000000000",
    "event_type": "connected_account.deleted",
    "occurred_at": "2025-01-01T00:00:00.000Z",
    "workspace_id": "00000000-0000-0000-0000-000000000000"
  }
  ```
</ResponseExample>

<Accordion title="Properties">
  <ResponseField name="connected_account_custom_metadata" type="Object">
    Custom metadata of the connected account, present when connected\_account\_id is provided.
  </ResponseField>

  <ResponseField name="connected_account_id" type="String (UUID)">
    ID of the affected connected account.
  </ResponseField>

  <ResponseField name="created_at" type="String (ISO 8601)">
    Date and time at which the event was created.
  </ResponseField>

  <ResponseField name="customer_key" type="String">
    The customer key associated with this connected account, if any.
  </ResponseField>

  <ResponseField name="event_description" type="String">
    Human-readable description of the event. Persisted when the event is created (so the creating code, including a provider, can supply a tailored description) and otherwise derived from the event.
  </ResponseField>

  <ResponseField name="event_id" type="String (UUID)">
    ID of the event.
  </ResponseField>

  <ResponseField name="event_type" type="Enum (String)">
    Value: `connected_account.deleted`
  </ResponseField>

  <ResponseField name="occurred_at" type="String (ISO 8601)">
    Date and time at which the event occurred.
  </ResponseField>

  <ResponseField name="workspace_id" type="String (UUID)">
    ID of the workspace associated with the event.
  </ResponseField>
</Accordion>

## `connected_account.completed_first_sync_after_reconnection`

A connected account completed the first sync after reconnection with Seam, and the corresponding devices or systems are now available.

<ResponseExample>
  ```json Example webhook payload theme={null}
  {
    "connected_account_custom_metadata": {},
    "connected_account_id": "00000000-0000-0000-0000-000000000000",
    "created_at": "2025-01-01T00:00:00.000Z",
    "event_description": "A connected account completed the first sync after reconnection with Seam, and the corresponding devices or systems are now available.",
    "event_id": "00000000-0000-0000-0000-000000000000",
    "event_type": "connected_account.completed_first_sync_after_reconnection",
    "occurred_at": "2025-01-01T00:00:00.000Z",
    "workspace_id": "00000000-0000-0000-0000-000000000000"
  }
  ```
</ResponseExample>

<Accordion title="Properties">
  <ResponseField name="connected_account_custom_metadata" type="Object">
    Custom metadata of the connected account, present when connected\_account\_id is provided.
  </ResponseField>

  <ResponseField name="connected_account_id" type="String (UUID)">
    ID of the affected connected account.
  </ResponseField>

  <ResponseField name="created_at" type="String (ISO 8601)">
    Date and time at which the event was created.
  </ResponseField>

  <ResponseField name="event_description" type="String">
    Human-readable description of the event. Persisted when the event is created (so the creating code, including a provider, can supply a tailored description) and otherwise derived from the event.
  </ResponseField>

  <ResponseField name="event_id" type="String (UUID)">
    ID of the event.
  </ResponseField>

  <ResponseField name="event_type" type="Enum (String)">
    Value: `connected_account.completed_first_sync_after_reconnection`
  </ResponseField>

  <ResponseField name="occurred_at" type="String (ISO 8601)">
    Date and time at which the event occurred.
  </ResponseField>

  <ResponseField name="workspace_id" type="String (UUID)">
    ID of the workspace associated with the event.
  </ResponseField>
</Accordion>

## `connected_account.reauthorization_requested`

A connected account requires reauthorization using a new Connect Webview. The account is still connected, but cannot access new features. Delaying reauthorization too long will eventually cause the Connected Account to become disconnected.

<ResponseExample>
  ```json Example webhook payload theme={null}
  {
    "connected_account_custom_metadata": {},
    "connected_account_errors": [],
    "connected_account_id": "00000000-0000-0000-0000-000000000000",
    "connected_account_warnings": [],
    "created_at": "2025-01-01T00:00:00.000Z",
    "event_description": "A connected account requires reauthorization using a new Connect Webview. The account is still connected, but cannot access new features. Delaying reauthorization too long will eventually cause the Connected Account to become disconnected.",
    "event_id": "00000000-0000-0000-0000-000000000000",
    "event_type": "connected_account.reauthorization_requested",
    "occurred_at": "2025-01-01T00:00:00.000Z",
    "workspace_id": "00000000-0000-0000-0000-000000000000"
  }
  ```
</ResponseExample>

<Accordion title="Properties">
  <ResponseField name="connected_account_custom_metadata" type="Object">
    Custom metadata of the connected account, present when connected\_account\_id is provided.
  </ResponseField>

  <ResponseField name="connected_account_errors" type="Array">
    Errors associated with the connected account.
  </ResponseField>

  <ResponseField name="connected_account_id" type="String (UUID)">
    ID of the affected connected account.
  </ResponseField>

  <ResponseField name="connected_account_warnings" type="Array">
    Warnings associated with the connected account.
  </ResponseField>

  <ResponseField name="created_at" type="String (ISO 8601)">
    Date and time at which the event was created.
  </ResponseField>

  <ResponseField name="event_description" type="String">
    Human-readable description of the event. Persisted when the event is created (so the creating code, including a provider, can supply a tailored description) and otherwise derived from the event.
  </ResponseField>

  <ResponseField name="event_id" type="String (UUID)">
    ID of the event.
  </ResponseField>

  <ResponseField name="event_type" type="Enum (String)">
    Value: `connected_account.reauthorization_requested`
  </ResponseField>

  <ResponseField name="occurred_at" type="String (ISO 8601)">
    Date and time at which the event occurred.
  </ResponseField>

  <ResponseField name="workspace_id" type="String (UUID)">
    ID of the workspace associated with the event.
  </ResponseField>
</Accordion>


# Get a Connected Account
Source: https://docs.seam.co/api/connected_accounts/get

/openapi.json post /connected_accounts/get
Returns a specified [connected account](/core-concepts/connected-accounts).

You must include at least one request parameter.



# List Connected Accounts
Source: https://docs.seam.co/api/connected_accounts/list

/openapi.json post /connected_accounts/list
Returns a list of all [connected accounts](/core-concepts/connected-accounts).



# The Connected Account Object
Source: https://docs.seam.co/api/connected_accounts/object

Learn how the connected_account object represents an external third-party account your user has authorized Seam to access, such as an August account.

## The connected\_account Object

Represents a [connected account](/core-concepts/connected-accounts). A connected account is an external third-party account to which your user has authorized Seam to get access, for example, an August account with a list of door locks.

<ResponseExample>
  ```json Connected Account theme={null}
  {
    "account_type": "salto_space",
    "account_type_display_name": "Salto Space",
    "display_name": "j**n@example.com",
    "automatically_manage_new_devices": true,
    "connected_account_id": "a289aa54-5488-4707-9a4b-eeea4edf311d",
    "created_at": "2025-06-15T16:54:17.946329Z",
    "custom_metadata": {
      "id": "internalId1"
    },
    "errors": [],
    "user_identifier": {
      "api_url": "https://example.com/api",
      "email": "jane_doe@example.com",
      "exclusive": true,
      "phone": "+1555551004",
      "username": "jane_doe"
    },
    "warnings": [],
    "accepted_capabilities": [
      "lock"
    ]
  }
  ```
</ResponseExample>

***

## Properties

<ResponseField name="accepted_capabilities" type="Array">
  List of capabilities that were accepted during the account connection process.
</ResponseField>

<ResponseField name="account_type" type="String">
  Type of connected account.
</ResponseField>

<ResponseField name="account_type_display_name" type="String">
  Display name for the connected account type.
</ResponseField>

<ResponseField name="automatically_manage_new_devices" type="Boolean">
  Indicates whether Seam should [import all new devices](/core-concepts/connect-webviews/customizing-connect-webviews#automatically_manage_new_devices) for the connected account to make these devices available for management by the Seam API.
</ResponseField>

<ResponseField name="connected_account_id" type="String (UUID)">
  ID of the connected account.
</ResponseField>

<ResponseField name="created_at" type="String (ISO 8601)">
  Date and time at which the connected account was created.
</ResponseField>

<ResponseField name="custom_metadata" type="Object">
  Set of key:value pairs. Adding custom metadata to a resource, such as a [Connect Webview](/core-concepts/connect-webviews/attaching-custom-data-to-the-connect-webview), [connected account](/core-concepts/connected-accounts/adding-custom-metadata-to-a-connected-account), or [device](/core-concepts/devices/adding-custom-metadata-to-a-device), enables you to store custom information, like customer details or internal IDs from your application.
</ResponseField>

<ResponseField name="customer_key" type="String">
  Your unique key for the customer associated with this connected account.
</ResponseField>

<ResponseField name="default_checkin_time" type="String">
  Default reservation check-in time for this connected account, as `HH:mm` (24-hour). Sourced from the connector configuration — set during the connect\_webview for providers like Lodgify whose API does not expose check-in times.
</ResponseField>

<ResponseField name="default_checkout_time" type="String">
  Default reservation check-out time for this connected account, as `HH:mm` (24-hour). Sourced from the connector configuration.
</ResponseField>

<ResponseField name="display_name" type="String">
  Display name for the connected account.
</ResponseField>

<ResponseField name="errors" type="Array">
  Errors associated with the connected account.
</ResponseField>

<ResponseField name="ical_feed_origin" type="String">
  For iCal connected accounts, the platform that produced the feed (for example, `airbnb`, `vrbo`, or `booking`), or `unknown` when it could not be determined. Intended for rendering the source platform's logo.
</ResponseField>

<ResponseField name="ical_url" type="String">
  For iCal connected accounts, the feed URL for the connection. Sourced from the connector configuration.
</ResponseField>

<ResponseField name="image_url" type="String">
  Logo URL for the connected account provider.
</ResponseField>

<ResponseField name="time_zone" type="String">
  IANA time zone (e.g. America/Los\_Angeles) for this connected account. Sourced from the connector configuration.
</ResponseField>

<ResponseField name="user_identifier" type="Object">
  **Deprecated**. Use `display_name` instead.

  User identifier associated with the connected account.

  <Expandable title="properties">
    <ResponseField name="api_url" type="String">
      API URL for the user identifier associated with the connected account.
    </ResponseField>

    <ResponseField name="email" type="String">
      Email address of the user identifier associated with the connected account.
    </ResponseField>

    <ResponseField name="exclusive" type="Boolean">
      Indicates whether the user identifier associated with the connected account is exclusive.
    </ResponseField>

    <ResponseField name="phone" type="String">
      Phone number of the user identifier associated with the connected account.
    </ResponseField>

    <ResponseField name="username" type="String">
      Username of the user identifier associated with the connected account.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="warnings" type="Array">
  Warnings associated with the connected account.
</ResponseField>


# Simulate Connected Account Disconnection
Source: https://docs.seam.co/api/connected_accounts/simulate/disconnect

/openapi.json post /connected_accounts/simulate/disconnect
Simulates a connected account becoming disconnected from Seam. Only applicable for [sandbox workspaces](/core-concepts/workspaces#sandbox-workspaces).



# Sync a Connected Account
Source: https://docs.seam.co/api/connected_accounts/sync

/openapi.json post /connected_accounts/sync
Request a [connected account](/core-concepts/connected-accounts) sync attempt for the specified `connected_account_id`.



# Update a Connected Account
Source: https://docs.seam.co/api/connected_accounts/update

/openapi.json post /connected_accounts/update
Updates a [connected account](/core-concepts/connected-accounts).



# Create Customer Portal
Source: https://docs.seam.co/api/customers/create_portal

/openapi.json post /customers/create_portal
Creates a new customer portal magic link with configurable features.



# Delete Customer Data
Source: https://docs.seam.co/api/customers/delete_data

/openapi.json post /customers/delete_data
Deletes customer data including resources like spaces, properties, rooms, users, etc.
This will delete the partner resources and any related Seam resources (user identities, access grants, spaces).



# The Customer Object
Source: https://docs.seam.co/api/customers/object

Learn how the customer_portal object provides a hosted, customizable interface for managing device access that you can share or embed in your product.

## The customer\_portal Object

Represents a Customer Portal. Customer Portal is a hosted, customizable interface for managing device access. It enables you to embed secure, pre-authenticated access flows into your product—either by sharing a link with users or embedding a view in an iframe.

With Customer Portal, you no longer need to build out frontend experiences for physical access, thermostats, and sensors. Instead, you can ship enterprise-grade access control experiences in a fraction of the time, while maintaining your product's branding and user experience.

Seam hosts these flows, handling everything from account connection and device mapping to full-featured device control.

<ResponseExample>
  ```json Customer Portal theme={null}
  {
    "created_at": "2025-06-16T16:54:17.946594Z",
    "customer_key": "My Company",
    "expires_at": "2025-06-17T16:54:17.946594Z",
    "url": "https://se.am/1234",
    "workspace_id": "67c58f1f-f148-4415-a63c-dc6c145c6b91"
  }
  ```
</ResponseExample>

***

## Properties

<ResponseField name="created_at" type="String (ISO 8601)">
  Date and time at which the customer portal link was created.
</ResponseField>

<ResponseField name="customer_key" type="String">
  Customer key for the customer portal.
</ResponseField>

<ResponseField name="expires_at" type="String (ISO 8601)">
  Date and time at which the customer portal link expires.
</ResponseField>

<ResponseField name="url" type="String">
  URL for the customer portal.
</ResponseField>

<ResponseField name="workspace_id" type="String (UUID)">
  ID of the workspace associated with the customer portal.
</ResponseField>


# Push Customer Data
Source: https://docs.seam.co/api/customers/push_data

/openapi.json post /customers/push_data
Pushes customer data including resources like spaces, properties, rooms, users, etc.



# Device Errors and Warnings
Source: https://docs.seam.co/api/devices/errors

Errors and warnings that Seam reports on the Device resource, each with its code and meaning.

## Errors

Each error is an object with the following shape:

```json Example error theme={null}
{
  "error_code": "account_disconnected",
  "message": "Indicates that the account is disconnected.",
  "created_at": "2025-01-01T00:00:00.000Z",
  "is_connected_account_error": true,
  "is_device_error": true
}
```

<Accordion title="Error object properties">
  <ResponseField name="error_code" type="Enum (String)">
    Unique identifier of the type of error. Enables quick recognition and categorization of the issue.

    One of the error codes listed below.
  </ResponseField>

  <ResponseField name="message" type="String">
    Detailed description of the error. Provides insights into the issue and potentially how to rectify it.
  </ResponseField>

  <ResponseField name="created_at" type="String (ISO 8601)">
    Date and time at which Seam created the error.
  </ResponseField>

  <ResponseField name="is_bridge_error" type="Boolean">
    Indicates whether the error is related to [Seam Bridge](/capability-guides/seam-bridge).
  </ResponseField>

  <ResponseField name="is_connected_account_error" type="Boolean">
    Indicates that the error is a [connected account](/api/connected_accounts/object) error.
  </ResponseField>

  <ResponseField name="is_device_error" type="Boolean">
    Indicates that the error is not a device error.
  </ResponseField>
</Accordion>

### `device_disconnected`

Indicates that the device is disconnected.

***

### `device_offline`

Indicates that the device is offline.

***

### `device_removed`

Indicates that the device has been removed.

***

### `hub_disconnected`

Indicates that the hub is disconnected.

***

### `missing_device_credentials`

Indicates that device credentials are missing.

***

### `subscription_required`

Indicates that a subscription is required to connect.

***

### Access Codes

#### `empty_backup_access_code_pool`

Indicates that the [backup access code pool](/low-level-apis/smart-locks/access-codes/backup-access-codes) is empty.

***

### Locks

#### `august_lock_not_authorized`

Indicates that the user is not authorized to use the August lock.

***

### Thermostats

#### `auxiliary_heat_running`

Indicates that the auxiliary heat is running.

***

### Connected Account

<Note>
  These errors are inherited from the [Connected Account](/api/connected_accounts/errors) resource. When they are set on the parent connected account, they are propagated to this resource's errors list.
</Note>

#### `account_disconnected`

Indicates that the account is disconnected.

***

#### `bridge_disconnected`

Indicates that the Seam API cannot communicate with [Seam Bridge](/capability-guides/seam-bridge), for example, if the Seam Bridge executable has stopped or if the computer running the Seam Bridge executable is offline. See also [Troubleshooting Your Access Control System](/low-level-apis/access-systems/troubleshooting-your-access-control-system#acs_system-errors-seam_bridge_disconnected).

***

#### `dormakaba_sites_disconnected`

Indicates that one or more dormakaba sites associated with the connected account could not be connected. Contact dormakaba support.

***

#### `insufficient_permissions`

Indicates that Seam's integration user does not have sufficient permissions on the provider's system to which this device belongs, so Seam cannot manage access codes or unlock the device. See the error message for specifics, then either reauthorize the connected account in Seam or grant the integration user the required permissions in the provider's system.

***

#### `salto_ks_subscription_limit_exceeded`

Indicates that the Salto site user limit has been reached.

***

## Warnings

Each warning is an object with the following shape:

```json Example warning theme={null}
{
  "warning_code": "partial_backup_access_code_pool",
  "message": "Indicates that the backup access code is unhealthy.",
  "created_at": "2025-01-01T00:00:00.000Z"
}
```

<Accordion title="Warning object properties">
  <ResponseField name="warning_code" type="Enum (String)">
    Unique identifier of the type of warning. Enables quick recognition and categorization of the issue.

    One of the warning codes listed below.
  </ResponseField>

  <ResponseField name="message" type="String">
    Detailed description of the warning. Provides insights into the issue and potentially how to rectify it.
  </ResponseField>

  <ResponseField name="created_at" type="String (ISO 8601)">
    Date and time at which Seam created the warning.
  </ResponseField>

  <ResponseField name="active_access_code_count" type="number">
    Number of active access codes on the device when the warning was set.
  </ResponseField>

  <ResponseField name="max_active_access_code_count" type="number">
    Maximum number of active access codes supported by the device.
  </ResponseField>
</Accordion>

### `device_communication_degraded`

Indicates that the device appears to be unresponsive.

***

### `device_has_flaky_connection`

Indicates that the device has a flaky connection.

***

### `scheduled_maintenance_window`

Indicates that a scheduled maintenance window has been detected.

***

### `third_party_integration_detected`

Indicates that a third-party integration has been detected.

***

### Access Codes

#### `many_active_backup_codes`

Indicates that there are too many backup codes.

***

#### `max_access_codes_reached`

Indicates that the device has reached its maximum number of active access codes. Delete existing codes before creating new ones.

***

#### `partial_backup_access_code_pool`

Indicates that the backup access code is unhealthy.

***

#### `privacy_mode`

Indicates that the lock is in Privacy Mode. Access codes and remote unlock are blocked until Privacy Mode is disabled.

***

#### `provider_issue`

Indicates a provider-specific issue that may affect device functionality.

***

#### `salto_ks_lock_access_code_support_removed`

Indicates that a change in the reported device model has been detected for this Salto KS lock, which may occur after an IQ hub reset. Access code support may be affected. See [https://help.getseam.com/articles/5098842588-salto-ks-lock-loses-access-code-support](https://help.getseam.com/articles/5098842588-salto-ks-lock-loses-access-code-support) for troubleshooting steps.

***

#### `salto_ks_office_mode`

Indicates that the Salto KS lock is in Office Mode. Access Codes will not unlock doors.

***

#### `salto_ks_privacy_mode`

Indicates that the Salto KS lock is in Privacy Mode. Access Codes will not unlock doors.

***

### Locks

#### `accessory_keypad_setup_required`

Indicates that the accessory keypad exists, but is not linked to the Igloohome Bridge. Online access code programming will fail until the keypad is linked to the Igloohome Bridge in the Igloohome app.

***

#### `hub_required_for_additional_capabilities`

Indicates that a hub or relay must be connected to unlock additional capabilities such as remote unlock.

***

#### `keynest_unsupported_locker`

Indicates that the key is in a locker that does not support the access codes API.

***

#### `lockly_time_zone_not_configured`

Indicates that Seam detected that the Lockly device does not have a time zone configured. Time-bound codes may not work as expected.

***

#### `power_saving_mode`

Indicates that the device is in power saving mode and may have limited functionality.

***

#### `salto_ks_subscription_limit_almost_reached`

Indicates that the Salto KS site has exceeded 80% of the maximum number of allowed users. Increase your subscription limit or delete some users from your site.

***

#### `time_zone_mismatch`

Indicates that the device's configured time zone does not match its hardware UTC offset. Time-bound access codes may activate at the wrong local time.

***

#### `time_zone_unknown`

Indicates that Seam does not know the device's time zone. Set a time zone to enable time-bound access codes.

***

#### `ttlock_lock_gateway_unlocking_not_enabled`

Indicates that the Remote Unlock feature is not enabled in the settings."

***

#### `ttlock_weak_gateway_signal`

Indicates that the gateway signal is weak.

***

#### `two_n_device_missing_timezone`

Indicates that the 2N device does not have a time zone configured. Configure a time zone on the device to enable access codes.

***

#### `ultraloq_time_zone_unknown`

Indicates that Seam does not know the time zone of the Ultraloq device. Set a time zone to enable time-bound access codes.

***

#### `unreliable_online_status`

Indicates that the device may optimistically be reported as online because the provider does not reliably report its online status.

***

### Phones

#### `unknown_issue_with_phone`

Indicates that an unknown issue occurred while syncing the state of the phone with the provider. This issue may affect the proper functioning of the phone.

***

### Thermostats

#### `temperature_threshold_exceeded`

Indicates that the temperature threshold has been exceeded.

***


# Device Events
Source: https://docs.seam.co/api/devices/events

Webhook events that Seam emits for the Device resource, with example payloads and properties.

## `device.connected`

The status of a device changed from offline to online. That is, the `device.properties.online` property changed from `false` to `true`. Note that some devices operate entirely in offline mode, so Seam never emits a `device.connected` event for these devices.

<ResponseExample>
  ```json Example webhook payload theme={null}
  {
    "connected_account_custom_metadata": {},
    "connected_account_id": "00000000-0000-0000-0000-000000000000",
    "created_at": "2025-01-01T00:00:00.000Z",
    "customer_key": "",
    "device_custom_metadata": {},
    "device_id": "00000000-0000-0000-0000-000000000000",
    "event_description": "The status of a device changed from offline to online. That is, the `device.properties.online` property changed from `false` to `true`. Note that some devices operate entirely in offline mode, so Seam never emits a `device.connected` event for these devices.",
    "event_id": "00000000-0000-0000-0000-000000000000",
    "event_type": "device.connected",
    "occurred_at": "2025-01-01T00:00:00.000Z",
    "workspace_id": "00000000-0000-0000-0000-000000000000"
  }
  ```
</ResponseExample>

<Accordion title="Properties">
  <ResponseField name="connected_account_custom_metadata" type="Object">
    Custom metadata of the connected account, present when connected\_account\_id is provided.
  </ResponseField>

  <ResponseField name="connected_account_id" type="String (UUID)">
    ID of the connected account associated with the event.
  </ResponseField>

  <ResponseField name="created_at" type="String (ISO 8601)">
    Date and time at which the event was created.
  </ResponseField>

  <ResponseField name="customer_key" type="String">
    The customer key associated with the device, if any.
  </ResponseField>

  <ResponseField name="device_custom_metadata" type="Object">
    Custom metadata of the device, present when device\_id is provided.
  </ResponseField>

  <ResponseField name="device_id" type="String (UUID)">
    ID of the affected device.
  </ResponseField>

  <ResponseField name="event_description" type="String">
    Human-readable description of the event. Persisted when the event is created (so the creating code, including a provider, can supply a tailored description) and otherwise derived from the event.
  </ResponseField>

  <ResponseField name="event_id" type="String (UUID)">
    ID of the event.
  </ResponseField>

  <ResponseField name="event_type" type="Enum (String)">
    Value: `device.connected`
  </ResponseField>

  <ResponseField name="occurred_at" type="String (ISO 8601)">
    Date and time at which the event occurred.
  </ResponseField>

  <ResponseField name="workspace_id" type="String (UUID)">
    ID of the workspace associated with the event.
  </ResponseField>
</Accordion>

## `device.added`

A device was added to Seam or was re-added to Seam after having been removed.

<ResponseExample>
  ```json Example webhook payload theme={null}
  {
    "connected_account_custom_metadata": {},
    "connected_account_id": "00000000-0000-0000-0000-000000000000",
    "created_at": "2025-01-01T00:00:00.000Z",
    "customer_key": "",
    "device_custom_metadata": {},
    "device_id": "00000000-0000-0000-0000-000000000000",
    "event_description": "A device was added to Seam or was re-added to Seam after having been removed.",
    "event_id": "00000000-0000-0000-0000-000000000000",
    "event_type": "device.added",
    "occurred_at": "2025-01-01T00:00:00.000Z",
    "workspace_id": "00000000-0000-0000-0000-000000000000"
  }
  ```
</ResponseExample>

<Accordion title="Properties">
  <ResponseField name="connected_account_custom_metadata" type="Object">
    Custom metadata of the connected account, present when connected\_account\_id is provided.
  </ResponseField>

  <ResponseField name="connected_account_id" type="String (UUID)">
    ID of the connected account associated with the event.
  </ResponseField>

  <ResponseField name="created_at" type="String (ISO 8601)">
    Date and time at which the event was created.
  </ResponseField>

  <ResponseField name="customer_key" type="String">
    The customer key associated with the device, if any.
  </ResponseField>

  <ResponseField name="device_custom_metadata" type="Object">
    Custom metadata of the device, present when device\_id is provided.
  </ResponseField>

  <ResponseField name="device_id" type="String (UUID)">
    ID of the affected device.
  </ResponseField>

  <ResponseField name="event_description" type="String">
    Human-readable description of the event. Persisted when the event is created (so the creating code, including a provider, can supply a tailored description) and otherwise derived from the event.
  </ResponseField>

  <ResponseField name="event_id" type="String (UUID)">
    ID of the event.
  </ResponseField>

  <ResponseField name="event_type" type="Enum (String)">
    Value: `device.added`
  </ResponseField>

  <ResponseField name="occurred_at" type="String (ISO 8601)">
    Date and time at which the event occurred.
  </ResponseField>

  <ResponseField name="workspace_id" type="String (UUID)">
    ID of the workspace associated with the event.
  </ResponseField>
</Accordion>

## `device.converted_to_unmanaged`

A managed device was successfully converted to an [unmanaged device](/core-concepts/devices/managed-and-unmanaged-devices).

<ResponseExample>
  ```json Example webhook payload theme={null}
  {
    "connected_account_custom_metadata": {},
    "connected_account_id": "00000000-0000-0000-0000-000000000000",
    "created_at": "2025-01-01T00:00:00.000Z",
    "customer_key": "",
    "device_custom_metadata": {},
    "device_id": "00000000-0000-0000-0000-000000000000",
    "event_description": "A managed device was successfully converted to an [unmanaged device](/core-concepts/devices/managed-and-unmanaged-devices).",
    "event_id": "00000000-0000-0000-0000-000000000000",
    "event_type": "device.converted_to_unmanaged",
    "occurred_at": "2025-01-01T00:00:00.000Z",
    "workspace_id": "00000000-0000-0000-0000-000000000000"
  }
  ```
</ResponseExample>

<Accordion title="Properties">
  <ResponseField name="connected_account_custom_metadata" type="Object">
    Custom metadata of the connected account, present when connected\_account\_id is provided.
  </ResponseField>

  <ResponseField name="connected_account_id" type="String (UUID)">
    ID of the connected account associated with the event.
  </ResponseField>

  <ResponseField name="created_at" type="String (ISO 8601)">
    Date and time at which the event was created.
  </ResponseField>

  <ResponseField name="customer_key" type="String">
    The customer key associated with the device, if any.
  </ResponseField>

  <ResponseField name="device_custom_metadata" type="Object">
    Custom metadata of the device, present when device\_id is provided.
  </ResponseField>

  <ResponseField name="device_id" type="String (UUID)">
    ID of the affected device.
  </ResponseField>

  <ResponseField name="event_description" type="String">
    Human-readable description of the event. Persisted when the event is created (so the creating code, including a provider, can supply a tailored description) and otherwise derived from the event.
  </ResponseField>

  <ResponseField name="event_id" type="String (UUID)">
    ID of the event.
  </ResponseField>

  <ResponseField name="event_type" type="Enum (String)">
    Value: `device.converted_to_unmanaged`
  </ResponseField>

  <ResponseField name="occurred_at" type="String (ISO 8601)">
    Date and time at which the event occurred.
  </ResponseField>

  <ResponseField name="workspace_id" type="String (UUID)">
    ID of the workspace associated with the event.
  </ResponseField>
</Accordion>

## `device.disconnected`

The status of a device changed from online to offline. That is, the `device.properties.online` property changed from `true` to `false`.

<ResponseExample>
  ```json Example webhook payload theme={null}
  {
    "connected_account_custom_metadata": {},
    "connected_account_errors": [],
    "connected_account_id": "00000000-0000-0000-0000-000000000000",
    "connected_account_warnings": [],
    "created_at": "2025-01-01T00:00:00.000Z",
    "customer_key": "",
    "device_custom_metadata": {},
    "device_errors": [],
    "device_id": "00000000-0000-0000-0000-000000000000",
    "device_warnings": [],
    "error_code": "account_disconnected",
    "event_description": "The status of a device changed from online to offline. That is, the `device.properties.online` property changed from `true` to `false`.",
    "event_id": "00000000-0000-0000-0000-000000000000",
    "event_type": "device.disconnected",
    "occurred_at": "2025-01-01T00:00:00.000Z",
    "workspace_id": "00000000-0000-0000-0000-000000000000"
  }
  ```
</ResponseExample>

<Accordion title="Properties">
  <ResponseField name="connected_account_custom_metadata" type="Object">
    Custom metadata of the connected account, present when connected\_account\_id is provided.
  </ResponseField>

  <ResponseField name="connected_account_errors" type="Array">
    Errors associated with the connected account.
  </ResponseField>

  <ResponseField name="connected_account_id" type="String (UUID)">
    ID of the connected account associated with the event.
  </ResponseField>

  <ResponseField name="connected_account_warnings" type="Array">
    Warnings associated with the connected account.
  </ResponseField>

  <ResponseField name="created_at" type="String (ISO 8601)">
    Date and time at which the event was created.
  </ResponseField>

  <ResponseField name="customer_key" type="String">
    The customer key associated with the device, if any.
  </ResponseField>

  <ResponseField name="device_custom_metadata" type="Object">
    Custom metadata of the device, present when device\_id is provided.
  </ResponseField>

  <ResponseField name="device_errors" type="Array">
    Errors associated with the device.
  </ResponseField>

  <ResponseField name="device_id" type="String (UUID)">
    ID of the affected device.
  </ResponseField>

  <ResponseField name="device_warnings" type="Array">
    Warnings associated with the device.
  </ResponseField>

  <ResponseField name="error_code" type="Enum (String)">
    Error code associated with the disconnection event, if any.

    Possible values: `account_disconnected`, `hub_disconnected`, `device_disconnected`
  </ResponseField>

  <ResponseField name="event_description" type="String">
    Human-readable description of the event. Persisted when the event is created (so the creating code, including a provider, can supply a tailored description) and otherwise derived from the event.
  </ResponseField>

  <ResponseField name="event_id" type="String (UUID)">
    ID of the event.
  </ResponseField>

  <ResponseField name="event_type" type="Enum (String)">
    Value: `device.disconnected`
  </ResponseField>

  <ResponseField name="occurred_at" type="String (ISO 8601)">
    Date and time at which the event occurred.
  </ResponseField>

  <ResponseField name="workspace_id" type="String (UUID)">
    ID of the workspace associated with the event.
  </ResponseField>
</Accordion>

## `device.tampered`

A device detected that it was tampered with, for example, opened or moved.

<ResponseExample>
  ```json Example webhook payload theme={null}
  {
    "connected_account_custom_metadata": {},
    "connected_account_id": "00000000-0000-0000-0000-000000000000",
    "created_at": "2025-01-01T00:00:00.000Z",
    "customer_key": "",
    "device_custom_metadata": {},
    "device_id": "00000000-0000-0000-0000-000000000000",
    "event_description": "A device detected that it was tampered with, for example, opened or moved.",
    "event_id": "00000000-0000-0000-0000-000000000000",
    "event_type": "device.tampered",
    "occurred_at": "2025-01-01T00:00:00.000Z",
    "workspace_id": "00000000-0000-0000-0000-000000000000"
  }
  ```
</ResponseExample>

<Accordion title="Properties">
  <ResponseField name="connected_account_custom_metadata" type="Object">
    Custom metadata of the connected account, present when connected\_account\_id is provided.
  </ResponseField>

  <ResponseField name="connected_account_id" type="String (UUID)">
    ID of the connected account associated with the event.
  </ResponseField>

  <ResponseField name="created_at" type="String (ISO 8601)">
    Date and time at which the event was created.
  </ResponseField>

  <ResponseField name="customer_key" type="String">
    The customer key associated with the device, if any.
  </ResponseField>

  <ResponseField name="device_custom_metadata" type="Object">
    Custom metadata of the device, present when device\_id is provided.
  </ResponseField>

  <ResponseField name="device_id" type="String (UUID)">
    ID of the affected device.
  </ResponseField>

  <ResponseField name="event_description" type="String">
    Human-readable description of the event. Persisted when the event is created (so the creating code, including a provider, can supply a tailored description) and otherwise derived from the event.
  </ResponseField>

  <ResponseField name="event_id" type="String (UUID)">
    ID of the event.
  </ResponseField>

  <ResponseField name="event_type" type="Enum (String)">
    Value: `device.tampered`
  </ResponseField>

  <ResponseField name="occurred_at" type="String (ISO 8601)">
    Date and time at which the event occurred.
  </ResponseField>

  <ResponseField name="workspace_id" type="String (UUID)">
    ID of the workspace associated with the event.
  </ResponseField>
</Accordion>

## `device.low_battery`

A device battery level dropped below the low threshold.

<ResponseExample>
  ```json Example webhook payload theme={null}
  {
    "battery_level": 0,
    "connected_account_custom_metadata": {},
    "connected_account_id": "00000000-0000-0000-0000-000000000000",
    "created_at": "2025-01-01T00:00:00.000Z",
    "customer_key": "",
    "device_custom_metadata": {},
    "device_id": "00000000-0000-0000-0000-000000000000",
    "event_description": "A device battery level dropped below the low threshold.",
    "event_id": "00000000-0000-0000-0000-000000000000",
    "event_type": "device.low_battery",
    "occurred_at": "2025-01-01T00:00:00.000Z",
    "workspace_id": "00000000-0000-0000-0000-000000000000"
  }
  ```
</ResponseExample>

<Accordion title="Properties">
  <ResponseField name="battery_level" type="number">
    Number in the range 0 to 1.0 indicating the amount of battery in the affected device, as reported by the device.
  </ResponseField>

  <ResponseField name="connected_account_custom_metadata" type="Object">
    Custom metadata of the connected account, present when connected\_account\_id is provided.
  </ResponseField>

  <ResponseField name="connected_account_id" type="String (UUID)">
    ID of the connected account associated with the event.
  </ResponseField>

  <ResponseField name="created_at" type="String (ISO 8601)">
    Date and time at which the event was created.
  </ResponseField>

  <ResponseField name="customer_key" type="String">
    The customer key associated with the device, if any.
  </ResponseField>

  <ResponseField name="device_custom_metadata" type="Object">
    Custom metadata of the device, present when device\_id is provided.
  </ResponseField>

  <ResponseField name="device_id" type="String (UUID)">
    ID of the affected device.
  </ResponseField>

  <ResponseField name="event_description" type="String">
    Human-readable description of the event. Persisted when the event is created (so the creating code, including a provider, can supply a tailored description) and otherwise derived from the event.
  </ResponseField>

  <ResponseField name="event_id" type="String (UUID)">
    ID of the event.
  </ResponseField>

  <ResponseField name="event_type" type="Enum (String)">
    Value: `device.low_battery`
  </ResponseField>

  <ResponseField name="occurred_at" type="String (ISO 8601)">
    Date and time at which the event occurred.
  </ResponseField>

  <ResponseField name="workspace_id" type="String (UUID)">
    ID of the workspace associated with the event.
  </ResponseField>
</Accordion>

## `device.battery_status_changed`

A device battery status changed since the last `battery_status_changed` event.

<ResponseExample>
  ```json Example webhook payload theme={null}
  {
    "battery_level": 0,
    "battery_status": "critical",
    "connected_account_custom_metadata": {},
    "connected_account_id": "00000000-0000-0000-0000-000000000000",
    "created_at": "2025-01-01T00:00:00.000Z",
    "customer_key": "",
    "device_custom_metadata": {},
    "device_id": "00000000-0000-0000-0000-000000000000",
    "event_description": "A device battery status changed since the last `battery_status_changed` event.",
    "event_id": "00000000-0000-0000-0000-000000000000",
    "event_type": "device.battery_status_changed",
    "occurred_at": "2025-01-01T00:00:00.000Z",
    "workspace_id": "00000000-0000-0000-0000-000000000000"
  }
  ```
</ResponseExample>

<Accordion title="Properties">
  <ResponseField name="battery_level" type="number">
    Number in the range 0 to 1.0 indicating the amount of battery in the affected device, as reported by the device.
  </ResponseField>

  <ResponseField name="battery_status" type="Enum (String)">
    Battery status of the affected device, calculated from the numeric `battery_level` value.

    Possible values: `critical`, `low`, `good`, `full`
  </ResponseField>

  <ResponseField name="connected_account_custom_metadata" type="Object">
    Custom metadata of the connected account, present when connected\_account\_id is provided.
  </ResponseField>

  <ResponseField name="connected_account_id" type="String (UUID)">
    ID of the connected account associated with the event.
  </ResponseField>

  <ResponseField name="created_at" type="String (ISO 8601)">
    Date and time at which the event was created.
  </ResponseField>

  <ResponseField name="customer_key" type="String">
    The customer key associated with the device, if any.
  </ResponseField>

  <ResponseField name="device_custom_metadata" type="Object">
    Custom metadata of the device, present when device\_id is provided.
  </ResponseField>

  <ResponseField name="device_id" type="String (UUID)">
    ID of the affected device.
  </ResponseField>

  <ResponseField name="event_description" type="String">
    Human-readable description of the event. Persisted when the event is created (so the creating code, including a provider, can supply a tailored description) and otherwise derived from the event.
  </ResponseField>

  <ResponseField name="event_id" type="String (UUID)">
    ID of the event.
  </ResponseField>

  <ResponseField name="event_type" type="Enum (String)">
    Value: `device.battery_status_changed`
  </ResponseField>

  <ResponseField name="occurred_at" type="String (ISO 8601)">
    Date and time at which the event occurred.
  </ResponseField>

  <ResponseField name="workspace_id" type="String (UUID)">
    ID of the workspace associated with the event.
  </ResponseField>
</Accordion>

## `device.removed`

A device was removed externally from the connected account.

<ResponseExample>
  ```json Example webhook payload theme={null}
  {
    "connected_account_custom_metadata": {},
    "connected_account_id": "00000000-0000-0000-0000-000000000000",
    "created_at": "2025-01-01T00:00:00.000Z",
    "customer_key": "",
    "device_custom_metadata": {},
    "device_id": "00000000-0000-0000-0000-000000000000",
    "event_description": "A device was removed externally from the connected account.",
    "event_id": "00000000-0000-0000-0000-000000000000",
    "event_type": "device.removed",
    "occurred_at": "2025-01-01T00:00:00.000Z",
    "workspace_id": "00000000-0000-0000-0000-000000000000"
  }
  ```
</ResponseExample>

<Accordion title="Properties">
  <ResponseField name="connected_account_custom_metadata" type="Object">
    Custom metadata of the connected account, present when connected\_account\_id is provided.
  </ResponseField>

  <ResponseField name="connected_account_id" type="String (UUID)">
    ID of the connected account associated with the event.
  </ResponseField>

  <ResponseField name="created_at" type="String (ISO 8601)">
    Date and time at which the event was created.
  </ResponseField>

  <ResponseField name="customer_key" type="String">
    The customer key associated with the device, if any.
  </ResponseField>

  <ResponseField name="device_custom_metadata" type="Object">
    Custom metadata of the device, present when device\_id is provided.
  </ResponseField>

  <ResponseField name="device_id" type="String (UUID)">
    ID of the affected device.
  </ResponseField>

  <ResponseField name="event_description" type="String">
    Human-readable description of the event. Persisted when the event is created (so the creating code, including a provider, can supply a tailored description) and otherwise derived from the event.
  </ResponseField>

  <ResponseField name="event_id" type="String (UUID)">
    ID of the event.
  </ResponseField>

  <ResponseField name="event_type" type="Enum (String)">
    Value: `device.removed`
  </ResponseField>

  <ResponseField name="occurred_at" type="String (ISO 8601)">
    Date and time at which the event occurred.
  </ResponseField>

  <ResponseField name="workspace_id" type="String (UUID)">
    ID of the workspace associated with the event.
  </ResponseField>
</Accordion>

## `device.deleted`

A device was deleted.

<ResponseExample>
  ```json Example webhook payload theme={null}
  {
    "connected_account_custom_metadata": {},
    "connected_account_id": "00000000-0000-0000-0000-000000000000",
    "created_at": "2025-01-01T00:00:00.000Z",
    "customer_key": "",
    "device_custom_metadata": {},
    "device_id": "00000000-0000-0000-0000-000000000000",
    "device_name": "",
    "event_description": "A device was deleted.",
    "event_id": "00000000-0000-0000-0000-000000000000",
    "event_type": "device.deleted",
    "occurred_at": "2025-01-01T00:00:00.000Z",
    "workspace_id": "00000000-0000-0000-0000-000000000000"
  }
  ```
</ResponseExample>

<Accordion title="Properties">
  <ResponseField name="connected_account_custom_metadata" type="Object">
    Custom metadata of the connected account, present when connected\_account\_id is provided.
  </ResponseField>

  <ResponseField name="connected_account_id" type="String (UUID)">
    ID of the connected account associated with the event.
  </ResponseField>

  <ResponseField name="created_at" type="String (ISO 8601)">
    Date and time at which the event was created.
  </ResponseField>

  <ResponseField name="customer_key" type="String">
    The customer key associated with the device, if any.
  </ResponseField>

  <ResponseField name="device_custom_metadata" type="Object">
    Custom metadata of the device, present when device\_id is provided.
  </ResponseField>

  <ResponseField name="device_id" type="String (UUID)">
    ID of the affected device.
  </ResponseField>

  <ResponseField name="device_name" type="String">
    Name of the deleted device, captured at deletion time. The device record no longer exists when this event fires, so the name is preserved here. Null when the device had no resolvable name.
  </ResponseField>

  <ResponseField name="event_description" type="String">
    Human-readable description of the event. Persisted when the event is created (so the creating code, including a provider, can supply a tailored description) and otherwise derived from the event.
  </ResponseField>

  <ResponseField name="event_id" type="String (UUID)">
    ID of the event.
  </ResponseField>

  <ResponseField name="event_type" type="Enum (String)">
    Value: `device.deleted`
  </ResponseField>

  <ResponseField name="occurred_at" type="String (ISO 8601)">
    Date and time at which the event occurred.
  </ResponseField>

  <ResponseField name="workspace_id" type="String (UUID)">
    ID of the workspace associated with the event.
  </ResponseField>
</Accordion>

## `device.third_party_integration_detected`

Seam detected that a device is using a third-party integration that will interfere with Seam device management.

<ResponseExample>
  ```json Example webhook payload theme={null}
  {
    "connected_account_custom_metadata": {},
    "connected_account_id": "00000000-0000-0000-0000-000000000000",
    "created_at": "2025-01-01T00:00:00.000Z",
    "customer_key": "",
    "device_custom_metadata": {},
    "device_id": "00000000-0000-0000-0000-000000000000",
    "event_description": "Seam detected that a device is using a third-party integration that will interfere with Seam device management.",
    "event_id": "00000000-0000-0000-0000-000000000000",
    "event_type": "device.third_party_integration_detected",
    "occurred_at": "2025-01-01T00:00:00.000Z",
    "workspace_id": "00000000-0000-0000-0000-000000000000"
  }
  ```
</ResponseExample>

<Accordion title="Properties">
  <ResponseField name="connected_account_custom_metadata" type="Object">
    Custom metadata of the connected account, present when connected\_account\_id is provided.
  </ResponseField>

  <ResponseField name="connected_account_id" type="String (UUID)">
    ID of the connected account associated with the event.
  </ResponseField>

  <ResponseField name="created_at" type="String (ISO 8601)">
    Date and time at which the event was created.
  </ResponseField>

  <ResponseField name="customer_key" type="String">
    The customer key associated with the device, if any.
  </ResponseField>

  <ResponseField name="device_custom_metadata" type="Object">
    Custom metadata of the device, present when device\_id is provided.
  </ResponseField>

  <ResponseField name="device_id" type="String (UUID)">
    ID of the affected device.
  </ResponseField>

  <ResponseField name="event_description" type="String">
    Human-readable description of the event. Persisted when the event is created (so the creating code, including a provider, can supply a tailored description) and otherwise derived from the event.
  </ResponseField>

  <ResponseField name="event_id" type="String (UUID)">
    ID of the event.
  </ResponseField>

  <ResponseField name="event_type" type="Enum (String)">
    Value: `device.third_party_integration_detected`
  </ResponseField>

  <ResponseField name="occurred_at" type="String (ISO 8601)">
    Date and time at which the event occurred.
  </ResponseField>

  <ResponseField name="workspace_id" type="String (UUID)">
    ID of the workspace associated with the event.
  </ResponseField>
</Accordion>

## `device.third_party_integration_no_longer_detected`

Seam detected that a device is no longer using a third-party integration that was interfering with Seam device management.

<ResponseExample>
  ```json Example webhook payload theme={null}
  {
    "connected_account_custom_metadata": {},
    "connected_account_id": "00000000-0000-0000-0000-000000000000",
    "created_at": "2025-01-01T00:00:00.000Z",
    "customer_key": "",
    "device_custom_metadata": {},
    "device_id": "00000000-0000-0000-0000-000000000000",
    "event_description": "Seam detected that a device is no longer using a third-party integration that was interfering with Seam device management.",
    "event_id": "00000000-0000-0000-0000-000000000000",
    "event_type": "device.third_party_integration_no_longer_detected",
    "occurred_at": "2025-01-01T00:00:00.000Z",
    "workspace_id": "00000000-0000-0000-0000-000000000000"
  }
  ```
</ResponseExample>

<Accordion title="Properties">
  <ResponseField name="connected_account_custom_metadata" type="Object">
    Custom metadata of the connected account, present when connected\_account\_id is provided.
  </ResponseField>

  <ResponseField name="connected_account_id" type="String (UUID)">
    ID of the connected account associated with the event.
  </ResponseField>

  <ResponseField name="created_at" type="String (ISO 8601)">
    Date and time at which the event was created.
  </ResponseField>

  <ResponseField name="customer_key" type="String">
    The customer key associated with the device, if any.
  </ResponseField>

  <ResponseField name="device_custom_metadata" type="Object">
    Custom metadata of the device, present when device\_id is provided.
  </ResponseField>

  <ResponseField name="device_id" type="String (UUID)">
    ID of the affected device.
  </ResponseField>

  <ResponseField name="event_description" type="String">
    Human-readable description of the event. Persisted when the event is created (so the creating code, including a provider, can supply a tailored description) and otherwise derived from the event.
  </ResponseField>

  <ResponseField name="event_id" type="String (UUID)">
    ID of the event.
  </ResponseField>

  <ResponseField name="event_type" type="Enum (String)">
    Value: `device.third_party_integration_no_longer_detected`
  </ResponseField>

  <ResponseField name="occurred_at" type="String (ISO 8601)">
    Date and time at which the event occurred.
  </ResponseField>

  <ResponseField name="workspace_id" type="String (UUID)">
    ID of the workspace associated with the event.
  </ResponseField>
</Accordion>

## `device.salto.privacy_mode_activated`

A [Salto device](/device-and-system-integration-guides/salto-locks) activated privacy mode.

<ResponseExample>
  ```json Example webhook payload theme={null}
  {
    "connected_account_custom_metadata": {},
    "connected_account_id": "00000000-0000-0000-0000-000000000000",
    "created_at": "2025-01-01T00:00:00.000Z",
    "customer_key": "",
    "device_custom_metadata": {},
    "device_id": "00000000-0000-0000-0000-000000000000",
    "event_description": "A [Salto device](/device-and-system-integration-guides/salto-locks) activated privacy mode.",
    "event_id": "00000000-0000-0000-0000-000000000000",
    "event_type": "device.salto.privacy_mode_activated",
    "occurred_at": "2025-01-01T00:00:00.000Z",
    "workspace_id": "00000000-0000-0000-0000-000000000000"
  }
  ```
</ResponseExample>

<Accordion title="Properties">
  <ResponseField name="connected_account_custom_metadata" type="Object">
    Custom metadata of the connected account, present when connected\_account\_id is provided.
  </ResponseField>

  <ResponseField name="connected_account_id" type="String (UUID)">
    ID of the connected account associated with the event.
  </ResponseField>

  <ResponseField name="created_at" type="String (ISO 8601)">
    Date and time at which the event was created.
  </ResponseField>

  <ResponseField name="customer_key" type="String">
    The customer key associated with the device, if any.
  </ResponseField>

  <ResponseField name="device_custom_metadata" type="Object">
    Custom metadata of the device, present when device\_id is provided.
  </ResponseField>

  <ResponseField name="device_id" type="String (UUID)">
    ID of the affected device.
  </ResponseField>

  <ResponseField name="event_description" type="String">
    Human-readable description of the event. Persisted when the event is created (so the creating code, including a provider, can supply a tailored description) and otherwise derived from the event.
  </ResponseField>

  <ResponseField name="event_id" type="String (UUID)">
    ID of the event.
  </ResponseField>

  <ResponseField name="event_type" type="Enum (String)">
    Value: `device.salto.privacy_mode_activated`
  </ResponseField>

  <ResponseField name="occurred_at" type="String (ISO 8601)">
    Date and time at which the event occurred.
  </ResponseField>

  <ResponseField name="workspace_id" type="String (UUID)">
    ID of the workspace associated with the event.
  </ResponseField>
</Accordion>

## `device.salto.privacy_mode_deactivated`

A [Salto device](/device-and-system-integration-guides/salto-locks) deactivated privacy mode.

<ResponseExample>
  ```json Example webhook payload theme={null}
  {
    "connected_account_custom_metadata": {},
    "connected_account_id": "00000000-0000-0000-0000-000000000000",
    "created_at": "2025-01-01T00:00:00.000Z",
    "customer_key": "",
    "device_custom_metadata": {},
    "device_id": "00000000-0000-0000-0000-000000000000",
    "event_description": "A [Salto device](/device-and-system-integration-guides/salto-locks) deactivated privacy mode.",
    "event_id": "00000000-0000-0000-0000-000000000000",
    "event_type": "device.salto.privacy_mode_deactivated",
    "occurred_at": "2025-01-01T00:00:00.000Z",
    "workspace_id": "00000000-0000-0000-0000-000000000000"
  }
  ```
</ResponseExample>

<Accordion title="Properties">
  <ResponseField name="connected_account_custom_metadata" type="Object">
    Custom metadata of the connected account, present when connected\_account\_id is provided.
  </ResponseField>

  <ResponseField name="connected_account_id" type="String (UUID)">
    ID of the connected account associated with the event.
  </ResponseField>

  <ResponseField name="created_at" type="String (ISO 8601)">
    Date and time at which the event was created.
  </ResponseField>

  <ResponseField name="customer_key" type="String">
    The customer key associated with the device, if any.
  </ResponseField>

  <ResponseField name="device_custom_metadata" type="Object">
    Custom metadata of the device, present when device\_id is provided.
  </ResponseField>

  <ResponseField name="device_id" type="String (UUID)">
    ID of the affected device.
  </ResponseField>

  <ResponseField name="event_description" type="String">
    Human-readable description of the event. Persisted when the event is created (so the creating code, including a provider, can supply a tailored description) and otherwise derived from the event.
  </ResponseField>

  <ResponseField name="event_id" type="String (UUID)">
    ID of the event.
  </ResponseField>

  <ResponseField name="event_type" type="Enum (String)">
    Value: `device.salto.privacy_mode_deactivated`
  </ResponseField>

  <ResponseField name="occurred_at" type="String (ISO 8601)">
    Date and time at which the event occurred.
  </ResponseField>

  <ResponseField name="workspace_id" type="String (UUID)">
    ID of the workspace associated with the event.
  </ResponseField>
</Accordion>

## `device.connection_became_flaky`

Seam detected a flaky device connection.

<ResponseExample>
  ```json Example webhook payload theme={null}
  {
    "connected_account_custom_metadata": {},
    "connected_account_errors": [],
    "connected_account_id": "00000000-0000-0000-0000-000000000000",
    "connected_account_warnings": [],
    "created_at": "2025-01-01T00:00:00.000Z",
    "customer_key": "",
    "device_custom_metadata": {},
    "device_errors": [],
    "device_id": "00000000-0000-0000-0000-000000000000",
    "device_warnings": [],
    "event_description": "Seam detected a flaky device connection.",
    "event_id": "00000000-0000-0000-0000-000000000000",
    "event_type": "device.connection_became_flaky",
    "occurred_at": "2025-01-01T00:00:00.000Z",
    "workspace_id": "00000000-0000-0000-0000-000000000000"
  }
  ```
</ResponseExample>

<Accordion title="Properties">
  <ResponseField name="connected_account_custom_metadata" type="Object">
    Custom metadata of the connected account, present when connected\_account\_id is provided.
  </ResponseField>

  <ResponseField name="connected_account_errors" type="Array">
    Errors associated with the connected account.
  </ResponseField>

  <ResponseField name="connected_account_id" type="String (UUID)">
    ID of the connected account associated with the event.
  </ResponseField>

  <ResponseField name="connected_account_warnings" type="Array">
    Warnings associated with the connected account.
  </ResponseField>

  <ResponseField name="created_at" type="String (ISO 8601)">
    Date and time at which the event was created.
  </ResponseField>

  <ResponseField name="customer_key" type="String">
    The customer key associated with the device, if any.
  </ResponseField>

  <ResponseField name="device_custom_metadata" type="Object">
    Custom metadata of the device, present when device\_id is provided.
  </ResponseField>

  <ResponseField name="device_errors" type="Array">
    Errors associated with the device.
  </ResponseField>

  <ResponseField name="device_id" type="String (UUID)">
    ID of the affected device.
  </ResponseField>

  <ResponseField name="device_warnings" type="Array">
    Warnings associated with the device.
  </ResponseField>

  <ResponseField name="event_description" type="String">
    Human-readable description of the event. Persisted when the event is created (so the creating code, including a provider, can supply a tailored description) and otherwise derived from the event.
  </ResponseField>

  <ResponseField name="event_id" type="String (UUID)">
    ID of the event.
  </ResponseField>

  <ResponseField name="event_type" type="Enum (String)">
    Value: `device.connection_became_flaky`
  </ResponseField>

  <ResponseField name="occurred_at" type="String (ISO 8601)">
    Date and time at which the event occurred.
  </ResponseField>

  <ResponseField name="workspace_id" type="String (UUID)">
    ID of the workspace associated with the event.
  </ResponseField>
</Accordion>

## `device.connection_stabilized`

Seam detected that a previously-flaky device connection stabilized.

<ResponseExample>
  ```json Example webhook payload theme={null}
  {
    "connected_account_custom_metadata": {},
    "connected_account_id": "00000000-0000-0000-0000-000000000000",
    "created_at": "2025-01-01T00:00:00.000Z",
    "customer_key": "",
    "device_custom_metadata": {},
    "device_id": "00000000-0000-0000-0000-000000000000",
    "event_description": "Seam detected that a previously-flaky device connection stabilized.",
    "event_id": "00000000-0000-0000-0000-000000000000",
    "event_type": "device.connection_stabilized",
    "occurred_at": "2025-01-01T00:00:00.000Z",
    "workspace_id": "00000000-0000-0000-0000-000000000000"
  }
  ```
</ResponseExample>

<Accordion title="Properties">
  <ResponseField name="connected_account_custom_metadata" type="Object">
    Custom metadata of the connected account, present when connected\_account\_id is provided.
  </ResponseField>

  <ResponseField name="connected_account_id" type="String (UUID)">
    ID of the connected account associated with the event.
  </ResponseField>

  <ResponseField name="created_at" type="String (ISO 8601)">
    Date and time at which the event was created.
  </ResponseField>

  <ResponseField name="customer_key" type="String">
    The customer key associated with the device, if any.
  </ResponseField>

  <ResponseField name="device_custom_metadata" type="Object">
    Custom metadata of the device, present when device\_id is provided.
  </ResponseField>

  <ResponseField name="device_id" type="String (UUID)">
    ID of the affected device.
  </ResponseField>

  <ResponseField name="event_description" type="String">
    Human-readable description of the event. Persisted when the event is created (so the creating code, including a provider, can supply a tailored description) and otherwise derived from the event.
  </ResponseField>

  <ResponseField name="event_id" type="String (UUID)">
    ID of the event.
  </ResponseField>

  <ResponseField name="event_type" type="Enum (String)">
    Value: `device.connection_stabilized`
  </ResponseField>

  <ResponseField name="occurred_at" type="String (ISO 8601)">
    Date and time at which the event occurred.
  </ResponseField>

  <ResponseField name="workspace_id" type="String (UUID)">
    ID of the workspace associated with the event.
  </ResponseField>
</Accordion>

## `device.error.subscription_required`

A third-party subscription is required to use all device features.

<ResponseExample>
  ```json Example webhook payload theme={null}
  {
    "connected_account_custom_metadata": {},
    "connected_account_errors": [],
    "connected_account_id": "00000000-0000-0000-0000-000000000000",
    "connected_account_warnings": [],
    "created_at": "2025-01-01T00:00:00.000Z",
    "customer_key": "",
    "device_custom_metadata": {},
    "device_errors": [],
    "device_id": "00000000-0000-0000-0000-000000000000",
    "device_warnings": [],
    "event_description": "A third-party subscription is required to use all device features.",
    "event_id": "00000000-0000-0000-0000-000000000000",
    "event_type": "device.error.subscription_required",
    "occurred_at": "2025-01-01T00:00:00.000Z",
    "workspace_id": "00000000-0000-0000-0000-000000000000"
  }
  ```
</ResponseExample>

<Accordion title="Properties">
  <ResponseField name="connected_account_custom_metadata" type="Object">
    Custom metadata of the connected account, present when connected\_account\_id is provided.
  </ResponseField>

  <ResponseField name="connected_account_errors" type="Array">
    Errors associated with the connected account.
  </ResponseField>

  <ResponseField name="connected_account_id" type="String (UUID)">
    ID of the connected account associated with the event.
  </ResponseField>

  <ResponseField name="connected_account_warnings" type="Array">
    Warnings associated with the connected account.
  </ResponseField>

  <ResponseField name="created_at" type="String (ISO 8601)">
    Date and time at which the event was created.
  </ResponseField>

  <ResponseField name="customer_key" type="String">
    The customer key associated with the device, if any.
  </ResponseField>

  <ResponseField name="device_custom_metadata" type="Object">
    Custom metadata of the device, present when device\_id is provided.
  </ResponseField>

  <ResponseField name="device_errors" type="Array">
    Errors associated with the device.
  </ResponseField>

  <ResponseField name="device_id" type="String (UUID)">
    ID of the affected device.
  </ResponseField>

  <ResponseField name="device_warnings" type="Array">
    Warnings associated with the device.
  </ResponseField>

  <ResponseField name="event_description" type="String">
    Human-readable description of the event. Persisted when the event is created (so the creating code, including a provider, can supply a tailored description) and otherwise derived from the event.
  </ResponseField>

  <ResponseField name="event_id" type="String (UUID)">
    ID of the event.
  </ResponseField>

  <ResponseField name="event_type" type="Enum (String)">
    Value: `device.error.subscription_required`
  </ResponseField>

  <ResponseField name="occurred_at" type="String (ISO 8601)">
    Date and time at which the event occurred.
  </ResponseField>

  <ResponseField name="workspace_id" type="String (UUID)">
    ID of the workspace associated with the event.
  </ResponseField>
</Accordion>

## `device.error.subscription_required.resolved`

A third-party subscription is active or no longer required to use all device features.

<ResponseExample>
  ```json Example webhook payload theme={null}
  {
    "connected_account_custom_metadata": {},
    "connected_account_id": "00000000-0000-0000-0000-000000000000",
    "created_at": "2025-01-01T00:00:00.000Z",
    "customer_key": "",
    "device_custom_metadata": {},
    "device_id": "00000000-0000-0000-0000-000000000000",
    "event_description": "A third-party subscription is active or no longer required to use all device features.",
    "event_id": "00000000-0000-0000-0000-000000000000",
    "event_type": "device.error.subscription_required.resolved",
    "occurred_at": "2025-01-01T00:00:00.000Z",
    "workspace_id": "00000000-0000-0000-0000-000000000000"
  }
  ```
</ResponseExample>

<Accordion title="Properties">
  <ResponseField name="connected_account_custom_metadata" type="Object">
    Custom metadata of the connected account, present when connected\_account\_id is provided.
  </ResponseField>

  <ResponseField name="connected_account_id" type="String (UUID)">
    ID of the connected account associated with the event.
  </ResponseField>

  <ResponseField name="created_at" type="String (ISO 8601)">
    Date and time at which the event was created.
  </ResponseField>

  <ResponseField name="customer_key" type="String">
    The customer key associated with the device, if any.
  </ResponseField>

  <ResponseField name="device_custom_metadata" type="Object">
    Custom metadata of the device, present when device\_id is provided.
  </ResponseField>

  <ResponseField name="device_id" type="String (UUID)">
    ID of the affected device.
  </ResponseField>

  <ResponseField name="event_description" type="String">
    Human-readable description of the event. Persisted when the event is created (so the creating code, including a provider, can supply a tailored description) and otherwise derived from the event.
  </ResponseField>

  <ResponseField name="event_id" type="String (UUID)">
    ID of the event.
  </ResponseField>

  <ResponseField name="event_type" type="Enum (String)">
    Value: `device.error.subscription_required.resolved`
  </ResponseField>

  <ResponseField name="occurred_at" type="String (ISO 8601)">
    Date and time at which the event occurred.
  </ResponseField>

  <ResponseField name="workspace_id" type="String (UUID)">
    ID of the workspace associated with the event.
  </ResponseField>
</Accordion>

## `device.accessory_keypad_connected`

An accessory keypad was connected to a device.

<ResponseExample>
  ```json Example webhook payload theme={null}
  {
    "connected_account_custom_metadata": {},
    "connected_account_id": "00000000-0000-0000-0000-000000000000",
    "created_at": "2025-01-01T00:00:00.000Z",
    "customer_key": "",
    "device_custom_metadata": {},
    "device_id": "00000000-0000-0000-0000-000000000000",
    "event_description": "An accessory keypad was connected to a device.",
    "event_id": "00000000-0000-0000-0000-000000000000",
    "event_type": "device.accessory_keypad_connected",
    "occurred_at": "2025-01-01T00:00:00.000Z",
    "workspace_id": "00000000-0000-0000-0000-000000000000"
  }
  ```
</ResponseExample>

<Accordion title="Properties">
  <ResponseField name="connected_account_custom_metadata" type="Object">
    Custom metadata of the connected account, present when connected\_account\_id is provided.
  </ResponseField>

  <ResponseField name="connected_account_id" type="String (UUID)">
    ID of the connected account associated with the event.
  </ResponseField>

  <ResponseField name="created_at" type="String (ISO 8601)">
    Date and time at which the event was created.
  </ResponseField>

  <ResponseField name="customer_key" type="String">
    The customer key associated with the device, if any.
  </ResponseField>

  <ResponseField name="device_custom_metadata" type="Object">
    Custom metadata of the device, present when device\_id is provided.
  </ResponseField>

  <ResponseField name="device_id" type="String (UUID)">
    ID of the affected device.
  </ResponseField>

  <ResponseField name="event_description" type="String">
    Human-readable description of the event. Persisted when the event is created (so the creating code, including a provider, can supply a tailored description) and otherwise derived from the event.
  </ResponseField>

  <ResponseField name="event_id" type="String (UUID)">
    ID of the event.
  </ResponseField>

  <ResponseField name="event_type" type="Enum (String)">
    Value: `device.accessory_keypad_connected`
  </ResponseField>

  <ResponseField name="occurred_at" type="String (ISO 8601)">
    Date and time at which the event occurred.
  </ResponseField>

  <ResponseField name="workspace_id" type="String (UUID)">
    ID of the workspace associated with the event.
  </ResponseField>
</Accordion>

## `device.accessory_keypad_disconnected`

An accessory keypad was disconnected from a device.

<ResponseExample>
  ```json Example webhook payload theme={null}
  {
    "connected_account_custom_metadata": {},
    "connected_account_errors": [],
    "connected_account_id": "00000000-0000-0000-0000-000000000000",
    "connected_account_warnings": [],
    "created_at": "2025-01-01T00:00:00.000Z",
    "customer_key": "",
    "device_custom_metadata": {},
    "device_errors": [],
    "device_id": "00000000-0000-0000-0000-000000000000",
    "device_warnings": [],
    "event_description": "An accessory keypad was disconnected from a device.",
    "event_id": "00000000-0000-0000-0000-000000000000",
    "event_type": "device.accessory_keypad_disconnected",
    "occurred_at": "2025-01-01T00:00:00.000Z",
    "workspace_id": "00000000-0000-0000-0000-000000000000"
  }
  ```
</ResponseExample>

<Accordion title="Properties">
  <ResponseField name="connected_account_custom_metadata" type="Object">
    Custom metadata of the connected account, present when connected\_account\_id is provided.
  </ResponseField>

  <ResponseField name="connected_account_errors" type="Array">
    Errors associated with the connected account.
  </ResponseField>

  <ResponseField name="connected_account_id" type="String (UUID)">
    ID of the connected account associated with the event.
  </ResponseField>

  <ResponseField name="connected_account_warnings" type="Array">
    Warnings associated with the connected account.
  </ResponseField>

  <ResponseField name="created_at" type="String (ISO 8601)">
    Date and time at which the event was created.
  </ResponseField>

  <ResponseField name="customer_key" type="String">
    The customer key associated with the device, if any.
  </ResponseField>

  <ResponseField name="device_custom_metadata" type="Object">
    Custom metadata of the device, present when device\_id is provided.
  </ResponseField>

  <ResponseField name="device_errors" type="Array">
    Errors associated with the device.
  </ResponseField>

  <ResponseField name="device_id" type="String (UUID)">
    ID of the affected device.
  </ResponseField>

  <ResponseField name="device_warnings" type="Array">
    Warnings associated with the device.
  </ResponseField>

  <ResponseField name="event_description" type="String">
    Human-readable description of the event. Persisted when the event is created (so the creating code, including a provider, can supply a tailored description) and otherwise derived from the event.
  </ResponseField>

  <ResponseField name="event_id" type="String (UUID)">
    ID of the event.
  </ResponseField>

  <ResponseField name="event_type" type="Enum (String)">
    Value: `device.accessory_keypad_disconnected`
  </ResponseField>

  <ResponseField name="occurred_at" type="String (ISO 8601)">
    Date and time at which the event occurred.
  </ResponseField>

  <ResponseField name="workspace_id" type="String (UUID)">
    ID of the workspace associated with the event.
  </ResponseField>
</Accordion>

## `device.name_changed`

The name of a device was changed.

<ResponseExample>
  ```json Example webhook payload theme={null}
  {
    "connected_account_custom_metadata": {},
    "connected_account_id": "00000000-0000-0000-0000-000000000000",
    "created_at": "2025-01-01T00:00:00.000Z",
    "customer_key": "",
    "device_custom_metadata": {},
    "device_id": "00000000-0000-0000-0000-000000000000",
    "device_name": "",
    "event_description": "The name of a device was changed.",
    "event_id": "00000000-0000-0000-0000-000000000000",
    "event_type": "device.name_changed",
    "occurred_at": "2025-01-01T00:00:00.000Z",
    "workspace_id": "00000000-0000-0000-0000-000000000000"
  }
  ```
</ResponseExample>

<Accordion title="Properties">
  <ResponseField name="connected_account_custom_metadata" type="Object">
    Custom metadata of the connected account, present when connected\_account\_id is provided.
  </ResponseField>

  <ResponseField name="connected_account_id" type="String (UUID)">
    ID of the connected account associated with the event.
  </ResponseField>

  <ResponseField name="created_at" type="String (ISO 8601)">
    Date and time at which the event was created.
  </ResponseField>

  <ResponseField name="customer_key" type="String">
    The customer key associated with the device, if any.
  </ResponseField>

  <ResponseField name="device_custom_metadata" type="Object">
    Custom metadata of the device, present when device\_id is provided.
  </ResponseField>

  <ResponseField name="device_id" type="String (UUID)">
    ID of the affected device.
  </ResponseField>

  <ResponseField name="device_name" type="String">
    The new name of the affected device.
  </ResponseField>

  <ResponseField name="event_description" type="String">
    Human-readable description of the event. Persisted when the event is created (so the creating code, including a provider, can supply a tailored description) and otherwise derived from the event.
  </ResponseField>

  <ResponseField name="event_id" type="String (UUID)">
    ID of the event.
  </ResponseField>

  <ResponseField name="event_type" type="Enum (String)">
    Value: `device.name_changed`
  </ResponseField>

  <ResponseField name="occurred_at" type="String (ISO 8601)">
    Date and time at which the event occurred.
  </ResponseField>

  <ResponseField name="workspace_id" type="String (UUID)">
    ID of the workspace associated with the event.
  </ResponseField>
</Accordion>

## `camera.activated`

A camera was activated, for example, by motion detection.

<ResponseExample>
  ```json Example webhook payload theme={null}
  {
    "activation_reason": "motion_detected",
    "connected_account_custom_metadata": {},
    "connected_account_id": "00000000-0000-0000-0000-000000000000",
    "created_at": "2025-01-01T00:00:00.000Z",
    "customer_key": "",
    "device_custom_metadata": {},
    "device_id": "00000000-0000-0000-0000-000000000000",
    "event_description": "A camera was activated, for example, by motion detection.",
    "event_id": "00000000-0000-0000-0000-000000000000",
    "event_type": "camera.activated",
    "image_url": "",
    "motion_sub_type": "human",
    "occurred_at": "2025-01-01T00:00:00.000Z",
    "video_url": "",
    "workspace_id": "00000000-0000-0000-0000-000000000000"
  }
  ```
</ResponseExample>

<Accordion title="Properties">
  <ResponseField name="activation_reason" type="Enum (String)">
    The reason the camera was activated.

    Possible values: `motion_detected`
  </ResponseField>

  <ResponseField name="connected_account_custom_metadata" type="Object">
    Custom metadata of the connected account, present when connected\_account\_id is provided.
  </ResponseField>

  <ResponseField name="connected_account_id" type="String (UUID)">
    ID of the connected account associated with the event.
  </ResponseField>

  <ResponseField name="created_at" type="String (ISO 8601)">
    Date and time at which the event was created.
  </ResponseField>

  <ResponseField name="customer_key" type="String">
    The customer key associated with the device, if any.
  </ResponseField>

  <ResponseField name="device_custom_metadata" type="Object">
    Custom metadata of the device, present when device\_id is provided.
  </ResponseField>

  <ResponseField name="device_id" type="String (UUID)">
    ID of the affected device.
  </ResponseField>

  <ResponseField name="event_description" type="String">
    Human-readable description of the event. Persisted when the event is created (so the creating code, including a provider, can supply a tailored description) and otherwise derived from the event.
  </ResponseField>

  <ResponseField name="event_id" type="String (UUID)">
    ID of the event.
  </ResponseField>

  <ResponseField name="event_type" type="Enum (String)">
    Value: `camera.activated`
  </ResponseField>

  <ResponseField name="image_url" type="String">
    URL to a thumbnail image captured at the time of activation.
  </ResponseField>

  <ResponseField name="motion_sub_type" type="Enum (String)">
    Sub-type of motion detected, if available.

    Possible values: `human`, `vehicle`, `package`, `other`
  </ResponseField>

  <ResponseField name="occurred_at" type="String (ISO 8601)">
    Date and time at which the event occurred.
  </ResponseField>

  <ResponseField name="video_url" type="String">
    URL to a short video clip captured at the time of activation.
  </ResponseField>

  <ResponseField name="workspace_id" type="String (UUID)">
    ID of the workspace associated with the event.
  </ResponseField>
</Accordion>

## `device.doorbell_rang`

A doorbell button was pressed on a device.

<ResponseExample>
  ```json Example webhook payload theme={null}
  {
    "connected_account_custom_metadata": {},
    "connected_account_id": "00000000-0000-0000-0000-000000000000",
    "created_at": "2025-01-01T00:00:00.000Z",
    "customer_key": "",
    "device_custom_metadata": {},
    "device_id": "00000000-0000-0000-0000-000000000000",
    "event_description": "A doorbell button was pressed on a device.",
    "event_id": "00000000-0000-0000-0000-000000000000",
    "event_type": "device.doorbell_rang",
    "image_url": "",
    "occurred_at": "2025-01-01T00:00:00.000Z",
    "video_url": "",
    "workspace_id": "00000000-0000-0000-0000-000000000000"
  }
  ```
</ResponseExample>

<Accordion title="Properties">
  <ResponseField name="connected_account_custom_metadata" type="Object">
    Custom metadata of the connected account, present when connected\_account\_id is provided.
  </ResponseField>

  <ResponseField name="connected_account_id" type="String (UUID)">
    ID of the connected account associated with the event.
  </ResponseField>

  <ResponseField name="created_at" type="String (ISO 8601)">
    Date and time at which the event was created.
  </ResponseField>

  <ResponseField name="customer_key" type="String">
    The customer key associated with the device, if any.
  </ResponseField>

  <ResponseField name="device_custom_metadata" type="Object">
    Custom metadata of the device, present when device\_id is provided.
  </ResponseField>

  <ResponseField name="device_id" type="String (UUID)">
    ID of the affected device.
  </ResponseField>

  <ResponseField name="event_description" type="String">
    Human-readable description of the event. Persisted when the event is created (so the creating code, including a provider, can supply a tailored description) and otherwise derived from the event.
  </ResponseField>

  <ResponseField name="event_id" type="String (UUID)">
    ID of the event.
  </ResponseField>

  <ResponseField name="event_type" type="Enum (String)">
    Value: `device.doorbell_rang`
  </ResponseField>

  <ResponseField name="image_url" type="String">
    URL to a thumbnail image captured at the time the doorbell was pressed.
  </ResponseField>

  <ResponseField name="occurred_at" type="String (ISO 8601)">
    Date and time at which the event occurred.
  </ResponseField>

  <ResponseField name="video_url" type="String">
    URL to a short video clip captured at the time the doorbell was pressed.
  </ResponseField>

  <ResponseField name="workspace_id" type="String (UUID)">
    ID of the workspace associated with the event.
  </ResponseField>
</Accordion>


# Get a Device
Source: https://docs.seam.co/api/devices/get

/openapi.json post /devices/get
Returns a specified [device](/core-concepts/devices).

You must specify either `device_id` or `name`.

You must include at least one request parameter.



# List Devices
Source: https://docs.seam.co/api/devices/list

/openapi.json post /devices/list
Returns a list of all [devices](/core-concepts/devices).



# List Device Providers
Source: https://docs.seam.co/api/devices/list_device_providers

/openapi.json post /devices/list_device_providers
Returns a list of all device providers.

The information that this endpoint returns for each provider includes a set of [capability flags](/capability-guides/device-and-system-capabilities#capability-flags), such as `device_provider.can_remotely_unlock`. If at least one supported device from a provider has a specific capability, the corresponding capability flag is `true`.

When you create a [Connect Webview](/core-concepts/connect-webviews), you can customize the providers—that is, the brands—that it displays. In the `/connect_webviews/create` request, include the desired set of device provider keys in the `accepted_providers` parameter. See also [Customize the Brands to Display in Your Connect Webviews](/core-concepts/connect-webviews/customizing-connect-webviews#customize-the-brands-to-display-in-your-connect-webviews).



# The Device Object
Source: https://docs.seam.co/api/devices/object

Learn how the device object represents a smart lock, thermostat, sensor, or other device connected to Seam, including its properties and events.

## The device Object

Represents a [device](/core-concepts/devices) that has been connected to Seam.

<ResponseExample>
  ```json Lock Device theme={null}
  {
    "can_program_online_access_codes": true,
    "can_remotely_lock": true,
    "can_remotely_unlock": true,
    "capabilities_supported": [
      "access_code",
      "lock"
    ],
    "connected_account_id": "8e3a4f1b-2c7d-4a9e-8b5f-3d2c1a0b9e8f",
    "created_at": "2025-03-27T02:08:16.418Z",
    "space_ids": [],
    "custom_metadata": {
      "id": "internalId1"
    },
    "device_id": "a69569e1-133b-4a9d-b883-018641bfe543",
    "device_type": "schlage_lock",
    "display_name": "FRONT DOOR",
    "errors": [],
    "is_managed": true,
    "location": {
      "location_name": "Front Door",
      "timezone": "America/New_York"
    },
    "nickname": "Front Door",
    "properties": {
      "appearance": {
        "name": "FRONT DOOR"
      },
      "battery": {
        "level": 0.48,
        "status": "good"
      },
      "battery_level": 0.48,
      "code_constraints": [
        {
          "constraint_type": "name_length",
          "max_length": 9
        }
      ],
      "has_native_entry_events": true,
      "image_alt_text": "Schlage Sense Smart Deadbolt with Camelot Trim, Front",
      "image_url": "https://connect.getseam.com/_next/image?url=https://connect.getseam.com/assets/images/devices/schlage_sense-smart-deadbolt-with-camelot-trim_front.png&q=75&w=128",
      "locked": false,
      "manufacturer": "schlage",
      "model": {
        "accessory_keypad_supported": false,
        "can_connect_accessory_keypad": false,
        "display_name": "Encode",
        "has_built_in_keypad": true,
        "manufacturer_display_name": "Schlage",
        "offline_access_codes_supported": false,
        "online_access_codes_supported": true
      },
      "name": "FRONT DOOR",
      "offline_access_codes_enabled": false,
      "online": true,
      "online_access_codes_enabled": true,
      "schlage_metadata": {
        "device_id": "a69569e1-133b-4a9d-b883-018641bfe543",
        "device_name": "FRONT DOOR",
        "model": "Encode"
      },
      "serial_number": "34000000000531e0",
      "supported_code_lengths": [
        4,
        5,
        6,
        7,
        8
      ],
      "supports_backup_access_code_pool": true,
      "supports_offline_access_codes": false
    },
    "warnings": [],
    "workspace_id": "5d7f2e1a-9c8b-4f3e-8d2c-1a0b9e8f7c6d"
  }
  ```

  ```json Noise Sensor Device theme={null}
  {
    "capabilities_supported": [
      "noise_detection"
    ],
    "connected_account_id": "9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d",
    "created_at": "2025-05-16T16:54:17.946049Z",
    "custom_metadata": {
      "id": "internalId1"
    },
    "device_id": "f1e2d3c4-b5a6-4d7c-8e9f-0a1b2c3d4e5f",
    "device_type": "minut_sensor",
    "display_name": "Living Room",
    "errors": [],
    "is_managed": true,
    "space_ids": [],
    "location": {
      "location_name": "Jane's Test Home",
      "timezone": "America/Los_Angeles"
    },
    "nickname": "Living Room",
    "properties": {
      "appearance": {
        "name": "Living Room"
      },
      "battery": {
        "level": 1,
        "status": "full"
      },
      "battery_level": 1,
      "currently_triggering_noise_threshold_ids": [],
      "image_alt_text": "Minut Sensor",
      "image_url": "https://connect.getseam.com/_next/image?url=https://connect.getseam.com/assets/images/devices/minut_gen-3_front.png&q=75&w=128",
      "manufacturer": "minut",
      "minut_metadata": {
        "device_id": "770cd3153deca3dee0fe0614",
        "device_location": {
          "latitude": 0,
          "longitude": 0
        },
        "device_name": "Living Room",
        "home_address": {
          "city": "San Francisco",
          "country": "US",
          "notes": "string",
          "post_code": "44210",
          "region": "San Francisco County",
          "street_name1": "2258 24th Street",
          "street_name2": ""
        },
        "home_id": "2978b6d5dba395ec08300e46",
        "home_location": {
          "latitude": 0,
          "longitude": 0
        },
        "home_name": "Jane's Test Home",
        "latest_sensor_values": {
          "accelerometer_z": {
            "time": "2025-06-16T16:54:17.946049Z",
            "value": -1.00390625
          },
          "humidity": {
            "time": "2025-06-16T16:54:17.946049Z",
            "value": 31.110000610351562
          },
          "pressure": {
            "time": "2025-06-16T16:54:17.946049Z",
            "value": 101923
          },
          "sound": {
            "time": "2025-06-16T16:54:17.946049Z",
            "value": 47.7117919921875
          },
          "temperature": {
            "time": "2025-06-16T16:54:17.946049Z",
            "value": 21.270000457763672
          }
        }
      },
      "model": {
        "display_name": "Noise Sensor",
        "manufacturer_display_name": "Minut"
      },
      "name": "Living Room",
      "noise_level_decibels": 47.7117919921875,
      "online": true
    },
    "warnings": [],
    "workspace_id": "1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d"
  }
  ```

  ```json Thermostat Device theme={null}
  {
    "can_hvac_cool": true,
    "can_hvac_heat": true,
    "can_hvac_heat_cool": true,
    "can_turn_off_hvac": true,
    "capabilities_supported": [
      "thermostat"
    ],
    "connected_account_id": "a0b1c2d3-e4f5-6a7b-8c9d-0e1f2a3b4c5d",
    "created_at": "2024-10-03T22:12:15.666Z",
    "custom_metadata": {
      "id": "internalId1"
    },
    "device_id": "a1b2c3d4-e5f6-7890-1234-56789abcdef0",
    "device_type": "ecobee_thermostat",
    "display_name": "Living Room",
    "errors": [],
    "is_managed": true,
    "space_ids": [],
    "location": {
      "location_name": "2948 20th St, San Francisco, CA, 94110, US",
      "timezone": "America/Los_Angeles"
    },
    "nickname": "Living Room",
    "properties": {
      "active_climate_preset": {
        "can_delete": true,
        "can_edit": true,
        "climate_preset_key": "sleep",
        "cooling_set_point_celsius": 23.88888888888889,
        "display_name": "Sleep",
        "fan_mode_setting": "auto",
        "heating_set_point_celsius": 17.77777777777778,
        "hvac_mode_setting": "heat_cool",
        "manual_override_allowed": true
      },
      "appearance": {
        "name": "Living Room"
      },
      "available_climate_presets": [
        {
          "climate_preset_key": "sleep",
          "can_edit": true,
          "can_delete": true,
          "can_use_with_thermostat_daily_programs": false,
          "name": "Sleep",
          "display_name": "Sleep",
          "fan_mode_setting": "auto",
          "hvac_mode_setting": "heat_cool",
          "manual_override_allowed": true,
          "cooling_set_point_celsius": 23.88888888888889,
          "heating_set_point_celsius": 17.77777777777778,
          "cooling_set_point_fahrenheit": 75,
          "heating_set_point_fahrenheit": 64
        },
        {
          "climate_preset_key": "home",
          "can_edit": true,
          "can_delete": true,
          "can_use_with_thermostat_daily_programs": false,
          "name": "Home",
          "display_name": "Home",
          "fan_mode_setting": "auto",
          "hvac_mode_setting": "heat_cool",
          "manual_override_allowed": false,
          "cooling_set_point_celsius": 23.88888888888889,
          "heating_set_point_celsius": 17.77777777777778,
          "cooling_set_point_fahrenheit": 75,
          "heating_set_point_fahrenheit": 64
        },
        {
          "climate_preset_key": "work",
          "can_edit": true,
          "can_delete": true,
          "can_use_with_thermostat_daily_programs": false,
          "name": "Work",
          "display_name": "Work",
          "fan_mode_setting": "auto",
          "hvac_mode_setting": "heat_cool",
          "manual_override_allowed": false,
          "cooling_set_point_celsius": 23.88888888888889,
          "heating_set_point_celsius": 17.77777777777778,
          "cooling_set_point_fahrenheit": 75,
          "heating_set_point_fahrenheit": 64
        }
      ],
      "available_fan_mode_settings": [
        "auto",
        "on"
      ],
      "available_hvac_mode_settings": [
        "cool",
        "heat",
        "heat_cool",
        "off"
      ],
      "current_climate_setting": {
        "display_name": "Manual Setting",
        "fan_mode_setting": "auto",
        "heating_set_point_celsius": 25,
        "heating_set_point_fahrenheit": 77,
        "hvac_mode_setting": "heat",
        "manual_override_allowed": true
      },
      "ecobee_metadata": {
        "device_name": "Living Room",
        "ecobee_device_id": "a1b2c3d4-e5f6-7890-1234-56789abcdef0"
      },
      "fallback_climate_preset_key": "eco",
      "fan_mode_setting": "auto",
      "has_direct_power": true,
      "image_alt_text": "Ecobee 3 Lite Thermostat",
      "image_url": "https://connect.getseam.com/_next/image?url=https://connect.getseam.com/assets/images/devices/ecobee_3-lite_front.png&q=75&w=128",
      "is_cooling": false,
      "is_fan_running": false,
      "is_heating": false,
      "is_temporary_manual_override_active": false,
      "manufacturer": "ecobee",
      "max_cooling_set_point_celsius": 33.333333333333336,
      "max_cooling_set_point_fahrenheit": 92,
      "max_heating_set_point_celsius": 26.11111111111111,
      "max_heating_set_point_fahrenheit": 79,
      "min_cooling_set_point_celsius": 18.333333333333336,
      "min_cooling_set_point_fahrenheit": 65,
      "min_heating_cooling_delta_celsius": 2.7777777777777777,
      "min_heating_cooling_delta_fahrenheit": 5,
      "min_heating_set_point_celsius": 7.222222222222222,
      "min_heating_set_point_fahrenheit": 45,
      "model": {
        "display_name": "Thermostat",
        "manufacturer_display_name": "Ecobee"
      },
      "name": "Living Room",
      "online": true,
      "relative_humidity": 0.36,
      "temperature_celsius": 21.11111111111111,
      "temperature_fahrenheit": 70,
      "temperature_threshold": {
        "lower_limit_celsius": 16.66666666666667,
        "lower_limit_fahrenheit": 62,
        "upper_limit_celsius": 26.66666666666667,
        "upper_limit_fahrenheit": 80
      },
      "thermostat_daily_programs": [
        {
          "thermostat_daily_program_id": "1a2b3c4d-5e6f-7890-1234-56789abcdef1",
          "device_id": "a1b2c3d4-e5f6-7890-1234-56789abcdef0",
          "name": "Weekday Program",
          "periods": [
            {
              "starts_at_time": "00:00:00",
              "climate_preset_key": "sleep"
            },
            {
              "starts_at_time": "07:00:00",
              "climate_preset_key": "home"
            },
            {
              "starts_at_time": "09:00:00",
              "climate_preset_key": "work"
            },
            {
              "starts_at_time": "18:00:00",
              "climate_preset_key": "home"
            },
            {
              "starts_at_time": "22:00:00",
              "climate_preset_key": "sleep"
            }
          ],
          "workspace_id": "9f8e7d6c-5b4a-3c2d-1e0f-9876543210ab",
          "created_at": "2025-05-30T04:01:25.455Z"
        },
        {
          "thermostat_daily_program_id": "d4e5f6a7-8b9c-0d1e-2f3a-4b5c6d7e8f90",
          "device_id": "a1b2c3d4-e5f6-7890-1234-56789abcdef0",
          "name": "Weekend Program",
          "periods": [
            {
              "starts_at_time": "00:00:00",
              "climate_preset_key": "sleep"
            },
            {
              "starts_at_time": "08:00:00",
              "climate_preset_key": "home"
            },
            {
              "starts_at_time": "23:00:00",
              "climate_preset_key": "sleep"
            }
          ],
          "workspace_id": "9f8e7d6c-5b4a-3c2d-1e0f-9876543210ab",
          "created_at": "2025-05-30T04:02:19.952Z"
        }
      ],
      "thermostat_weekly_program": null
    },
    "warnings": [],
    "workspace_id": "9f8e7d6c-5b4a-3c2d-1e0f-9876543210ab"
  }
  ```
</ResponseExample>

***

## Properties

<ResponseField name="can_configure_auto_lock" type="Boolean">
  Indicates whether the lock supports configuring automatic locking.
</ResponseField>

<ResponseField name="can_hvac_cool" type="Boolean">
  Indicates whether the thermostat supports cooling.
</ResponseField>

<ResponseField name="can_hvac_heat" type="Boolean">
  Indicates whether the thermostat supports heating.
</ResponseField>

<ResponseField name="can_hvac_heat_cool" type="Boolean">
  Indicates whether the thermostat supports simultaneous heating and cooling.
</ResponseField>

<ResponseField name="can_program_offline_access_codes" type="Boolean">
  Indicates whether the device supports programming offline access codes.
</ResponseField>

<ResponseField name="can_program_online_access_codes" type="Boolean">
  Indicates whether the device supports programming online access codes.
</ResponseField>

<ResponseField name="can_program_thermostat_programs_as_different_each_day" type="Boolean">
  Indicates whether the thermostat supports different climate programs for each day of the week.
</ResponseField>

<ResponseField name="can_program_thermostat_programs_as_same_each_day" type="Boolean">
  Indicates whether the thermostat supports a single climate program applied to every day.
</ResponseField>

<ResponseField name="can_program_thermostat_programs_as_weekday_weekend" type="Boolean">
  Indicates whether the thermostat supports weekday/weekend climate programs.
</ResponseField>

<ResponseField name="can_remotely_lock" type="Boolean">
  Indicates whether the device supports remote locking.
</ResponseField>

<ResponseField name="can_remotely_unlock" type="Boolean">
  Indicates whether the device supports remote unlocking.
</ResponseField>

<ResponseField name="can_run_thermostat_programs" type="Boolean">
  Indicates whether the thermostat supports running climate programs.
</ResponseField>

<ResponseField name="can_simulate_connection" type="Boolean">
  Indicates whether the device supports simulating connection in a sandbox.
</ResponseField>

<ResponseField name="can_simulate_disconnection" type="Boolean">
  Indicates whether the device supports simulating disconnection in a sandbox.
</ResponseField>

<ResponseField name="can_simulate_hub_connection" type="Boolean">
  Indicates whether the hub supports simulating connection in a sandbox.
</ResponseField>

<ResponseField name="can_simulate_hub_disconnection" type="Boolean">
  Indicates whether the hub supports simulating disconnection in a sandbox.
</ResponseField>

<ResponseField name="can_simulate_paid_subscription" type="Boolean">
  Indicates whether the device supports simulating a paid subscription in a sandbox.
</ResponseField>

<ResponseField name="can_simulate_removal" type="Boolean">
  Indicates whether the device supports simulating removal in a sandbox.
</ResponseField>

<ResponseField name="can_turn_off_hvac" type="Boolean">
  Indicates whether the thermostat can be turned off.
</ResponseField>

<ResponseField name="can_unlock_with_code" type="Boolean">
  Indicates whether the lock supports unlocking with an access code.
</ResponseField>

<ResponseField name="capabilities_supported" type="Array">
  Collection of capabilities that the device supports when connected to Seam. Values are `access_code`, which indicates that the device can manage and utilize digital PIN codes for secure access; `lock`, which indicates that the device controls a door locking mechanism, enabling the remote opening and closing of doors and other entry points; `noise_detection`, which indicates that the device supports monitoring and responding to ambient noise levels; `thermostat`, which indicates that the device can regulate and adjust indoor temperatures; `battery`, which indicates that the device can manage battery life and health; and `phone`, which indicates that the device is a mobile device, such as a smartphone. **Important:** Superseded by [capability flags](/capability-guides/device-and-system-capabilities#capability-flags).
</ResponseField>

<ResponseField name="connected_account_id" type="String (UUID)">
  Unique identifier for the account associated with the device.
</ResponseField>

<ResponseField name="created_at" type="String (ISO 8601)">
  Date and time at which the device object was created.
</ResponseField>

<ResponseField name="custom_metadata" type="Object">
  Set of key:value pairs. Adding custom metadata to a resource, such as a [Connect Webview](/core-concepts/connect-webviews/attaching-custom-data-to-the-connect-webview), [connected account](/core-concepts/connected-accounts/adding-custom-metadata-to-a-connected-account), or [device](/core-concepts/devices/adding-custom-metadata-to-a-device), enables you to store custom information, like customer details or internal IDs from your application.
</ResponseField>

<ResponseField name="device_id" type="String (UUID)">
  ID of the device.
</ResponseField>

<ResponseField name="device_type" type="Enum (String)">
  Type of the device.
</ResponseField>

<ResponseField name="display_name" type="String">
  Display name of the device, defaults to nickname (if it is set) or `properties.appearance.name`, otherwise. Enables administrators and users to identify the device easily, especially when there are numerous devices.
</ResponseField>

<ResponseField name="errors" type="Array">
  Array of errors associated with the device. Each error object within the array contains two fields: `error_code` and `message`. `error_code` is a string that uniquely identifies the type of error, enabling quick recognition and categorization of the issue. `message` provides a more detailed description of the error, offering insights into the issue and potentially how to rectify it.
</ResponseField>

<ResponseField name="is_managed" type="Boolean">
  Indicates whether Seam manages the device. See also [Managed and Unmanaged Devices](/core-concepts/devices/managed-and-unmanaged-devices).
</ResponseField>

<ResponseField name="nickname" type="String">
  Optional nickname to describe the device, settable through Seam.
</ResponseField>

<ResponseField name="properties" type="Object">
  Properties of the device.

  <Expandable title="properties">
    <ResponseField name="accessory_keypad" type="Object">
      Accessory keypad properties and state.

      <Expandable title="properties">
        <ResponseField name="battery" type="Object">
          Keypad battery properties.

          <Expandable title="properties">
            <ResponseField name="level" type="number">
              The level.
            </ResponseField>
          </Expandable>
        </ResponseField>

        <ResponseField name="is_connected" type="Boolean">
          Indicates if an accessory keypad is connected to the device.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="appearance" type="Object">
      Appearance-related properties, as reported by the device.

      <Expandable title="properties">
        <ResponseField name="name" type="String">
          Name of the device as seen from the provider API and application, not settable through Seam.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="battery" type="Object">
      Represents the current status of the battery charge level.

      <Expandable title="properties">
        <ResponseField name="level" type="number">
          Battery charge level as a value between 0 and 1, inclusive.
        </ResponseField>

        <ResponseField name="status" type="Enum (String)">
          Represents the current status of the battery charge level. Values are `critical`, which indicates an extremely low level, suggesting imminent shutdown or an urgent need for charging; `low`, which signifies that the battery is under the preferred threshold and should be charged soon; `good`, which denotes a satisfactory charge level, adequate for normal use without the immediate need for recharging; and `full`, which represents a battery that is fully charged, providing the maximum duration of usage.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="battery_level" type="number">
      Indicates the battery level of the device as a decimal value between 0 and 1, inclusive.
    </ResponseField>

    <ResponseField name="currently_triggering_noise_threshold_ids" type="Array">
      Array of noise threshold IDs that are currently triggering.
    </ResponseField>

    <ResponseField name="has_direct_power" type="Boolean">
      Indicates whether the device has direct power.
    </ResponseField>

    <ResponseField name="image_alt_text" type="String">
      Alt text for the device image.
    </ResponseField>

    <ResponseField name="image_url" type="String">
      Image URL for the device.
    </ResponseField>

    <ResponseField name="manufacturer" type="String">
      Manufacturer of the device. When a device, such as a smart lock, is connected through a smart hub, the manufacturer of the device might be different from that of the smart hub.
    </ResponseField>

    <ResponseField name="model" type="Object">
      Device model-related properties.

      <Expandable title="properties">
        <ResponseField name="accessory_keypad_supported" type="Boolean">
          **Deprecated**. use device.properties.model.can\_connect\_accessory\_keypad

          The accessory keypad supported.
        </ResponseField>

        <ResponseField name="can_connect_accessory_keypad" type="Boolean">
          Indicates whether the device can connect a accessory keypad.
        </ResponseField>

        <ResponseField name="display_name" type="String">
          Display name of the device model.
        </ResponseField>

        <ResponseField name="has_built_in_keypad" type="Boolean">
          Indicates whether the device has a built in accessory keypad.
        </ResponseField>

        <ResponseField name="manufacturer_display_name" type="String">
          Display name that corresponds to the manufacturer-specific terminology for the device.
        </ResponseField>

        <ResponseField name="offline_access_codes_supported" type="Boolean">
          **Deprecated**. use device.can\_program\_offline\_access\_codes.

          The offline access codes supported.
        </ResponseField>

        <ResponseField name="online_access_codes_supported" type="Boolean">
          **Deprecated**. use device.can\_program\_online\_access\_codes.

          The online access codes supported.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="name" type="String">
      **Deprecated**. use device.display\_name instead

      Name of the device.
    </ResponseField>

    <ResponseField name="noise_level_decibels" type="number">
      Indicates current noise level in decibels, if the device supports noise detection.
    </ResponseField>

    <ResponseField name="offline_access_codes_enabled" type="Boolean">
      **Deprecated**. use device.can\_program\_offline\_access\_codes

      Indicates whether it is currently possible to use offline access codes for the device.
    </ResponseField>

    <ResponseField name="online" type="Boolean">
      Indicates whether the device is online.
    </ResponseField>

    <ResponseField name="online_access_codes_enabled" type="Boolean">
      **Deprecated**. use device.can\_program\_online\_access\_codes

      Indicates whether it is currently possible to use online access codes for the device.
    </ResponseField>

    <ResponseField name="serial_number" type="String">
      Serial number of the device.
    </ResponseField>

    <ResponseField name="supports_accessory_keypad" type="Boolean">
      **Deprecated**. use device.properties.model.can\_connect\_accessory\_keypad

      The supports accessory keypad.
    </ResponseField>

    <ResponseField name="supports_offline_access_codes" type="Boolean">
      **Deprecated**. use offline\_access\_codes\_enabled

      The supports offline access codes.
    </ResponseField>

    <ResponseField name="assa_abloy_credential_service_metadata" type="Object">
      ASSA ABLOY Credential Service metadata for the phone.

      <Expandable title="properties">
        <ResponseField name="endpoints" type="Array">
          Endpoints associated with the phone.

          <Expandable title="properties">
            <ResponseField name="endpoint_id" type="String">
              ID of the associated endpoint.
            </ResponseField>

            <ResponseField name="is_active" type="Boolean">
              Indicated whether the endpoint is active.
            </ResponseField>
          </Expandable>
        </ResponseField>

        <ResponseField name="has_active_endpoint" type="Boolean">
          Indicates whether the credential service has active endpoints associated with the phone.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="salto_space_credential_service_metadata" type="Object">
      Salto Space credential service metadata for the phone.

      <Expandable title="properties">
        <ResponseField name="has_active_phone" type="Boolean">
          Indicates whether the credential service has an active associated phone.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="akiles_metadata" type="Object">
      Metadata for an Akiles device.

      <Expandable title="properties">
        <ResponseField name="_member_group_id" type="String">
          Group ID to which to add users for an Akiles device.
        </ResponseField>

        <ResponseField name="gadget_id" type="String">
          Gadget ID for an Akiles device.
        </ResponseField>

        <ResponseField name="gadget_name" type="String">
          Gadget name for an Akiles device.
        </ResponseField>

        <ResponseField name="product_name" type="String">
          Product name for an Akiles device.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="aqara_metadata" type="Object">
      Metadata for an Aqara device.

      <Expandable title="properties">
        <ResponseField name="device_name" type="String">
          Device name for an Aqara device.
        </ResponseField>

        <ResponseField name="did" type="String">
          Device ID (did) for an Aqara device.
        </ResponseField>

        <ResponseField name="firmware_version" type="String">
          Firmware version for an Aqara device.
        </ResponseField>

        <ResponseField name="model" type="String">
          Model identifier for an Aqara device.
        </ResponseField>

        <ResponseField name="model_type" type="number">
          Model type for an Aqara device.
        </ResponseField>

        <ResponseField name="parent_did" type="String">
          Parent gateway device ID for an Aqara device.
        </ResponseField>

        <ResponseField name="position_id" type="String">
          Position (room) ID for an Aqara device.
        </ResponseField>

        <ResponseField name="time_zone" type="String">
          Time zone reported for an Aqara device (e.g. GMT-07:00).
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="assa_abloy_vostio_metadata" type="Object">
      Metadata for an ASSA ABLOY Vostio system.

      <Expandable title="properties">
        <ResponseField name="encoder_name" type="String">
          Encoder name for an ASSA ABLOY Vostio system.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="august_metadata" type="Object">
      Metadata for an August device.

      <Expandable title="properties">
        <ResponseField name="has_keypad" type="Boolean">
          Indicates whether an August device has a keypad.
        </ResponseField>

        <ResponseField name="house_id" type="String">
          House ID for an August device.
        </ResponseField>

        <ResponseField name="house_name" type="String">
          House name for an August device.
        </ResponseField>

        <ResponseField name="keypad_battery_level" type="String">
          Keypad battery level for an August device.
        </ResponseField>

        <ResponseField name="lock_id" type="String">
          Lock ID for an August device.
        </ResponseField>

        <ResponseField name="lock_name" type="String">
          Lock name for an August device.
        </ResponseField>

        <ResponseField name="model" type="String">
          Model for an August device.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="avigilon_alta_metadata" type="Object">
      Metadata for an Avigilon Alta system.

      <Expandable title="properties">
        <ResponseField name="entry_name" type="String">
          Entry name for an Avigilon Alta system.
        </ResponseField>

        <ResponseField name="entry_relays_total_count" type="number">
          Total count of entry relays for an Avigilon Alta system.
        </ResponseField>

        <ResponseField name="org_name" type="String">
          Organization name for an Avigilon Alta system.
        </ResponseField>

        <ResponseField name="site_id" type="number">
          Site ID for an Avigilon Alta system.
        </ResponseField>

        <ResponseField name="site_name" type="String">
          Site name for an Avigilon Alta system.
        </ResponseField>

        <ResponseField name="zone_id" type="number">
          Zone ID for an Avigilon Alta system.
        </ResponseField>

        <ResponseField name="zone_name" type="String">
          Zone name for an Avigilon Alta system.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="brivo_metadata" type="Object">
      Metadata for a Brivo device.

      <Expandable title="properties">
        <ResponseField name="activation_enabled" type="Boolean">
          Indicates whether the Brivo access point has activation (remote unlock) enabled.
        </ResponseField>

        <ResponseField name="device_name" type="String">
          Device name for a Brivo device.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="controlbyweb_metadata" type="Object">
      Metadata for a ControlByWeb device.

      <Expandable title="properties">
        <ResponseField name="device_id" type="String">
          Device ID for a ControlByWeb device.
        </ResponseField>

        <ResponseField name="device_name" type="String">
          Device name for a ControlByWeb device.
        </ResponseField>

        <ResponseField name="relay_name" type="String">
          Relay name for a ControlByWeb device.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="dormakaba_oracode_metadata" type="Object">
      Metadata for a dormakaba Oracode device.

      <Expandable title="properties">
        <ResponseField name="device_id" type="String">
          Device ID for a dormakaba Oracode device.
        </ResponseField>

        <ResponseField name="door_id" type="number">
          Door ID for a dormakaba Oracode device.
        </ResponseField>

        <ResponseField name="door_is_wireless" type="Boolean">
          Indicates whether a door is wireless for a dormakaba Oracode device.
        </ResponseField>

        <ResponseField name="door_name" type="String">
          Door name for a dormakaba Oracode device.
        </ResponseField>

        <ResponseField name="iana_timezone" type="String">
          IANA time zone for a dormakaba Oracode device.
        </ResponseField>

        <ResponseField name="predefined_time_slots" type="Array">
          Predefined time slots for a dormakaba Oracode device.

          <Expandable title="properties">
            <ResponseField name="check_in_time" type="String">
              Check in time for a time slot for a dormakaba Oracode device.
            </ResponseField>

            <ResponseField name="check_out_time" type="String">
              Checkout time for a time slot for a dormakaba Oracode device.
            </ResponseField>

            <ResponseField name="dormakaba_oracode_user_level_id" type="String (UUID)">
              ID of a user level for a dormakaba Oracode device.
            </ResponseField>

            <ResponseField name="dormakaba_oracode_user_level_prefix" type="number">
              Prefix for a user level for a dormakaba Oracode device.
            </ResponseField>

            <ResponseField name="is_24_hour" type="Boolean">
              Indicates whether a time slot for a dormakaba Oracode device is a 24-hour time slot.
            </ResponseField>

            <ResponseField name="is_biweekly_mode" type="Boolean">
              Indicates whether a time slot for a dormakaba Oracode device is in biweekly mode.
            </ResponseField>

            <ResponseField name="is_master" type="Boolean">
              Indicates whether a time slot for a dormakaba Oracode device is a master time slot.
            </ResponseField>

            <ResponseField name="is_one_shot" type="Boolean">
              Indicates whether a time slot for a dormakaba Oracode device is a one-shot time slot.
            </ResponseField>

            <ResponseField name="name" type="String">
              Name of a time slot for a dormakaba Oracode device.
            </ResponseField>

            <ResponseField name="prefix" type="number">
              Prefix for a time slot for a dormakaba Oracode device.
            </ResponseField>
          </Expandable>
        </ResponseField>

        <ResponseField name="site_id" type="number">
          **Deprecated**. Previously marked as "@DEPRECATED."

          Site ID for a dormakaba Oracode device.
        </ResponseField>

        <ResponseField name="site_name" type="String">
          Site name for a dormakaba Oracode device.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="ecobee_metadata" type="Object">
      Metadata for an ecobee device.

      <Expandable title="properties">
        <ResponseField name="device_name" type="String">
          Device name for an ecobee device.
        </ResponseField>

        <ResponseField name="ecobee_device_id" type="String">
          Device ID for an ecobee device.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="four_suites_metadata" type="Object">
      Metadata for a 4SUITES device.

      <Expandable title="properties">
        <ResponseField name="device_id" type="number">
          Device ID for a 4SUITES device.
        </ResponseField>

        <ResponseField name="device_name" type="String">
          Device name for a 4SUITES device.
        </ResponseField>

        <ResponseField name="reclose_delay_in_seconds" type="number">
          Reclose delay, in seconds, for a 4SUITES device.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="genie_metadata" type="Object">
      Metadata for a Genie device.

      <Expandable title="properties">
        <ResponseField name="device_name" type="String">
          Lock name for a Genie device.
        </ResponseField>

        <ResponseField name="door_name" type="String">
          Door name for a Genie device.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="honeywell_resideo_metadata" type="Object">
      Metadata for a Honeywell Resideo device.

      <Expandable title="properties">
        <ResponseField name="device_name" type="String">
          Device name for a Honeywell Resideo device.
        </ResponseField>

        <ResponseField name="honeywell_resideo_device_id" type="String">
          Device ID for a Honeywell Resideo device.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="igloo_metadata" type="Object">
      Metadata for an igloo device.

      <Expandable title="properties">
        <ResponseField name="bridge_id" type="String">
          Bridge ID for an igloo device.
        </ResponseField>

        <ResponseField name="device_id" type="String">
          Device ID for an igloo device.
        </ResponseField>

        <ResponseField name="model" type="String">
          Model for an igloo device.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="igloohome_metadata" type="Object">
      Metadata for an igloohome device.

      <Expandable title="properties">
        <ResponseField name="bridge_id" type="String">
          Bridge ID for an igloohome device.
        </ResponseField>

        <ResponseField name="bridge_name" type="String">
          Bridge name for an igloohome device.
        </ResponseField>

        <ResponseField name="device_id" type="String">
          Device ID for an igloohome device.
        </ResponseField>

        <ResponseField name="device_name" type="String">
          Device name for an igloohome device.
        </ResponseField>

        <ResponseField name="is_accessory_keypad_linked_to_bridge" type="Boolean">
          Indicates whether a keypad is linked to a bridge for an igloohome device.
        </ResponseField>

        <ResponseField name="keypad_id" type="String">
          Keypad ID for an igloohome device.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="keynest_metadata" type="Object">
      Metadata for a KeyNest device.

      <Expandable title="properties">
        <ResponseField name="address" type="String">
          Address for a KeyNest device.
        </ResponseField>

        <ResponseField name="current_or_last_store_id" type="number">
          Current or last store ID for a KeyNest device.
        </ResponseField>

        <ResponseField name="current_status" type="String">
          Current status for a KeyNest device.
        </ResponseField>

        <ResponseField name="current_user_company" type="String">
          Current user company for a KeyNest device.
        </ResponseField>

        <ResponseField name="current_user_email" type="String">
          Current user email for a KeyNest device.
        </ResponseField>

        <ResponseField name="current_user_name" type="String">
          Current user name for a KeyNest device.
        </ResponseField>

        <ResponseField name="current_user_phone_number" type="String">
          Current user phone number for a KeyNest device.
        </ResponseField>

        <ResponseField name="default_office_id" type="number">
          Default office ID for a KeyNest device.
        </ResponseField>

        <ResponseField name="device_name" type="String">
          Device name for a KeyNest device.
        </ResponseField>

        <ResponseField name="fob_id" type="number">
          Fob ID for a KeyNest device.
        </ResponseField>

        <ResponseField name="handover_method" type="String">
          Handover method for a KeyNest device.
        </ResponseField>

        <ResponseField name="has_photo" type="Boolean">
          Whether the KeyNest device has a photo.
        </ResponseField>

        <ResponseField name="is_quadient_locker" type="Boolean">
          Whether the key is in a locker that does not support the access codes API.
        </ResponseField>

        <ResponseField name="key_id" type="String">
          Key ID for a KeyNest device.
        </ResponseField>

        <ResponseField name="key_notes" type="String">
          Key notes for a KeyNest device.
        </ResponseField>

        <ResponseField name="keynest_app_user" type="String">
          KeyNest app user for a KeyNest device.
        </ResponseField>

        <ResponseField name="last_movement" type="String">
          Last movement timestamp for a KeyNest device.
        </ResponseField>

        <ResponseField name="property_id" type="String">
          Property ID for a KeyNest device.
        </ResponseField>

        <ResponseField name="property_postcode" type="String">
          Property postcode for a KeyNest device.
        </ResponseField>

        <ResponseField name="status_type" type="String">
          Status type for a KeyNest device.
        </ResponseField>

        <ResponseField name="subscription_plan" type="String">
          Subscription plan for a KeyNest device.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="kisi_metadata" type="Object">
      Metadata for a Kisi device.

      <Expandable title="properties">
        <ResponseField name="description" type="String">
          Description for a Kisi device.
        </ResponseField>

        <ResponseField name="lock_id" type="number">
          Lock ID for a Kisi device.
        </ResponseField>

        <ResponseField name="lock_name" type="String">
          Lock name for a Kisi device.
        </ResponseField>

        <ResponseField name="place_name" type="String">
          Place name for a Kisi device.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="korelock_metadata" type="Object">
      Metadata for a Korelock device.

      <Expandable title="properties">
        <ResponseField name="device_id" type="String">
          Device ID for a Korelock device.
        </ResponseField>

        <ResponseField name="device_name" type="String">
          Device name for a Korelock device.
        </ResponseField>

        <ResponseField name="firmware_version" type="String">
          Firmware version for a Korelock device.
        </ResponseField>

        <ResponseField name="location_id" type="String">
          Location ID for a Korelock device. Required for timebound access codes.
        </ResponseField>

        <ResponseField name="model_code" type="String">
          Model code for a Korelock device.
        </ResponseField>

        <ResponseField name="serial_number" type="String">
          Serial number for a Korelock device.
        </ResponseField>

        <ResponseField name="wifi_signal_strength" type="number">
          WiFi signal strength (0-1) for a Korelock device.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="kwikset_metadata" type="Object">
      Metadata for a Kwikset device.

      <Expandable title="properties">
        <ResponseField name="device_id" type="String">
          Device ID for a Kwikset device.
        </ResponseField>

        <ResponseField name="device_name" type="String">
          Device name for a Kwikset device.
        </ResponseField>

        <ResponseField name="model_number" type="String">
          Model number for a Kwikset device.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="lockly_metadata" type="Object">
      Metadata for a Lockly device.

      <Expandable title="properties">
        <ResponseField name="device_id" type="String">
          Device ID for a Lockly device.
        </ResponseField>

        <ResponseField name="device_name" type="String">
          Device name for a Lockly device.
        </ResponseField>

        <ResponseField name="model" type="String">
          Model for a Lockly device.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="minut_metadata" type="Object">
      Metadata for a Minut device.

      <Expandable title="properties">
        <ResponseField name="device_id" type="String">
          Device ID for a Minut device.
        </ResponseField>

        <ResponseField name="device_name" type="String">
          Device name for a Minut device.
        </ResponseField>

        <ResponseField name="latest_sensor_values" type="Object">
          Latest sensor values for a Minut device.

          <Expandable title="properties">
            <ResponseField name="accelerometer_z" type="Object">
              Latest accelerometer Z-axis reading for a Minut device.

              <Expandable title="properties">
                <ResponseField name="time" type="String">
                  Time of latest accelerometer Z-axis reading for a Minut device.
                </ResponseField>

                <ResponseField name="value" type="number">
                  Value of latest accelerometer Z-axis reading for a Minut device.
                </ResponseField>
              </Expandable>
            </ResponseField>

            <ResponseField name="humidity" type="Object">
              Latest humidity reading for a Minut device.

              <Expandable title="properties">
                <ResponseField name="time" type="String">
                  Time of latest humidity reading for a Minut device.
                </ResponseField>

                <ResponseField name="value" type="number">
                  Value of latest humidity reading for a Minut device.
                </ResponseField>
              </Expandable>
            </ResponseField>

            <ResponseField name="pressure" type="Object">
              Latest pressure reading for a Minut device.

              <Expandable title="properties">
                <ResponseField name="time" type="String">
                  Time of latest pressure reading for a Minut device.
                </ResponseField>

                <ResponseField name="value" type="number">
                  Value of latest pressure reading for a Minut device.
                </ResponseField>
              </Expandable>
            </ResponseField>

            <ResponseField name="sound" type="Object">
              Latest sound reading for a Minut device.

              <Expandable title="properties">
                <ResponseField name="time" type="String">
                  Time of latest sound reading for a Minut device.
                </ResponseField>

                <ResponseField name="value" type="number">
                  Value of latest sound reading for a Minut device.
                </ResponseField>
              </Expandable>
            </ResponseField>

            <ResponseField name="temperature" type="Object">
              Latest temperature reading for a Minut device.

              <Expandable title="properties">
                <ResponseField name="time" type="String">
                  Time of latest temperature reading for a Minut device.
                </ResponseField>

                <ResponseField name="value" type="number">
                  Value of latest temperature reading for a Minut device.
                </ResponseField>
              </Expandable>
            </ResponseField>
          </Expandable>
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="nest_metadata" type="Object">
      Metadata for a Google Nest device.

      <Expandable title="properties">
        <ResponseField name="device_custom_name" type="String">
          Custom device name for a Google Nest device. The device owner sets this value.
        </ResponseField>

        <ResponseField name="device_name" type="String">
          Device name for a Google Nest device. Google sets this value.
        </ResponseField>

        <ResponseField name="display_name" type="String">
          Display name for a Google Nest device.
        </ResponseField>

        <ResponseField name="nest_device_id" type="String">
          Device ID for a Google Nest device.
        </ResponseField>

        <ResponseField name="nest_structure_id" type="String">
          ID of the Google Nest structure containing the device.
        </ResponseField>

        <ResponseField name="structure_name" type="String">
          Name of the Google Nest structure containing the device. The device owner sets this value.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="noiseaware_metadata" type="Object">
      Metadata for a NoiseAware device.

      <Expandable title="properties">
        <ResponseField name="device_id" type="String">
          Device ID for a NoiseAware device.
        </ResponseField>

        <ResponseField name="device_model" type="Enum (String)">
          Device model for a NoiseAware device.
        </ResponseField>

        <ResponseField name="device_name" type="String">
          Device name for a NoiseAware device.
        </ResponseField>

        <ResponseField name="noise_level_decibel" type="number">
          Noise level, in decibels, for a NoiseAware device.
        </ResponseField>

        <ResponseField name="noise_level_nrs" type="number">
          Noise level, expressed as a Noise Risk Score (NRS), for a NoiseAware device.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="nuki_metadata" type="Object">
      Metadata for a Nuki device.

      <Expandable title="properties">
        <ResponseField name="device_id" type="String">
          Device ID for a Nuki device.
        </ResponseField>

        <ResponseField name="device_name" type="String">
          Device name for a Nuki device.
        </ResponseField>

        <ResponseField name="keypad_2_paired" type="Boolean">
          Indicates whether keypad 2 is paired for a Nuki device.
        </ResponseField>

        <ResponseField name="keypad_battery_critical" type="Boolean">
          Indicates whether the keypad battery is in a critical state for a Nuki device.
        </ResponseField>

        <ResponseField name="keypad_paired" type="Boolean">
          Indicates whether the keypad is paired for a Nuki device.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="omnitec_metadata" type="Object">
      Metadata for an Omnitec device.

      <Expandable title="properties">
        <ResponseField name="has_gateway" type="Boolean">
          Whether the Omnitec lock has a connected gateway for remote operations.
        </ResponseField>

        <ResponseField name="lock_alias" type="String">
          Operator-assigned alias for an Omnitec device.
        </ResponseField>

        <ResponseField name="lock_id" type="number">
          Lock ID for an Omnitec device.
        </ResponseField>

        <ResponseField name="lock_mac" type="String">
          Bluetooth MAC address for an Omnitec device.
        </ResponseField>

        <ResponseField name="lock_name" type="String">
          Lock name for an Omnitec device.
        </ResponseField>

        <ResponseField name="time_zone" type="String">
          IANA time zone for the Omnitec device, used to schedule time-bound access codes at the correct local time (accounting for DST).
        </ResponseField>

        <ResponseField name="timezone_raw_offset_ms" type="number">
          Static UTC offset of the Omnitec lock in milliseconds. Does not account for DST.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="ring_metadata" type="Object">
      Metadata for a Ring device.

      <Expandable title="properties">
        <ResponseField name="device_id" type="String">
          Device ID for a Ring device.
        </ResponseField>

        <ResponseField name="device_name" type="String">
          Device name for a Ring device.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="salto_ks_metadata" type="Object">
      Metadata for a Salto KS device.

      <Expandable title="properties">
        <ResponseField name="battery_level" type="String">
          Battery level for a Salto KS device.
        </ResponseField>

        <ResponseField name="customer_reference" type="String">
          Customer reference for a Salto KS device.
        </ResponseField>

        <ResponseField name="has_custom_pin_subscription" type="Boolean">
          Indicates whether the site has a Salto KS subscription that supports custom PINs.
        </ResponseField>

        <ResponseField name="lock_id" type="String">
          Lock ID for a Salto KS device.
        </ResponseField>

        <ResponseField name="lock_type" type="String">
          Lock type for a Salto KS device.
        </ResponseField>

        <ResponseField name="locked_state" type="String">
          Locked state for a Salto KS device.
        </ResponseField>

        <ResponseField name="model" type="String">
          Model for a Salto KS device.
        </ResponseField>

        <ResponseField name="site_id" type="String">
          Site ID for the Salto KS site to which the device belongs.
        </ResponseField>

        <ResponseField name="site_name" type="String">
          Site name for the Salto KS site to which the device belongs.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="salto_metadata" type="Object">
      **Deprecated**. Use `salto_ks_metadata` instead.

      Metada for a Salto device.

      <Expandable title="properties">
        <ResponseField name="battery_level" type="String">
          Battery level for a Salto device.
        </ResponseField>

        <ResponseField name="customer_reference" type="String">
          Customer reference for a Salto device.
        </ResponseField>

        <ResponseField name="lock_id" type="String">
          Lock ID for a Salto device.
        </ResponseField>

        <ResponseField name="lock_type" type="String">
          Lock type for a Salto device.
        </ResponseField>

        <ResponseField name="locked_state" type="String">
          Locked state for a Salto device.
        </ResponseField>

        <ResponseField name="model" type="String">
          Model for a Salto device.
        </ResponseField>

        <ResponseField name="site_id" type="String">
          Site ID for the Salto KS site to which the device belongs.
        </ResponseField>

        <ResponseField name="site_name" type="String">
          Site name for the Salto KS site to which the device belongs.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="schlage_metadata" type="Object">
      Metadata for a Schlage device.

      <Expandable title="properties">
        <ResponseField name="device_id" type="String">
          Device ID for a Schlage device.
        </ResponseField>

        <ResponseField name="device_name" type="String">
          Device name for a Schlage device.
        </ResponseField>

        <ResponseField name="model" type="String">
          Model for a Schlage device.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="seam_bridge_metadata" type="Object">
      Metadata for Seam Bridge.

      <Expandable title="properties">
        <ResponseField name="device_num" type="number">
          Device number for Seam Bridge.
        </ResponseField>

        <ResponseField name="name" type="String">
          Name for Seam Bridge.
        </ResponseField>

        <ResponseField name="unlock_method" type="Enum (String)">
          Unlock method for Seam Bridge.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="sensi_metadata" type="Object">
      Metadata for a Sensi device.

      <Expandable title="properties">
        <ResponseField name="device_id" type="String">
          Device ID for a Sensi device.
        </ResponseField>

        <ResponseField name="device_name" type="String">
          Device name for a Sensi device.
        </ResponseField>

        <ResponseField name="dual_setpoints_not_supported" type="Boolean">
          Set to true when the device does not support the /dual-setpoints API endpoint.
        </ResponseField>

        <ResponseField name="enforced_setpoint_range_celsius" type="Array">
          Enforced setpoint range in Celsius for a Sensi device, derived from an OutOfRange API error.
        </ResponseField>

        <ResponseField name="product_type" type="String">
          Product type for a Sensi device.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="smartthings_metadata" type="Object">
      Metadata for a SmartThings device.

      <Expandable title="properties">
        <ResponseField name="device_id" type="String">
          Device ID for a SmartThings device.
        </ResponseField>

        <ResponseField name="device_name" type="String">
          Device name for a SmartThings device.
        </ResponseField>

        <ResponseField name="location_id" type="String">
          Location ID for a SmartThings device.
        </ResponseField>

        <ResponseField name="model" type="String">
          Model for a SmartThings device.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="tado_metadata" type="Object">
      Metadata for a tado° device.

      <Expandable title="properties">
        <ResponseField name="device_type" type="String">
          Device type for a tado° device.
        </ResponseField>

        <ResponseField name="serial_no" type="String">
          Serial number for a tado° device.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="tedee_metadata" type="Object">
      Metadata for a Tedee device.

      <Expandable title="properties">
        <ResponseField name="bridge_id" type="number">
          Bridge ID for a Tedee device.
        </ResponseField>

        <ResponseField name="bridge_name" type="String">
          Bridge name for a Tedee device.
        </ResponseField>

        <ResponseField name="device_id" type="number">
          Device ID for a Tedee device.
        </ResponseField>

        <ResponseField name="device_model" type="String">
          Device model for a Tedee device.
        </ResponseField>

        <ResponseField name="device_name" type="String">
          Device name for a Tedee device.
        </ResponseField>

        <ResponseField name="keypad_id" type="number">
          Keypad ID for a Tedee device.
        </ResponseField>

        <ResponseField name="serial_number" type="String">
          Serial number for a Tedee device.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="ttlock_metadata" type="Object">
      Metadata for a TTLock device.

      <Expandable title="properties">
        <ResponseField name="feature_value" type="String">
          Feature value for a TTLock device.
        </ResponseField>

        <ResponseField name="features" type="Object">
          Features for a TTLock device.

          <Expandable title="properties">
            <ResponseField name="auto_lock_time_config" type="Boolean">
              Indicates whether a TTLock device supports auto-lock time configuration.
            </ResponseField>

            <ResponseField name="incomplete_keyboard_passcode" type="Boolean">
              Indicates whether a TTLock device supports an incomplete keyboard passcode.
            </ResponseField>

            <ResponseField name="lock_command" type="Boolean">
              Indicates whether a TTLock device supports the lock command.
            </ResponseField>

            <ResponseField name="passcode" type="Boolean">
              Indicates whether a TTLock device supports a passcode.
            </ResponseField>

            <ResponseField name="passcode_management" type="Boolean">
              Indicates whether a TTLock device supports passcode management.
            </ResponseField>

            <ResponseField name="unlock_via_gateway" type="Boolean">
              Indicates whether a TTLock device supports unlock via gateway.
            </ResponseField>

            <ResponseField name="wifi" type="Boolean">
              Indicates whether a TTLock device supports Wi-Fi.
            </ResponseField>
          </Expandable>
        </ResponseField>

        <ResponseField name="has_gateway" type="Boolean">
          Indicates whether a TTLock device has a gateway.
        </ResponseField>

        <ResponseField name="lock_alias" type="String">
          Lock alias for a TTLock device.
        </ResponseField>

        <ResponseField name="lock_id" type="number">
          Lock ID for a TTLock device.
        </ResponseField>

        <ResponseField name="timezone_raw_offset_ms" type="number">
          Lock-side timezone offset in milliseconds east of UTC, as configured in the TTLock app. Source of truth for the lock's wall-clock interpretation of access code start/end times — a misconfigured value here is the typical cause of customer "codes offset by N hours" reports. Diagnostic only; Seam does not convert times based on this value.
        </ResponseField>

        <ResponseField name="wireless_keypads" type="Array">
          Wireless keypads for a TTLock device.

          <Expandable title="properties">
            <ResponseField name="wireless_keypad_id" type="number">
              ID for a wireless keypad for a TTLock device.
            </ResponseField>

            <ResponseField name="wireless_keypad_name" type="String">
              Name for a wireless keypad for a TTLock device.
            </ResponseField>
          </Expandable>
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="two_n_metadata" type="Object">
      Metadata for a 2N device.

      <Expandable title="properties">
        <ResponseField name="device_id" type="number">
          Device ID for a 2N device.
        </ResponseField>

        <ResponseField name="device_name" type="String">
          Device name for a 2N device.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="ultraloq_metadata" type="Object">
      Metadata for an Ultraloq device.

      <Expandable title="properties">
        <ResponseField name="device_id" type="String">
          Device ID for an Ultraloq device.
        </ResponseField>

        <ResponseField name="device_name" type="String">
          Device name for an Ultraloq device.
        </ResponseField>

        <ResponseField name="device_type" type="String">
          Device type for an Ultraloq device.
        </ResponseField>

        <ResponseField name="time_zone" type="String">
          IANA timezone for the Ultraloq device.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="visionline_metadata" type="Object">
      Metadata for an ASSA ABLOY Visionline system.

      <Expandable title="properties">
        <ResponseField name="encoder_id" type="String">
          Encoder ID for an ASSA ABLOY Visionline system.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="wyze_metadata" type="Object">
      Metadata for a Wyze device.

      <Expandable title="properties">
        <ResponseField name="device_id" type="String">
          Device ID for a Wyze device.
        </ResponseField>

        <ResponseField name="device_info_model" type="String">
          Device information model for a Wyze device.
        </ResponseField>

        <ResponseField name="device_name" type="String">
          Device name for a Wyze device.
        </ResponseField>

        <ResponseField name="keypad_uuid" type="String">
          Keypad UUID for a Wyze device.
        </ResponseField>

        <ResponseField name="locker_status_hardlock" type="number">
          Locker status (hardlock) for a Wyze device.
        </ResponseField>

        <ResponseField name="product_model" type="String">
          Product model for a Wyze device.
        </ResponseField>

        <ResponseField name="product_name" type="String">
          Product name for a Wyze device.
        </ResponseField>

        <ResponseField name="product_type" type="String">
          Product type for a Wyze device.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="auto_lock_delay_seconds" type="number">
      The delay in seconds before the lock automatically locks after being unlocked.
    </ResponseField>

    <ResponseField name="auto_lock_enabled" type="Boolean">
      Indicates whether automatic locking is enabled.
    </ResponseField>

    <ResponseField name="backup_access_code_pool_enabled" type="Boolean">
      Indicates whether the [backup access code pool](/low-level-apis/smart-locks/access-codes/backup-access-codes) is currently enabled for the device. To disable it, set this to `false` using [/devices/update](/api/devices/update).
    </ResponseField>

    <ResponseField name="code_constraints" type="Array">
      Constraints on access codes for the device. Seam represents each constraint as an object with a `constraint_type` property. Depending on the constraint type, there may also be additional properties. Note that some constraints are manufacturer- or device-specific.

      <Expandable title="properties">
        <ResponseField name="constraint_type" type="Enum (String)">
          The constraint type.
        </ResponseField>

        <ResponseField name="max_length" type="number">
          Maximum name length constraint for access codes.
        </ResponseField>

        <ResponseField name="min_length" type="number">
          Minimum name length constraint for access codes.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="door_open" type="Boolean">
      Indicates whether the door is open.
    </ResponseField>

    <ResponseField name="has_native_entry_events" type="Boolean">
      Indicates whether the device supports native entry events.
    </ResponseField>

    <ResponseField name="keypad_battery" type="Object">
      Keypad battery status.

      <Expandable title="properties">
        <ResponseField name="level" type="number">
          Keypad battery charge level.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="locked" type="Boolean">
      Indicates whether the lock is locked.
    </ResponseField>

    <ResponseField name="max_active_codes_supported" type="number">
      Maximum number of active access codes that the device supports.
    </ResponseField>

    <ResponseField name="offline_time_frame_options" type="Array">
      Time frames that may be requested when creating an offline access code, expressed as a list of options. The caller picks one option (by matching the requested duration when the options' duration ranges do not overlap, or by `display_name` when they do) and satisfies that one option's rules. When `undefined`, any time frame works.

      <Expandable title="properties">
        <ResponseField name="display_name" type="String">
          Label for this option. For a single-option device, the product name (for example, `algoPIN` or `SmartPIN`); for a multi-option device, a label that distinguishes it (for example, `Hourly` or `Fixed start times`).
        </ResponseField>

        <ResponseField name="end_date_recurrence_rule" type="String">
          iCalendar recurrence rule (RRULE) that the end date must fall on. Constrains which calendar dates are selectable, independent of the time-of-day rules.
        </ResponseField>

        <ResponseField name="matching_start_end_time" type="Boolean">
          When `true`, the start and end must fall at the same time of day (the caller picks which). Mutually exclusive with `time_pairs`.
        </ResponseField>

        <ResponseField name="max_duration" type="String">
          Maximum duration this option covers, as an ISO 8601 duration (for example, `PT672H` or `P367D`). Omitted when there is no maximum.
        </ResponseField>

        <ResponseField name="min_duration" type="String">
          Minimum duration this option covers, as an ISO 8601 duration (for example, `PT1H` or `P29D`). Omitted when there is no minimum.
        </ResponseField>

        <ResponseField name="start_date_recurrence_rule" type="String">
          iCalendar recurrence rule (RRULE) that the start date must fall on (for example, `FREQ=MONTHLY;BYDAY=1MO,3MO`). Constrains which calendar dates are selectable, independent of the time-of-day rules.
        </ResponseField>

        <ResponseField name="time_pairs" type="Array">
          Fixed start/end time pairings the caller chooses from. Mutually exclusive with `matching_start_end_time`.

          <Expandable title="properties">
            <ResponseField name="display_name" type="String">
              Label for the start/end time pairing.
            </ResponseField>

            <ResponseField name="end_time" type="String">
              End time of day as a 24-hour `HH:MM` value, interpreted in the option's `time_zone`. An `end_time` earlier on the clock than `start_time` means the end falls on a later date.
            </ResponseField>

            <ResponseField name="start_time" type="String">
              Start time of day as a 24-hour `HH:MM` value, interpreted in the option's `time_zone`.
            </ResponseField>
          </Expandable>
        </ResponseField>

        <ResponseField name="time_zone" type="String">
          IANA time zone for interpreting `time_pairs` and the date recurrence rules. Present only when the option fixes times or dates.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="online_time_frame_options" type="Array">
      Time frames that may be requested when creating an online access code, expressed as a list of options. The caller picks one option (by matching the requested duration when the options' duration ranges do not overlap, or by `display_name` when they do) and satisfies that one option's rules. When `undefined`, any time frame works.

      <Expandable title="properties">
        <ResponseField name="display_name" type="String">
          Label for this option. For a single-option device, the product name (for example, `algoPIN` or `SmartPIN`); for a multi-option device, a label that distinguishes it (for example, `Hourly` or `Fixed start times`).
        </ResponseField>

        <ResponseField name="end_date_recurrence_rule" type="String">
          iCalendar recurrence rule (RRULE) that the end date must fall on. Constrains which calendar dates are selectable, independent of the time-of-day rules.
        </ResponseField>

        <ResponseField name="matching_start_end_time" type="Boolean">
          When `true`, the start and end must fall at the same time of day (the caller picks which). Mutually exclusive with `time_pairs`.
        </ResponseField>

        <ResponseField name="max_duration" type="String">
          Maximum duration this option covers, as an ISO 8601 duration (for example, `PT672H` or `P367D`). Omitted when there is no maximum.
        </ResponseField>

        <ResponseField name="min_duration" type="String">
          Minimum duration this option covers, as an ISO 8601 duration (for example, `PT1H` or `P29D`). Omitted when there is no minimum.
        </ResponseField>

        <ResponseField name="start_date_recurrence_rule" type="String">
          iCalendar recurrence rule (RRULE) that the start date must fall on (for example, `FREQ=MONTHLY;BYDAY=1MO,3MO`). Constrains which calendar dates are selectable, independent of the time-of-day rules.
        </ResponseField>

        <ResponseField name="time_pairs" type="Array">
          Fixed start/end time pairings the caller chooses from. Mutually exclusive with `matching_start_end_time`.

          <Expandable title="properties">
            <ResponseField name="display_name" type="String">
              Label for the start/end time pairing.
            </ResponseField>

            <ResponseField name="end_time" type="String">
              End time of day as a 24-hour `HH:MM` value, interpreted in the option's `time_zone`. An `end_time` earlier on the clock than `start_time` means the end falls on a later date.
            </ResponseField>

            <ResponseField name="start_time" type="String">
              Start time of day as a 24-hour `HH:MM` value, interpreted in the option's `time_zone`.
            </ResponseField>
          </Expandable>
        </ResponseField>

        <ResponseField name="time_zone" type="String">
          IANA time zone for interpreting `time_pairs` and the date recurrence rules. Present only when the option fixes times or dates.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="supported_code_lengths" type="Array">
      Supported code lengths for access codes.
    </ResponseField>

    <ResponseField name="supports_backup_access_code_pool" type="Boolean">
      Indicates whether the device supports a [backup access code pool](/low-level-apis/smart-locks/access-codes/backup-access-codes).
    </ResponseField>

    <ResponseField name="active_thermostat_schedule" type="Object">
      **Deprecated**. Use `active_thermostat_schedule_id` with `/thermostats/schedules/get` instead.

      Active [thermostat schedule](/capability-guides/thermostats/creating-and-managing-thermostat-schedules).

      <Expandable title="properties">
        <ResponseField name="climate_preset_key" type="String">
          Key of the [climate preset](/capability-guides/thermostats/creating-and-managing-climate-presets) to use for the [thermostat schedule](/capability-guides/thermostats/creating-and-managing-thermostat-schedules).
        </ResponseField>

        <ResponseField name="created_at" type="String (ISO 8601)">
          Date and time at which the [thermostat schedule](/capability-guides/thermostats/creating-and-managing-thermostat-schedules) was created.
        </ResponseField>

        <ResponseField name="device_id" type="String (UUID)">
          ID of the desired [thermostat](/capability-guides/thermostats) device.
        </ResponseField>

        <ResponseField name="ends_at" type="String (ISO 8601)">
          Date and time at which the [thermostat schedule](/capability-guides/thermostats/creating-and-managing-thermostat-schedules) ends, in [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) format.
        </ResponseField>

        <ResponseField name="errors" type="Array">
          Errors associated with the [thermostat schedule](/capability-guides/thermostats/creating-and-managing-thermostat-schedules).

          <Expandable title="properties">
            <ResponseField name="created_at" type="String (ISO 8601)">
              Date and time at which Seam created the error.
            </ResponseField>

            <ResponseField name="error_code" type="String">
              Unique identifier of the type of error. Enables quick recognition and categorization of the issue.
            </ResponseField>

            <ResponseField name="message" type="String">
              Detailed description of the error. Provides insights into the issue and potentially how to rectify it.
            </ResponseField>
          </Expandable>
        </ResponseField>

        <ResponseField name="is_override_allowed" type="Boolean">
          Indicates whether a person at the thermostat can change the thermostat's settings after the [thermostat schedule](/capability-guides/thermostats/creating-and-managing-thermostat-schedules) starts.
        </ResponseField>

        <ResponseField name="max_override_period_minutes" type="number">
          Number of minutes for which a person at the thermostat can change the thermostat's settings after the activation of the scheduled [climate preset](/capability-guides/thermostats/creating-and-managing-climate-presets). See also [Specifying Manual Override Permissions](/capability-guides/thermostats/creating-and-managing-thermostat-schedules#specifying-manual-override-permissions).
        </ResponseField>

        <ResponseField name="name" type="String">
          User-friendly name to identify the [thermostat schedule](/capability-guides/thermostats/creating-and-managing-thermostat-schedules).
        </ResponseField>

        <ResponseField name="starts_at" type="String (ISO 8601)">
          Date and time at which the [thermostat schedule](/capability-guides/thermostats/creating-and-managing-thermostat-schedules) starts, in [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) format.
        </ResponseField>

        <ResponseField name="thermostat_schedule_id" type="String (UUID)">
          ID of the [thermostat schedule](/capability-guides/thermostats/creating-and-managing-thermostat-schedules).
        </ResponseField>

        <ResponseField name="workspace_id" type="String (UUID)">
          ID of the workspace that contains the thermostat schedule.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="active_thermostat_schedule_id" type="String (UUID)">
      ID of the active [thermostat schedule](/capability-guides/thermostats/creating-and-managing-thermostat-schedules).
    </ResponseField>

    <ResponseField name="available_climate_preset_modes" type="Array">
      Climate preset modes that the thermostat supports, such as "home", "away", "wake", "sleep", "occupied", and "unoccupied".
    </ResponseField>

    <ResponseField name="available_climate_presets" type="Array">
      Available [climate presets](/capability-guides/thermostats/creating-and-managing-climate-presets) for the thermostat.

      <Expandable title="properties">
        <ResponseField name="can_delete" type="Boolean">
          Indicates whether the [climate preset](/capability-guides/thermostats/creating-and-managing-climate-presets) key can be deleted.
        </ResponseField>

        <ResponseField name="can_edit" type="Boolean">
          Indicates whether the [climate preset](/capability-guides/thermostats/creating-and-managing-climate-presets) key can be edited.
        </ResponseField>

        <ResponseField name="can_use_with_thermostat_daily_programs" type="Boolean">
          Indicates whether the [climate preset](/capability-guides/thermostats/creating-and-managing-climate-presets) key can be programmed in a thermostat daily program.
        </ResponseField>

        <ResponseField name="climate_preset_key" type="String">
          Unique key to identify the [climate preset](/capability-guides/thermostats/creating-and-managing-climate-presets).
        </ResponseField>

        <ResponseField name="climate_preset_mode" type="Enum (String)">
          The climate preset mode for the thermostat, based on the available climate preset modes reported by the device.
        </ResponseField>

        <ResponseField name="cooling_set_point_celsius" type="number">
          Temperature to which the thermostat should cool (in °C). See also [Set Points](/capability-guides/thermostats/understanding-thermostat-concepts/set-points).
        </ResponseField>

        <ResponseField name="cooling_set_point_fahrenheit" type="number">
          Temperature to which the thermostat should cool (in °F). See also [Set Points](/capability-guides/thermostats/understanding-thermostat-concepts/set-points).
        </ResponseField>

        <ResponseField name="display_name" type="String">
          Display name for the [climate preset](/capability-guides/thermostats/creating-and-managing-climate-presets).
        </ResponseField>

        <ResponseField name="ecobee_metadata" type="Object">
          Metadata specific to the Ecobee climate, if applicable.

          <Expandable title="properties">
            <ResponseField name="climate_ref" type="String">
              Reference to the Ecobee climate, if applicable.
            </ResponseField>

            <ResponseField name="is_optimized" type="Boolean">
              Indicates if the climate preset is optimized by Ecobee.
            </ResponseField>

            <ResponseField name="owner" type="Enum (String)">
              Indicates whether the climate preset is owned by the user or the system.
            </ResponseField>
          </Expandable>
        </ResponseField>

        <ResponseField name="fan_mode_setting" type="Enum (String)">
          Desired [fan mode setting](/capability-guides/thermostats/configure-current-climate-settings#fan-mode-settings), such as `on`, `auto`, or `circulate`.
        </ResponseField>

        <ResponseField name="heating_set_point_celsius" type="number">
          Temperature to which the thermostat should heat (in °C). See also [Set Points](/capability-guides/thermostats/understanding-thermostat-concepts/set-points).
        </ResponseField>

        <ResponseField name="heating_set_point_fahrenheit" type="number">
          Temperature to which the thermostat should heat (in °F). See also [Set Points](/capability-guides/thermostats/understanding-thermostat-concepts/set-points).
        </ResponseField>

        <ResponseField name="hvac_mode_setting" type="Enum (String)">
          Desired [HVAC mode](/capability-guides/thermostats/understanding-thermostat-concepts/hvac-mode) setting, such as `heat`, `cool`, `heat_cool`, or `off`.
        </ResponseField>

        <ResponseField name="manual_override_allowed" type="Boolean">
          **Deprecated**. Use 'thermostat\_schedule.is\_override\_allowed'

          Indicates whether a person at the thermostat can change the thermostat's settings. See [Specifying Manual Override Permissions](/capability-guides/thermostats/creating-and-managing-thermostat-schedules#specifying-manual-override-permissions).
        </ResponseField>

        <ResponseField name="name" type="String">
          User-friendly name to identify the [climate preset](/capability-guides/thermostats/creating-and-managing-climate-presets).
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="available_fan_mode_settings" type="Array">
      Fan mode settings that the thermostat supports.
    </ResponseField>

    <ResponseField name="available_hvac_mode_settings" type="Array">
      HVAC mode settings that the thermostat supports.
    </ResponseField>

    <ResponseField name="current_climate_setting" type="Object">
      Current climate setting.

      <Expandable title="properties">
        <ResponseField name="can_delete" type="Boolean">
          Indicates whether the [climate preset](/capability-guides/thermostats/creating-and-managing-climate-presets) key can be deleted.
        </ResponseField>

        <ResponseField name="can_edit" type="Boolean">
          Indicates whether the [climate preset](/capability-guides/thermostats/creating-and-managing-climate-presets) key can be edited.
        </ResponseField>

        <ResponseField name="can_use_with_thermostat_daily_programs" type="Boolean">
          Indicates whether the [climate preset](/capability-guides/thermostats/creating-and-managing-climate-presets) key can be programmed in a thermostat daily program.
        </ResponseField>

        <ResponseField name="climate_preset_key" type="String">
          Unique key to identify the [climate preset](/capability-guides/thermostats/creating-and-managing-climate-presets).
        </ResponseField>

        <ResponseField name="climate_preset_mode" type="Enum (String)">
          The climate preset mode for the thermostat, based on the available climate preset modes reported by the device.
        </ResponseField>

        <ResponseField name="cooling_set_point_celsius" type="number">
          Temperature to which the thermostat should cool (in °C). See also [Set Points](/capability-guides/thermostats/understanding-thermostat-concepts/set-points).
        </ResponseField>

        <ResponseField name="cooling_set_point_fahrenheit" type="number">
          Temperature to which the thermostat should cool (in °F). See also [Set Points](/capability-guides/thermostats/understanding-thermostat-concepts/set-points).
        </ResponseField>

        <ResponseField name="display_name" type="String">
          Display name for the [climate preset](/capability-guides/thermostats/creating-and-managing-climate-presets).
        </ResponseField>

        <ResponseField name="ecobee_metadata" type="Object">
          Metadata specific to the Ecobee climate, if applicable.

          <Expandable title="properties">
            <ResponseField name="climate_ref" type="String">
              Reference to the Ecobee climate, if applicable.
            </ResponseField>

            <ResponseField name="is_optimized" type="Boolean">
              Indicates if the climate preset is optimized by Ecobee.
            </ResponseField>

            <ResponseField name="owner" type="Enum (String)">
              Indicates whether the climate preset is owned by the user or the system.
            </ResponseField>
          </Expandable>
        </ResponseField>

        <ResponseField name="fan_mode_setting" type="Enum (String)">
          Desired [fan mode setting](/capability-guides/thermostats/configure-current-climate-settings#fan-mode-settings), such as `on`, `auto`, or `circulate`.
        </ResponseField>

        <ResponseField name="heating_set_point_celsius" type="number">
          Temperature to which the thermostat should heat (in °C). See also [Set Points](/capability-guides/thermostats/understanding-thermostat-concepts/set-points).
        </ResponseField>

        <ResponseField name="heating_set_point_fahrenheit" type="number">
          Temperature to which the thermostat should heat (in °F). See also [Set Points](/capability-guides/thermostats/understanding-thermostat-concepts/set-points).
        </ResponseField>

        <ResponseField name="hvac_mode_setting" type="Enum (String)">
          Desired [HVAC mode](/capability-guides/thermostats/understanding-thermostat-concepts/hvac-mode) setting, such as `heat`, `cool`, `heat_cool`, or `off`.
        </ResponseField>

        <ResponseField name="manual_override_allowed" type="Boolean">
          **Deprecated**. Use 'thermostat\_schedule.is\_override\_allowed'

          Indicates whether a person at the thermostat can change the thermostat's settings. See [Specifying Manual Override Permissions](/capability-guides/thermostats/creating-and-managing-thermostat-schedules#specifying-manual-override-permissions).
        </ResponseField>

        <ResponseField name="name" type="String">
          User-friendly name to identify the [climate preset](/capability-guides/thermostats/creating-and-managing-climate-presets).
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="default_climate_setting" type="Object">
      **Deprecated**. use fallback\_climate\_preset\_key to specify a fallback climate preset instead.

      The default climate setting.

      <Expandable title="properties">
        <ResponseField name="can_delete" type="Boolean">
          Indicates whether the [climate preset](/capability-guides/thermostats/creating-and-managing-climate-presets) key can be deleted.
        </ResponseField>

        <ResponseField name="can_edit" type="Boolean">
          Indicates whether the [climate preset](/capability-guides/thermostats/creating-and-managing-climate-presets) key can be edited.
        </ResponseField>

        <ResponseField name="can_use_with_thermostat_daily_programs" type="Boolean">
          Indicates whether the [climate preset](/capability-guides/thermostats/creating-and-managing-climate-presets) key can be programmed in a thermostat daily program.
        </ResponseField>

        <ResponseField name="climate_preset_key" type="String">
          Unique key to identify the [climate preset](/capability-guides/thermostats/creating-and-managing-climate-presets).
        </ResponseField>

        <ResponseField name="climate_preset_mode" type="Enum (String)">
          The climate preset mode for the thermostat, based on the available climate preset modes reported by the device.
        </ResponseField>

        <ResponseField name="cooling_set_point_celsius" type="number">
          Temperature to which the thermostat should cool (in °C). See also [Set Points](/capability-guides/thermostats/understanding-thermostat-concepts/set-points).
        </ResponseField>

        <ResponseField name="cooling_set_point_fahrenheit" type="number">
          Temperature to which the thermostat should cool (in °F). See also [Set Points](/capability-guides/thermostats/understanding-thermostat-concepts/set-points).
        </ResponseField>

        <ResponseField name="display_name" type="String">
          Display name for the [climate preset](/capability-guides/thermostats/creating-and-managing-climate-presets).
        </ResponseField>

        <ResponseField name="ecobee_metadata" type="Object">
          Metadata specific to the Ecobee climate, if applicable.

          <Expandable title="properties">
            <ResponseField name="climate_ref" type="String">
              Reference to the Ecobee climate, if applicable.
            </ResponseField>

            <ResponseField name="is_optimized" type="Boolean">
              Indicates if the climate preset is optimized by Ecobee.
            </ResponseField>

            <ResponseField name="owner" type="Enum (String)">
              Indicates whether the climate preset is owned by the user or the system.
            </ResponseField>
          </Expandable>
        </ResponseField>

        <ResponseField name="fan_mode_setting" type="Enum (String)">
          Desired [fan mode setting](/capability-guides/thermostats/configure-current-climate-settings#fan-mode-settings), such as `on`, `auto`, or `circulate`.
        </ResponseField>

        <ResponseField name="heating_set_point_celsius" type="number">
          Temperature to which the thermostat should heat (in °C). See also [Set Points](/capability-guides/thermostats/understanding-thermostat-concepts/set-points).
        </ResponseField>

        <ResponseField name="heating_set_point_fahrenheit" type="number">
          Temperature to which the thermostat should heat (in °F). See also [Set Points](/capability-guides/thermostats/understanding-thermostat-concepts/set-points).
        </ResponseField>

        <ResponseField name="hvac_mode_setting" type="Enum (String)">
          Desired [HVAC mode](/capability-guides/thermostats/understanding-thermostat-concepts/hvac-mode) setting, such as `heat`, `cool`, `heat_cool`, or `off`.
        </ResponseField>

        <ResponseField name="manual_override_allowed" type="Boolean">
          **Deprecated**. Use 'thermostat\_schedule.is\_override\_allowed'

          Indicates whether a person at the thermostat can change the thermostat's settings. See [Specifying Manual Override Permissions](/capability-guides/thermostats/creating-and-managing-thermostat-schedules#specifying-manual-override-permissions).
        </ResponseField>

        <ResponseField name="name" type="String">
          User-friendly name to identify the [climate preset](/capability-guides/thermostats/creating-and-managing-climate-presets).
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="fallback_climate_preset_key" type="String">
      Key of the [fallback climate preset](/capability-guides/thermostats/creating-and-managing-climate-presets/setting-the-fallback-climate-preset) for the thermostat.
    </ResponseField>

    <ResponseField name="fan_mode_setting" type="Enum (String)">
      **Deprecated**. Use `current_climate_setting.fan_mode_setting` instead.

      The fan mode setting.
    </ResponseField>

    <ResponseField name="is_cooling" type="Boolean">
      Indicates whether the connected HVAC system is currently cooling, as reported by the thermostat.
    </ResponseField>

    <ResponseField name="is_fan_running" type="Boolean">
      Indicates whether the fan in the connected HVAC system is currently running, as reported by the thermostat.
    </ResponseField>

    <ResponseField name="is_heating" type="Boolean">
      Indicates whether the connected HVAC system is currently heating, as reported by the thermostat.
    </ResponseField>

    <ResponseField name="is_temporary_manual_override_active" type="Boolean">
      Indicates whether the current thermostat settings differ from the most recent active program or schedule that Seam activated. For this condition to occur, `current_climate_setting.manual_override_allowed` must also be `true`.
    </ResponseField>

    <ResponseField name="max_cooling_set_point_celsius" type="number">
      Maximum [cooling set point](/capability-guides/thermostats/understanding-thermostat-concepts/set-points#cooling-set-point) in °C.
    </ResponseField>

    <ResponseField name="max_cooling_set_point_fahrenheit" type="number">
      Maximum [cooling set point](/capability-guides/thermostats/understanding-thermostat-concepts/set-points#cooling-set-point) in °F.
    </ResponseField>

    <ResponseField name="max_heating_set_point_celsius" type="number">
      Maximum [heating set point](/capability-guides/thermostats/understanding-thermostat-concepts/set-points#heating-set-point) in °C.
    </ResponseField>

    <ResponseField name="max_heating_set_point_fahrenheit" type="number">
      Maximum [heating set point](/capability-guides/thermostats/understanding-thermostat-concepts/set-points#heating-set-point) in °F.
    </ResponseField>

    <ResponseField name="max_thermostat_daily_program_periods_per_day" type="number">
      Maximum number of periods that the thermostat can support per day. For example, if the thermostat supports 4 periods per day, this value is 4.
    </ResponseField>

    <ResponseField name="max_unique_climate_presets_per_thermostat_weekly_program" type="number">
      Maximum number of climate presets that the thermostat can support for weekly programming.
    </ResponseField>

    <ResponseField name="min_cooling_set_point_celsius" type="number">
      Minimum [cooling set point](/capability-guides/thermostats/understanding-thermostat-concepts/set-points#cooling-set-point) in °C.
    </ResponseField>

    <ResponseField name="min_cooling_set_point_fahrenheit" type="number">
      Minimum [cooling set point](/capability-guides/thermostats/understanding-thermostat-concepts/set-points#cooling-set-point) in °F.
    </ResponseField>

    <ResponseField name="min_heating_cooling_delta_celsius" type="number">
      Minimum [temperature difference](/capability-guides/thermostats/understanding-thermostat-concepts/set-points#minimum-heating-cooling-temperature-delta) in °C between the cooling and heating set points when in heat-cool (auto) mode.
    </ResponseField>

    <ResponseField name="min_heating_cooling_delta_fahrenheit" type="number">
      Minimum [temperature difference](/capability-guides/thermostats/understanding-thermostat-concepts/set-points#minimum-heating-cooling-temperature-delta) in °F between the cooling and heating set points when in heat-cool (auto) mode.
    </ResponseField>

    <ResponseField name="min_heating_set_point_celsius" type="number">
      Minimum [heating set point](/capability-guides/thermostats/understanding-thermostat-concepts/set-points#heating-set-point) in °C.
    </ResponseField>

    <ResponseField name="min_heating_set_point_fahrenheit" type="number">
      Minimum [heating set point](/capability-guides/thermostats/understanding-thermostat-concepts/set-points#heating-set-point) in °F.
    </ResponseField>

    <ResponseField name="relative_humidity" type="number">
      Reported relative humidity, as a value between 0 and 1, inclusive.
    </ResponseField>

    <ResponseField name="temperature_celsius" type="number">
      Reported temperature in °C.
    </ResponseField>

    <ResponseField name="temperature_fahrenheit" type="number">
      Reported temperature in °F.
    </ResponseField>

    <ResponseField name="temperature_threshold" type="Object">
      Current [temperature threshold](/capability-guides/thermostats/setting-and-monitoring-temperature-thresholds) set for the thermostat.

      <Expandable title="properties">
        <ResponseField name="lower_limit_celsius" type="number">
          Lower limit in °C within the current [temperature threshold](/capability-guides/thermostats/setting-and-monitoring-temperature-thresholds) set for the thermostat.
        </ResponseField>

        <ResponseField name="lower_limit_fahrenheit" type="number">
          Lower limit in °F within the current [temperature threshold](/capability-guides/thermostats/setting-and-monitoring-temperature-thresholds) set for the thermostat.
        </ResponseField>

        <ResponseField name="upper_limit_celsius" type="number">
          Upper limit in °C within the current [temperature threshold](/capability-guides/thermostats/setting-and-monitoring-temperature-thresholds) set for the thermostat.
        </ResponseField>

        <ResponseField name="upper_limit_fahrenheit" type="number">
          Upper limit in °F within the current [temperature threshold](/capability-guides/thermostats/setting-and-monitoring-temperature-thresholds) set for the thermostat.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="thermostat_daily_program_period_precision_minutes" type="number">
      Precision of the thermostat's period in minutes. For example, if the thermostat supports 15-minute periods, this value is 15. All values are relative to the top of the hour, so for 15 minutes, the periods would be 0, 15, 30, and 45 minutes past the hour.
    </ResponseField>

    <ResponseField name="thermostat_daily_programs" type="Array">
      Configured [daily programs](/capability-guides/thermostats/creating-and-managing-thermostat-programs) for the thermostat.

      <Expandable title="properties">
        <ResponseField name="created_at" type="String (ISO 8601)">
          Date and time at which the thermostat daily program was created.
        </ResponseField>

        <ResponseField name="device_id" type="String (UUID)">
          ID of the thermostat device on which the thermostat daily program is configured.
        </ResponseField>

        <ResponseField name="name" type="String">
          User-friendly name to identify the thermostat daily program.
        </ResponseField>

        <ResponseField name="periods" type="Array">
          Array of thermostat daily program periods.

          <Expandable title="properties">
            <ResponseField name="climate_preset_key" type="String">
              Key of the [climate preset](/capability-guides/thermostats/creating-and-managing-climate-presets) to activate at the `starts_at_time`.
            </ResponseField>

            <ResponseField name="starts_at_time" type="String">
              Time at which the thermostat daily program period starts, in [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) format.
            </ResponseField>
          </Expandable>
        </ResponseField>

        <ResponseField name="thermostat_daily_program_id" type="String (UUID)">
          ID of the thermostat daily program.
        </ResponseField>

        <ResponseField name="workspace_id" type="String (UUID)">
          ID of the workspace that contains the thermostat daily program.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="thermostat_weekly_program" type="Object">
      Current [weekly program](/capability-guides/thermostats/creating-and-managing-thermostat-programs) for the thermostat.

      <Expandable title="properties">
        <ResponseField name="created_at" type="String (ISO 8601)">
          Date and time at which the thermostat weekly program was created.
        </ResponseField>

        <ResponseField name="friday_program_id" type="String (UUID)">
          ID of the thermostat daily program to run on Fridays.
        </ResponseField>

        <ResponseField name="monday_program_id" type="String (UUID)">
          ID of the thermostat daily program to run on Mondays.
        </ResponseField>

        <ResponseField name="saturday_program_id" type="String (UUID)">
          ID of the thermostat daily program to run on Saturdays.
        </ResponseField>

        <ResponseField name="sunday_program_id" type="String (UUID)">
          ID of the thermostat daily program to run on Sundays.
        </ResponseField>

        <ResponseField name="thursday_program_id" type="String (UUID)">
          ID of the thermostat daily program to run on Thursdays.
        </ResponseField>

        <ResponseField name="tuesday_program_id" type="String (UUID)">
          ID of the thermostat daily program to run on Tuesdays.
        </ResponseField>

        <ResponseField name="wednesday_program_id" type="String (UUID)">
          ID of the thermostat daily program to run on Wednesdays.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="space_ids" type="Array">
  IDs of the spaces the device is in.
</ResponseField>

<ResponseField name="warnings" type="Array">
  Array of warnings associated with the device. Each warning object within the array contains two fields: `warning_code` and `message`. `warning_code` is a string that uniquely identifies the type of warning, enabling quick recognition and categorization of the issue. `message` provides a more detailed description of the warning, offering insights into the issue and potentially how to rectify it.
</ResponseField>

<ResponseField name="workspace_id" type="String (UUID)">
  Unique identifier for the Seam workspace associated with the device.
</ResponseField>

<ResponseField name="device_manufacturer" type="Object">
  Manufacturer of the device. Represents the hardware brand, which may differ from the provider.

  <Expandable title="properties">
    <ResponseField name="display_name" type="String">
      Display name for the manufacturer, such as `August`, `Yale`, `Salto`, and so on.
    </ResponseField>

    <ResponseField name="image_url" type="String">
      Image URL for the manufacturer logo.
    </ResponseField>

    <ResponseField name="manufacturer" type="String">
      Manufacturer identifier, such as `august`, `yale`, `salto`, and so on.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="device_provider" type="Object">
  Provider of the device. Represents the third-party service through which the device is controlled.

  <Expandable title="properties">
    <ResponseField name="device_provider_name" type="String">
      Device provider name. Corresponds to the integration type, such as `august`, `schlage`, `yale_access`, and so on.
    </ResponseField>

    <ResponseField name="display_name" type="String">
      Display name for the device provider type.
    </ResponseField>

    <ResponseField name="image_url" type="String">
      Image URL for the device provider.
    </ResponseField>

    <ResponseField name="provider_category" type="String">
      Provider category. Indicates the third-party provider type, such as `stable`, for stable integrations, or `internal`, for internal integrations.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="location" type="Object">
  Location information for the device.

  <Expandable title="properties">
    <ResponseField name="location_name" type="String">
      Name of the device location.
    </ResponseField>

    <ResponseField name="room_name" type="String">
      Name of the room within the device location, when the provider reports one.
    </ResponseField>

    <ResponseField name="time_zone" type="String">
      Time zone of the device location.
    </ResponseField>

    <ResponseField name="timezone" type="String">
      **Deprecated**. Use `time_zone` instead.

      Time zone of the device location.
    </ResponseField>
  </Expandable>
</ResponseField>

## Access Codes

<ResponseField name="offline_access_codes_enabled" type="Boolean">
  **Deprecated**. use device.can\_program\_offline\_access\_codes

  Indicates whether it is currently possible to use offline access codes for the device.
</ResponseField>

<ResponseField name="online_access_codes_enabled" type="Boolean">
  **Deprecated**. use device.can\_program\_online\_access\_codes

  Indicates whether it is currently possible to use online access codes for the device.
</ResponseField>

<ResponseField name="supports_accessory_keypad" type="Boolean">
  **Deprecated**. use device.properties.model.can\_connect\_accessory\_keypad

  The supports accessory keypad.
</ResponseField>

<ResponseField name="supports_offline_access_codes" type="Boolean">
  **Deprecated**. use offline\_access\_codes\_enabled

  The supports offline access codes.
</ResponseField>

<ResponseField name="backup_access_code_pool_enabled" type="Boolean">
  Indicates whether the [backup access code pool](/low-level-apis/smart-locks/access-codes/backup-access-codes) is currently enabled for the device. To disable it, set this to `false` using [/devices/update](/api/devices/update).
</ResponseField>

<ResponseField name="code_constraints" type="Array">
  Constraints on access codes for the device. Seam represents each constraint as an object with a `constraint_type` property. Depending on the constraint type, there may also be additional properties. Note that some constraints are manufacturer- or device-specific.

  <Expandable title="properties">
    <ResponseField name="constraint_type" type="Enum (String)">
      The constraint type.
    </ResponseField>

    <ResponseField name="max_length" type="number">
      Maximum name length constraint for access codes.
    </ResponseField>

    <ResponseField name="min_length" type="number">
      Minimum name length constraint for access codes.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="has_native_entry_events" type="Boolean">
  Indicates whether the device supports native entry events.
</ResponseField>

<ResponseField name="keypad_battery" type="Object">
  Keypad battery status.

  <Expandable title="properties">
    <ResponseField name="level" type="number">
      Keypad battery charge level.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="max_active_codes_supported" type="number">
  Maximum number of active access codes that the device supports.
</ResponseField>

<ResponseField name="offline_time_frame_options" type="Array">
  Time frames that may be requested when creating an offline access code, expressed as a list of options. The caller picks one option (by matching the requested duration when the options' duration ranges do not overlap, or by `display_name` when they do) and satisfies that one option's rules. When `undefined`, any time frame works.

  <Expandable title="properties">
    <ResponseField name="display_name" type="String">
      Label for this option. For a single-option device, the product name (for example, `algoPIN` or `SmartPIN`); for a multi-option device, a label that distinguishes it (for example, `Hourly` or `Fixed start times`).
    </ResponseField>

    <ResponseField name="end_date_recurrence_rule" type="String">
      iCalendar recurrence rule (RRULE) that the end date must fall on. Constrains which calendar dates are selectable, independent of the time-of-day rules.
    </ResponseField>

    <ResponseField name="matching_start_end_time" type="Boolean">
      When `true`, the start and end must fall at the same time of day (the caller picks which). Mutually exclusive with `time_pairs`.
    </ResponseField>

    <ResponseField name="max_duration" type="String">
      Maximum duration this option covers, as an ISO 8601 duration (for example, `PT672H` or `P367D`). Omitted when there is no maximum.
    </ResponseField>

    <ResponseField name="min_duration" type="String">
      Minimum duration this option covers, as an ISO 8601 duration (for example, `PT1H` or `P29D`). Omitted when there is no minimum.
    </ResponseField>

    <ResponseField name="start_date_recurrence_rule" type="String">
      iCalendar recurrence rule (RRULE) that the start date must fall on (for example, `FREQ=MONTHLY;BYDAY=1MO,3MO`). Constrains which calendar dates are selectable, independent of the time-of-day rules.
    </ResponseField>

    <ResponseField name="time_pairs" type="Array">
      Fixed start/end time pairings the caller chooses from. Mutually exclusive with `matching_start_end_time`.

      <Expandable title="properties">
        <ResponseField name="display_name" type="String">
          Label for the start/end time pairing.
        </ResponseField>

        <ResponseField name="end_time" type="String">
          End time of day as a 24-hour `HH:MM` value, interpreted in the option's `time_zone`. An `end_time` earlier on the clock than `start_time` means the end falls on a later date.
        </ResponseField>

        <ResponseField name="start_time" type="String">
          Start time of day as a 24-hour `HH:MM` value, interpreted in the option's `time_zone`.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="time_zone" type="String">
      IANA time zone for interpreting `time_pairs` and the date recurrence rules. Present only when the option fixes times or dates.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="online_time_frame_options" type="Array">
  Time frames that may be requested when creating an online access code, expressed as a list of options. The caller picks one option (by matching the requested duration when the options' duration ranges do not overlap, or by `display_name` when they do) and satisfies that one option's rules. When `undefined`, any time frame works.

  <Expandable title="properties">
    <ResponseField name="display_name" type="String">
      Label for this option. For a single-option device, the product name (for example, `algoPIN` or `SmartPIN`); for a multi-option device, a label that distinguishes it (for example, `Hourly` or `Fixed start times`).
    </ResponseField>

    <ResponseField name="end_date_recurrence_rule" type="String">
      iCalendar recurrence rule (RRULE) that the end date must fall on. Constrains which calendar dates are selectable, independent of the time-of-day rules.
    </ResponseField>

    <ResponseField name="matching_start_end_time" type="Boolean">
      When `true`, the start and end must fall at the same time of day (the caller picks which). Mutually exclusive with `time_pairs`.
    </ResponseField>

    <ResponseField name="max_duration" type="String">
      Maximum duration this option covers, as an ISO 8601 duration (for example, `PT672H` or `P367D`). Omitted when there is no maximum.
    </ResponseField>

    <ResponseField name="min_duration" type="String">
      Minimum duration this option covers, as an ISO 8601 duration (for example, `PT1H` or `P29D`). Omitted when there is no minimum.
    </ResponseField>

    <ResponseField name="start_date_recurrence_rule" type="String">
      iCalendar recurrence rule (RRULE) that the start date must fall on (for example, `FREQ=MONTHLY;BYDAY=1MO,3MO`). Constrains which calendar dates are selectable, independent of the time-of-day rules.
    </ResponseField>

    <ResponseField name="time_pairs" type="Array">
      Fixed start/end time pairings the caller chooses from. Mutually exclusive with `matching_start_end_time`.

      <Expandable title="properties">
        <ResponseField name="display_name" type="String">
          Label for the start/end time pairing.
        </ResponseField>

        <ResponseField name="end_time" type="String">
          End time of day as a 24-hour `HH:MM` value, interpreted in the option's `time_zone`. An `end_time` earlier on the clock than `start_time` means the end falls on a later date.
        </ResponseField>

        <ResponseField name="start_time" type="String">
          Start time of day as a 24-hour `HH:MM` value, interpreted in the option's `time_zone`.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="time_zone" type="String">
      IANA time zone for interpreting `time_pairs` and the date recurrence rules. Present only when the option fixes times or dates.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="supported_code_lengths" type="Array">
  Supported code lengths for access codes.
</ResponseField>

<ResponseField name="supports_backup_access_code_pool" type="Boolean">
  Indicates whether the device supports a [backup access code pool](/low-level-apis/smart-locks/access-codes/backup-access-codes).
</ResponseField>

## Hardware

<ResponseField name="accessory_keypad" type="Object">
  Accessory keypad properties and state.

  <Expandable title="properties">
    <ResponseField name="battery" type="Object">
      Keypad battery properties.

      <Expandable title="properties">
        <ResponseField name="level" type="number">
          The level.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="is_connected" type="Boolean">
      Indicates if an accessory keypad is connected to the device.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="appearance" type="Object">
  Appearance-related properties, as reported by the device.

  <Expandable title="properties">
    <ResponseField name="name" type="String">
      Name of the device as seen from the provider API and application, not settable through Seam.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="battery" type="Object">
  Represents the current status of the battery charge level.

  <Expandable title="properties">
    <ResponseField name="level" type="number">
      Battery charge level as a value between 0 and 1, inclusive.
    </ResponseField>

    <ResponseField name="status" type="Enum (String)">
      Represents the current status of the battery charge level. Values are `critical`, which indicates an extremely low level, suggesting imminent shutdown or an urgent need for charging; `low`, which signifies that the battery is under the preferred threshold and should be charged soon; `good`, which denotes a satisfactory charge level, adequate for normal use without the immediate need for recharging; and `full`, which represents a battery that is fully charged, providing the maximum duration of usage.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="battery_level" type="number">
  Indicates the battery level of the device as a decimal value between 0 and 1, inclusive.
</ResponseField>

<ResponseField name="has_direct_power" type="Boolean">
  Indicates whether the device has direct power.
</ResponseField>

<ResponseField name="image_alt_text" type="String">
  Alt text for the device image.
</ResponseField>

<ResponseField name="image_url" type="String">
  Image URL for the device.
</ResponseField>

<ResponseField name="manufacturer" type="String">
  Manufacturer of the device. When a device, such as a smart lock, is connected through a smart hub, the manufacturer of the device might be different from that of the smart hub.
</ResponseField>

<ResponseField name="serial_number" type="String">
  Serial number of the device.
</ResponseField>

## Locks

<ResponseField name="auto_lock_delay_seconds" type="number">
  The delay in seconds before the lock automatically locks after being unlocked.
</ResponseField>

<ResponseField name="auto_lock_enabled" type="Boolean">
  Indicates whether automatic locking is enabled.
</ResponseField>

<ResponseField name="door_open" type="Boolean">
  Indicates whether the door is open.
</ResponseField>

<ResponseField name="locked" type="Boolean">
  Indicates whether the lock is locked.
</ResponseField>

## Noise Sensors

<ResponseField name="currently_triggering_noise_threshold_ids" type="Array">
  Array of noise threshold IDs that are currently triggering.
</ResponseField>

<ResponseField name="noise_level_decibels" type="number">
  Indicates current noise level in decibels, if the device supports noise detection.
</ResponseField>

## Thermostats

<ResponseField name="active_thermostat_schedule" type="Object">
  **Deprecated**. Use `active_thermostat_schedule_id` with `/thermostats/schedules/get` instead.

  Active [thermostat schedule](/capability-guides/thermostats/creating-and-managing-thermostat-schedules).

  <Expandable title="properties">
    <ResponseField name="climate_preset_key" type="String">
      Key of the [climate preset](/capability-guides/thermostats/creating-and-managing-climate-presets) to use for the [thermostat schedule](/capability-guides/thermostats/creating-and-managing-thermostat-schedules).
    </ResponseField>

    <ResponseField name="created_at" type="String (ISO 8601)">
      Date and time at which the [thermostat schedule](/capability-guides/thermostats/creating-and-managing-thermostat-schedules) was created.
    </ResponseField>

    <ResponseField name="device_id" type="String (UUID)">
      ID of the desired [thermostat](/capability-guides/thermostats) device.
    </ResponseField>

    <ResponseField name="ends_at" type="String (ISO 8601)">
      Date and time at which the [thermostat schedule](/capability-guides/thermostats/creating-and-managing-thermostat-schedules) ends, in [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) format.
    </ResponseField>

    <ResponseField name="errors" type="Array">
      Errors associated with the [thermostat schedule](/capability-guides/thermostats/creating-and-managing-thermostat-schedules).

      <Expandable title="properties">
        <ResponseField name="created_at" type="String (ISO 8601)">
          Date and time at which Seam created the error.
        </ResponseField>

        <ResponseField name="error_code" type="String">
          Unique identifier of the type of error. Enables quick recognition and categorization of the issue.
        </ResponseField>

        <ResponseField name="message" type="String">
          Detailed description of the error. Provides insights into the issue and potentially how to rectify it.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="is_override_allowed" type="Boolean">
      Indicates whether a person at the thermostat can change the thermostat's settings after the [thermostat schedule](/capability-guides/thermostats/creating-and-managing-thermostat-schedules) starts.
    </ResponseField>

    <ResponseField name="max_override_period_minutes" type="number">
      Number of minutes for which a person at the thermostat can change the thermostat's settings after the activation of the scheduled [climate preset](/capability-guides/thermostats/creating-and-managing-climate-presets). See also [Specifying Manual Override Permissions](/capability-guides/thermostats/creating-and-managing-thermostat-schedules#specifying-manual-override-permissions).
    </ResponseField>

    <ResponseField name="name" type="String">
      User-friendly name to identify the [thermostat schedule](/capability-guides/thermostats/creating-and-managing-thermostat-schedules).
    </ResponseField>

    <ResponseField name="starts_at" type="String (ISO 8601)">
      Date and time at which the [thermostat schedule](/capability-guides/thermostats/creating-and-managing-thermostat-schedules) starts, in [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) format.
    </ResponseField>

    <ResponseField name="thermostat_schedule_id" type="String (UUID)">
      ID of the [thermostat schedule](/capability-guides/thermostats/creating-and-managing-thermostat-schedules).
    </ResponseField>

    <ResponseField name="workspace_id" type="String (UUID)">
      ID of the workspace that contains the thermostat schedule.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="active_thermostat_schedule_id" type="String (UUID)">
  ID of the active [thermostat schedule](/capability-guides/thermostats/creating-and-managing-thermostat-schedules).
</ResponseField>

<ResponseField name="available_climate_preset_modes" type="Array">
  Climate preset modes that the thermostat supports, such as "home", "away", "wake", "sleep", "occupied", and "unoccupied".
</ResponseField>

<ResponseField name="available_climate_presets" type="Array">
  Available [climate presets](/capability-guides/thermostats/creating-and-managing-climate-presets) for the thermostat.

  <Expandable title="properties">
    <ResponseField name="can_delete" type="Boolean">
      Indicates whether the [climate preset](/capability-guides/thermostats/creating-and-managing-climate-presets) key can be deleted.
    </ResponseField>

    <ResponseField name="can_edit" type="Boolean">
      Indicates whether the [climate preset](/capability-guides/thermostats/creating-and-managing-climate-presets) key can be edited.
    </ResponseField>

    <ResponseField name="can_use_with_thermostat_daily_programs" type="Boolean">
      Indicates whether the [climate preset](/capability-guides/thermostats/creating-and-managing-climate-presets) key can be programmed in a thermostat daily program.
    </ResponseField>

    <ResponseField name="climate_preset_key" type="String">
      Unique key to identify the [climate preset](/capability-guides/thermostats/creating-and-managing-climate-presets).
    </ResponseField>

    <ResponseField name="climate_preset_mode" type="Enum (String)">
      The climate preset mode for the thermostat, based on the available climate preset modes reported by the device.
    </ResponseField>

    <ResponseField name="cooling_set_point_celsius" type="number">
      Temperature to which the thermostat should cool (in °C). See also [Set Points](/capability-guides/thermostats/understanding-thermostat-concepts/set-points).
    </ResponseField>

    <ResponseField name="cooling_set_point_fahrenheit" type="number">
      Temperature to which the thermostat should cool (in °F). See also [Set Points](/capability-guides/thermostats/understanding-thermostat-concepts/set-points).
    </ResponseField>

    <ResponseField name="display_name" type="String">
      Display name for the [climate preset](/capability-guides/thermostats/creating-and-managing-climate-presets).
    </ResponseField>

    <ResponseField name="ecobee_metadata" type="Object">
      Metadata specific to the Ecobee climate, if applicable.

      <Expandable title="properties">
        <ResponseField name="climate_ref" type="String">
          Reference to the Ecobee climate, if applicable.
        </ResponseField>

        <ResponseField name="is_optimized" type="Boolean">
          Indicates if the climate preset is optimized by Ecobee.
        </ResponseField>

        <ResponseField name="owner" type="Enum (String)">
          Indicates whether the climate preset is owned by the user or the system.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="fan_mode_setting" type="Enum (String)">
      Desired [fan mode setting](/capability-guides/thermostats/configure-current-climate-settings#fan-mode-settings), such as `on`, `auto`, or `circulate`.
    </ResponseField>

    <ResponseField name="heating_set_point_celsius" type="number">
      Temperature to which the thermostat should heat (in °C). See also [Set Points](/capability-guides/thermostats/understanding-thermostat-concepts/set-points).
    </ResponseField>

    <ResponseField name="heating_set_point_fahrenheit" type="number">
      Temperature to which the thermostat should heat (in °F). See also [Set Points](/capability-guides/thermostats/understanding-thermostat-concepts/set-points).
    </ResponseField>

    <ResponseField name="hvac_mode_setting" type="Enum (String)">
      Desired [HVAC mode](/capability-guides/thermostats/understanding-thermostat-concepts/hvac-mode) setting, such as `heat`, `cool`, `heat_cool`, or `off`.
    </ResponseField>

    <ResponseField name="manual_override_allowed" type="Boolean">
      **Deprecated**. Use 'thermostat\_schedule.is\_override\_allowed'

      Indicates whether a person at the thermostat can change the thermostat's settings. See [Specifying Manual Override Permissions](/capability-guides/thermostats/creating-and-managing-thermostat-schedules#specifying-manual-override-permissions).
    </ResponseField>

    <ResponseField name="name" type="String">
      User-friendly name to identify the [climate preset](/capability-guides/thermostats/creating-and-managing-climate-presets).
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="available_fan_mode_settings" type="Array">
  Fan mode settings that the thermostat supports.
</ResponseField>

<ResponseField name="available_hvac_mode_settings" type="Array">
  HVAC mode settings that the thermostat supports.
</ResponseField>

<ResponseField name="current_climate_setting" type="Object">
  Current climate setting.

  <Expandable title="properties">
    <ResponseField name="can_delete" type="Boolean">
      Indicates whether the [climate preset](/capability-guides/thermostats/creating-and-managing-climate-presets) key can be deleted.
    </ResponseField>

    <ResponseField name="can_edit" type="Boolean">
      Indicates whether the [climate preset](/capability-guides/thermostats/creating-and-managing-climate-presets) key can be edited.
    </ResponseField>

    <ResponseField name="can_use_with_thermostat_daily_programs" type="Boolean">
      Indicates whether the [climate preset](/capability-guides/thermostats/creating-and-managing-climate-presets) key can be programmed in a thermostat daily program.
    </ResponseField>

    <ResponseField name="climate_preset_key" type="String">
      Unique key to identify the [climate preset](/capability-guides/thermostats/creating-and-managing-climate-presets).
    </ResponseField>

    <ResponseField name="climate_preset_mode" type="Enum (String)">
      The climate preset mode for the thermostat, based on the available climate preset modes reported by the device.
    </ResponseField>

    <ResponseField name="cooling_set_point_celsius" type="number">
      Temperature to which the thermostat should cool (in °C). See also [Set Points](/capability-guides/thermostats/understanding-thermostat-concepts/set-points).
    </ResponseField>

    <ResponseField name="cooling_set_point_fahrenheit" type="number">
      Temperature to which the thermostat should cool (in °F). See also [Set Points](/capability-guides/thermostats/understanding-thermostat-concepts/set-points).
    </ResponseField>

    <ResponseField name="display_name" type="String">
      Display name for the [climate preset](/capability-guides/thermostats/creating-and-managing-climate-presets).
    </ResponseField>

    <ResponseField name="ecobee_metadata" type="Object">
      Metadata specific to the Ecobee climate, if applicable.

      <Expandable title="properties">
        <ResponseField name="climate_ref" type="String">
          Reference to the Ecobee climate, if applicable.
        </ResponseField>

        <ResponseField name="is_optimized" type="Boolean">
          Indicates if the climate preset is optimized by Ecobee.
        </ResponseField>

        <ResponseField name="owner" type="Enum (String)">
          Indicates whether the climate preset is owned by the user or the system.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="fan_mode_setting" type="Enum (String)">
      Desired [fan mode setting](/capability-guides/thermostats/configure-current-climate-settings#fan-mode-settings), such as `on`, `auto`, or `circulate`.
    </ResponseField>

    <ResponseField name="heating_set_point_celsius" type="number">
      Temperature to which the thermostat should heat (in °C). See also [Set Points](/capability-guides/thermostats/understanding-thermostat-concepts/set-points).
    </ResponseField>

    <ResponseField name="heating_set_point_fahrenheit" type="number">
      Temperature to which the thermostat should heat (in °F). See also [Set Points](/capability-guides/thermostats/understanding-thermostat-concepts/set-points).
    </ResponseField>

    <ResponseField name="hvac_mode_setting" type="Enum (String)">
      Desired [HVAC mode](/capability-guides/thermostats/understanding-thermostat-concepts/hvac-mode) setting, such as `heat`, `cool`, `heat_cool`, or `off`.
    </ResponseField>

    <ResponseField name="manual_override_allowed" type="Boolean">
      **Deprecated**. Use 'thermostat\_schedule.is\_override\_allowed'

      Indicates whether a person at the thermostat can change the thermostat's settings. See [Specifying Manual Override Permissions](/capability-guides/thermostats/creating-and-managing-thermostat-schedules#specifying-manual-override-permissions).
    </ResponseField>

    <ResponseField name="name" type="String">
      User-friendly name to identify the [climate preset](/capability-guides/thermostats/creating-and-managing-climate-presets).
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="default_climate_setting" type="Object">
  **Deprecated**. use fallback\_climate\_preset\_key to specify a fallback climate preset instead.

  The default climate setting.

  <Expandable title="properties">
    <ResponseField name="can_delete" type="Boolean">
      Indicates whether the [climate preset](/capability-guides/thermostats/creating-and-managing-climate-presets) key can be deleted.
    </ResponseField>

    <ResponseField name="can_edit" type="Boolean">
      Indicates whether the [climate preset](/capability-guides/thermostats/creating-and-managing-climate-presets) key can be edited.
    </ResponseField>

    <ResponseField name="can_use_with_thermostat_daily_programs" type="Boolean">
      Indicates whether the [climate preset](/capability-guides/thermostats/creating-and-managing-climate-presets) key can be programmed in a thermostat daily program.
    </ResponseField>

    <ResponseField name="climate_preset_key" type="String">
      Unique key to identify the [climate preset](/capability-guides/thermostats/creating-and-managing-climate-presets).
    </ResponseField>

    <ResponseField name="climate_preset_mode" type="Enum (String)">
      The climate preset mode for the thermostat, based on the available climate preset modes reported by the device.
    </ResponseField>

    <ResponseField name="cooling_set_point_celsius" type="number">
      Temperature to which the thermostat should cool (in °C). See also [Set Points](/capability-guides/thermostats/understanding-thermostat-concepts/set-points).
    </ResponseField>

    <ResponseField name="cooling_set_point_fahrenheit" type="number">
      Temperature to which the thermostat should cool (in °F). See also [Set Points](/capability-guides/thermostats/understanding-thermostat-concepts/set-points).
    </ResponseField>

    <ResponseField name="display_name" type="String">
      Display name for the [climate preset](/capability-guides/thermostats/creating-and-managing-climate-presets).
    </ResponseField>

    <ResponseField name="ecobee_metadata" type="Object">
      Metadata specific to the Ecobee climate, if applicable.

      <Expandable title="properties">
        <ResponseField name="climate_ref" type="String">
          Reference to the Ecobee climate, if applicable.
        </ResponseField>

        <ResponseField name="is_optimized" type="Boolean">
          Indicates if the climate preset is optimized by Ecobee.
        </ResponseField>

        <ResponseField name="owner" type="Enum (String)">
          Indicates whether the climate preset is owned by the user or the system.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="fan_mode_setting" type="Enum (String)">
      Desired [fan mode setting](/capability-guides/thermostats/configure-current-climate-settings#fan-mode-settings), such as `on`, `auto`, or `circulate`.
    </ResponseField>

    <ResponseField name="heating_set_point_celsius" type="number">
      Temperature to which the thermostat should heat (in °C). See also [Set Points](/capability-guides/thermostats/understanding-thermostat-concepts/set-points).
    </ResponseField>

    <ResponseField name="heating_set_point_fahrenheit" type="number">
      Temperature to which the thermostat should heat (in °F). See also [Set Points](/capability-guides/thermostats/understanding-thermostat-concepts/set-points).
    </ResponseField>

    <ResponseField name="hvac_mode_setting" type="Enum (String)">
      Desired [HVAC mode](/capability-guides/thermostats/understanding-thermostat-concepts/hvac-mode) setting, such as `heat`, `cool`, `heat_cool`, or `off`.
    </ResponseField>

    <ResponseField name="manual_override_allowed" type="Boolean">
      **Deprecated**. Use 'thermostat\_schedule.is\_override\_allowed'

      Indicates whether a person at the thermostat can change the thermostat's settings. See [Specifying Manual Override Permissions](/capability-guides/thermostats/creating-and-managing-thermostat-schedules#specifying-manual-override-permissions).
    </ResponseField>

    <ResponseField name="name" type="String">
      User-friendly name to identify the [climate preset](/capability-guides/thermostats/creating-and-managing-climate-presets).
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="fallback_climate_preset_key" type="String">
  Key of the [fallback climate preset](/capability-guides/thermostats/creating-and-managing-climate-presets/setting-the-fallback-climate-preset) for the thermostat.
</ResponseField>

<ResponseField name="fan_mode_setting" type="Enum (String)">
  **Deprecated**. Use `current_climate_setting.fan_mode_setting` instead.

  The fan mode setting.
</ResponseField>

<ResponseField name="is_cooling" type="Boolean">
  Indicates whether the connected HVAC system is currently cooling, as reported by the thermostat.
</ResponseField>

<ResponseField name="is_fan_running" type="Boolean">
  Indicates whether the fan in the connected HVAC system is currently running, as reported by the thermostat.
</ResponseField>

<ResponseField name="is_heating" type="Boolean">
  Indicates whether the connected HVAC system is currently heating, as reported by the thermostat.
</ResponseField>

<ResponseField name="is_temporary_manual_override_active" type="Boolean">
  Indicates whether the current thermostat settings differ from the most recent active program or schedule that Seam activated. For this condition to occur, `current_climate_setting.manual_override_allowed` must also be `true`.
</ResponseField>

<ResponseField name="max_cooling_set_point_celsius" type="number">
  Maximum [cooling set point](/capability-guides/thermostats/understanding-thermostat-concepts/set-points#cooling-set-point) in °C.
</ResponseField>

<ResponseField name="max_cooling_set_point_fahrenheit" type="number">
  Maximum [cooling set point](/capability-guides/thermostats/understanding-thermostat-concepts/set-points#cooling-set-point) in °F.
</ResponseField>

<ResponseField name="max_heating_set_point_celsius" type="number">
  Maximum [heating set point](/capability-guides/thermostats/understanding-thermostat-concepts/set-points#heating-set-point) in °C.
</ResponseField>

<ResponseField name="max_heating_set_point_fahrenheit" type="number">
  Maximum [heating set point](/capability-guides/thermostats/understanding-thermostat-concepts/set-points#heating-set-point) in °F.
</ResponseField>

<ResponseField name="max_thermostat_daily_program_periods_per_day" type="number">
  Maximum number of periods that the thermostat can support per day. For example, if the thermostat supports 4 periods per day, this value is 4.
</ResponseField>

<ResponseField name="max_unique_climate_presets_per_thermostat_weekly_program" type="number">
  Maximum number of climate presets that the thermostat can support for weekly programming.
</ResponseField>

<ResponseField name="min_cooling_set_point_celsius" type="number">
  Minimum [cooling set point](/capability-guides/thermostats/understanding-thermostat-concepts/set-points#cooling-set-point) in °C.
</ResponseField>

<ResponseField name="min_cooling_set_point_fahrenheit" type="number">
  Minimum [cooling set point](/capability-guides/thermostats/understanding-thermostat-concepts/set-points#cooling-set-point) in °F.
</ResponseField>

<ResponseField name="min_heating_cooling_delta_celsius" type="number">
  Minimum [temperature difference](/capability-guides/thermostats/understanding-thermostat-concepts/set-points#minimum-heating-cooling-temperature-delta) in °C between the cooling and heating set points when in heat-cool (auto) mode.
</ResponseField>

<ResponseField name="min_heating_cooling_delta_fahrenheit" type="number">
  Minimum [temperature difference](/capability-guides/thermostats/understanding-thermostat-concepts/set-points#minimum-heating-cooling-temperature-delta) in °F between the cooling and heating set points when in heat-cool (auto) mode.
</ResponseField>

<ResponseField name="min_heating_set_point_celsius" type="number">
  Minimum [heating set point](/capability-guides/thermostats/understanding-thermostat-concepts/set-points#heating-set-point) in °C.
</ResponseField>

<ResponseField name="min_heating_set_point_fahrenheit" type="number">
  Minimum [heating set point](/capability-guides/thermostats/understanding-thermostat-concepts/set-points#heating-set-point) in °F.
</ResponseField>

<ResponseField name="relative_humidity" type="number">
  Reported relative humidity, as a value between 0 and 1, inclusive.
</ResponseField>

<ResponseField name="temperature_celsius" type="number">
  Reported temperature in °C.
</ResponseField>

<ResponseField name="temperature_fahrenheit" type="number">
  Reported temperature in °F.
</ResponseField>

<ResponseField name="temperature_threshold" type="Object">
  Current [temperature threshold](/capability-guides/thermostats/setting-and-monitoring-temperature-thresholds) set for the thermostat.

  <Expandable title="properties">
    <ResponseField name="lower_limit_celsius" type="number">
      Lower limit in °C within the current [temperature threshold](/capability-guides/thermostats/setting-and-monitoring-temperature-thresholds) set for the thermostat.
    </ResponseField>

    <ResponseField name="lower_limit_fahrenheit" type="number">
      Lower limit in °F within the current [temperature threshold](/capability-guides/thermostats/setting-and-monitoring-temperature-thresholds) set for the thermostat.
    </ResponseField>

    <ResponseField name="upper_limit_celsius" type="number">
      Upper limit in °C within the current [temperature threshold](/capability-guides/thermostats/setting-and-monitoring-temperature-thresholds) set for the thermostat.
    </ResponseField>

    <ResponseField name="upper_limit_fahrenheit" type="number">
      Upper limit in °F within the current [temperature threshold](/capability-guides/thermostats/setting-and-monitoring-temperature-thresholds) set for the thermostat.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="thermostat_daily_program_period_precision_minutes" type="number">
  Precision of the thermostat's period in minutes. For example, if the thermostat supports 15-minute periods, this value is 15. All values are relative to the top of the hour, so for 15 minutes, the periods would be 0, 15, 30, and 45 minutes past the hour.
</ResponseField>

<ResponseField name="thermostat_daily_programs" type="Array">
  Configured [daily programs](/capability-guides/thermostats/creating-and-managing-thermostat-programs) for the thermostat.

  <Expandable title="properties">
    <ResponseField name="created_at" type="String (ISO 8601)">
      Date and time at which the thermostat daily program was created.
    </ResponseField>

    <ResponseField name="device_id" type="String (UUID)">
      ID of the thermostat device on which the thermostat daily program is configured.
    </ResponseField>

    <ResponseField name="name" type="String">
      User-friendly name to identify the thermostat daily program.
    </ResponseField>

    <ResponseField name="periods" type="Array">
      Array of thermostat daily program periods.

      <Expandable title="properties">
        <ResponseField name="climate_preset_key" type="String">
          Key of the [climate preset](/capability-guides/thermostats/creating-and-managing-climate-presets) to activate at the `starts_at_time`.
        </ResponseField>

        <ResponseField name="starts_at_time" type="String">
          Time at which the thermostat daily program period starts, in [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) format.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="thermostat_daily_program_id" type="String (UUID)">
      ID of the thermostat daily program.
    </ResponseField>

    <ResponseField name="workspace_id" type="String (UUID)">
      ID of the workspace that contains the thermostat daily program.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="thermostat_weekly_program" type="Object">
  Current [weekly program](/capability-guides/thermostats/creating-and-managing-thermostat-programs) for the thermostat.

  <Expandable title="properties">
    <ResponseField name="created_at" type="String (ISO 8601)">
      Date and time at which the thermostat weekly program was created.
    </ResponseField>

    <ResponseField name="friday_program_id" type="String (UUID)">
      ID of the thermostat daily program to run on Fridays.
    </ResponseField>

    <ResponseField name="monday_program_id" type="String (UUID)">
      ID of the thermostat daily program to run on Mondays.
    </ResponseField>

    <ResponseField name="saturday_program_id" type="String (UUID)">
      ID of the thermostat daily program to run on Saturdays.
    </ResponseField>

    <ResponseField name="sunday_program_id" type="String (UUID)">
      ID of the thermostat daily program to run on Sundays.
    </ResponseField>

    <ResponseField name="thursday_program_id" type="String (UUID)">
      ID of the thermostat daily program to run on Thursdays.
    </ResponseField>

    <ResponseField name="tuesday_program_id" type="String (UUID)">
      ID of the thermostat daily program to run on Tuesdays.
    </ResponseField>

    <ResponseField name="wednesday_program_id" type="String (UUID)">
      ID of the thermostat daily program to run on Wednesdays.
    </ResponseField>
  </Expandable>
</ResponseField>

## The device\_provider Object

<ResponseExample>
  ```json Device Provider theme={null}
  {
    "can_program_online_access_codes": true,
    "can_remotely_unlock": true,
    "device_provider_name": "akiles",
    "display_name": "Akiles",
    "image_url": "https://connect.getseam.com/_next/image?url=https://connect.getseam.com/assets/images/logos/akiles.png&q=75&w=128",
    "space_ids": [],
    "provider_categories": [
      "stable",
      "consumer_smartlocks"
    ]
  }
  ```
</ResponseExample>

***

## Properties

<ResponseField name="can_configure_auto_lock" type="Boolean">
  Indicates whether the lock supports configuring automatic locking.
</ResponseField>

<ResponseField name="can_hvac_cool" type="Boolean">
  Indicates whether the thermostat supports cooling.
</ResponseField>

<ResponseField name="can_hvac_heat" type="Boolean">
  Indicates whether the thermostat supports heating.
</ResponseField>

<ResponseField name="can_hvac_heat_cool" type="Boolean">
  Indicates whether the thermostat supports simultaneous heating and cooling.
</ResponseField>

<ResponseField name="can_program_offline_access_codes" type="Boolean">
  Indicates whether the device supports programming offline access codes.
</ResponseField>

<ResponseField name="can_program_online_access_codes" type="Boolean">
  Indicates whether the device supports programming online access codes.
</ResponseField>

<ResponseField name="can_program_thermostat_programs_as_different_each_day" type="Boolean">
  Indicates whether the thermostat supports different climate programs for each day of the week.
</ResponseField>

<ResponseField name="can_program_thermostat_programs_as_same_each_day" type="Boolean">
  Indicates whether the thermostat supports a single climate program applied to every day.
</ResponseField>

<ResponseField name="can_program_thermostat_programs_as_weekday_weekend" type="Boolean">
  Indicates whether the thermostat supports weekday/weekend climate programs.
</ResponseField>

<ResponseField name="can_remotely_lock" type="Boolean">
  Indicates whether the device supports remote locking.
</ResponseField>

<ResponseField name="can_remotely_unlock" type="Boolean">
  Indicates whether the device supports remote unlocking.
</ResponseField>

<ResponseField name="can_run_thermostat_programs" type="Boolean">
  Indicates whether the thermostat supports running climate programs.
</ResponseField>

<ResponseField name="can_simulate_connection" type="Boolean">
  Indicates whether the device supports simulating connection in a sandbox.
</ResponseField>

<ResponseField name="can_simulate_disconnection" type="Boolean">
  Indicates whether the device supports simulating disconnection in a sandbox.
</ResponseField>

<ResponseField name="can_simulate_hub_connection" type="Boolean">
  Indicates whether the hub supports simulating connection in a sandbox.
</ResponseField>

<ResponseField name="can_simulate_hub_disconnection" type="Boolean">
  Indicates whether the hub supports simulating disconnection in a sandbox.
</ResponseField>

<ResponseField name="can_simulate_paid_subscription" type="Boolean">
  Indicates whether the device supports simulating a paid subscription in a sandbox.
</ResponseField>

<ResponseField name="can_simulate_removal" type="Boolean">
  Indicates whether the device supports simulating removal in a sandbox.
</ResponseField>

<ResponseField name="can_turn_off_hvac" type="Boolean">
  Indicates whether the thermostat can be turned off.
</ResponseField>

<ResponseField name="can_unlock_with_code" type="Boolean">
  Indicates whether the lock supports unlocking with an access code.
</ResponseField>

<ResponseField name="device_provider_name" type="Enum (String)">
  Name of the device provider.
</ResponseField>

<ResponseField name="display_name" type="String">
  Display name for the device provider.
</ResponseField>

<ResponseField name="image_url" type="String">
  Image URL for the device provider.
</ResponseField>

<ResponseField name="provider_categories" type="Array">
  List of provider categories to which the device provider belongs, such as `stable`, `consumer_smartlocks`, `thermostats`, and so on.
</ResponseField>


# Report Provider Metadata
Source: https://docs.seam.co/api/devices/report_provider_metadata

/openapi.json post /devices/report_provider_metadata
Updates provider-specific metadata for devices.



# Simulate Device Connection
Source: https://docs.seam.co/api/devices/simulate/connect

/openapi.json post /devices/simulate/connect
Simulates connecting a device to Seam. Only applicable for [sandbox devices](/core-concepts/workspaces#sandbox-workspaces). See also [Testing Your App Against Device Disconnection and Removal](/core-concepts/devices/testing-your-app-against-device-disconnection-and-removal).



# Simulate Hub Connection
Source: https://docs.seam.co/api/devices/simulate/connect_to_hub

/openapi.json post /devices/simulate/connect_to_hub
Simulates bringing the Wi‑Fi hub (bridge) back online for a device.
Only applicable for sandbox workspaces and currently
implemented for August and TTLock locks.
This will clear the `hub_disconnected` error on the device.



# Simulate Device Disconnection
Source: https://docs.seam.co/api/devices/simulate/disconnect

/openapi.json post /devices/simulate/disconnect
Simulates disconnecting a device from Seam. Only applicable for [sandbox devices](/core-concepts/workspaces#sandbox-workspaces). See also [Testing Your App Against Device Disconnection and Removal](/core-concepts/devices/testing-your-app-against-device-disconnection-and-removal).



# Simulate Hub Disconnection
Source: https://docs.seam.co/api/devices/simulate/disconnect_from_hub

/openapi.json post /devices/simulate/disconnect_from_hub
Simulates taking the Wi‑Fi hub (bridge) offline for a device.
Only applicable for sandbox workspaces and currently
implemented for August, TTLock, and IglooHome devices.
This will set the `hub_disconnected` error on the device, or mark the
IglooHome bridge offline in sandbox.



# Device Simulations
Source: https://docs.seam.co/api/devices/simulate/object

Use the device simulation endpoints to connect, disconnect, and remove sandbox devices so you can test how your app handles device state changes.

## Endpoints

[**`/devices/simulate/connect`**](./connect)

Simulates connecting a device to Seam. Only applicable for [sandbox devices](/core-concepts/workspaces#sandbox-workspaces). See also [Testing Your App Against Device Disconnection and Removal](/core-concepts/devices/testing-your-app-against-device-disconnection-and-removal).

[**`/devices/simulate/connect_to_hub`**](./connect_to_hub)

Simulates bringing the Wi‑Fi hub (bridge) back online for a device.
Only applicable for sandbox workspaces and currently
implemented for August and TTLock locks.
This will clear the `hub_disconnected` error on the device.

[**`/devices/simulate/disconnect`**](./disconnect)

Simulates disconnecting a device from Seam. Only applicable for [sandbox devices](/core-concepts/workspaces#sandbox-workspaces). See also [Testing Your App Against Device Disconnection and Removal](/core-concepts/devices/testing-your-app-against-device-disconnection-and-removal).

[**`/devices/simulate/disconnect_from_hub`**](./disconnect_from_hub)

Simulates taking the Wi‑Fi hub (bridge) offline for a device.
Only applicable for sandbox workspaces and currently
implemented for August, TTLock, and IglooHome devices.
This will set the `hub_disconnected` error on the device, or mark the
IglooHome bridge offline in sandbox.

[**`/devices/simulate/paid_subscription`**](./paid_subscription)

Toggle the simulated Nuki Smart Hosting subscription for a device (sandbox only).
Send `is_expired: true` to simulate an expired subscription, or `false` to simulate an active subscription.
The actual device error is created/cleared by the poller after this state change.

[**`/devices/simulate/remove`**](./remove)

Simulates removing a device from Seam. Only applicable for [sandbox devices](/core-concepts/workspaces#sandbox-workspaces). See also [Testing Your App Against Device Disconnection and Removal](/core-concepts/devices/testing-your-app-against-device-disconnection-and-removal).


# Simulate Paid Subscription
Source: https://docs.seam.co/api/devices/simulate/paid_subscription

/openapi.json post /devices/simulate/paid_subscription
Toggle the simulated Nuki Smart Hosting subscription for a device (sandbox only).
Send `is_expired: true` to simulate an expired subscription, or `false` to simulate an active subscription.
The actual device error is created/cleared by the poller after this state change.



# Simulate Device Removal
Source: https://docs.seam.co/api/devices/simulate/remove

/openapi.json post /devices/simulate/remove
Simulates removing a device from Seam. Only applicable for [sandbox devices](/core-concepts/workspaces#sandbox-workspaces). See also [Testing Your App Against Device Disconnection and Removal](/core-concepts/devices/testing-your-app-against-device-disconnection-and-removal).



# Unmanaged Devices Errors and Warnings
Source: https://docs.seam.co/api/devices/unmanaged/errors

Errors and warnings that Seam reports on the Unmanaged Devices resource, each with its code and meaning.

## Errors

Each error is an object with the following shape:

```json Example error theme={null}
{
  "error_code": "account_disconnected",
  "message": "Indicates that the account is disconnected.",
  "created_at": "2025-01-01T00:00:00.000Z",
  "is_connected_account_error": true,
  "is_device_error": true
}
```

<Accordion title="Error object properties">
  <ResponseField name="error_code" type="Enum (String)">
    Unique identifier of the type of error. Enables quick recognition and categorization of the issue.

    One of the error codes listed below.
  </ResponseField>

  <ResponseField name="message" type="String">
    Detailed description of the error. Provides insights into the issue and potentially how to rectify it.
  </ResponseField>

  <ResponseField name="created_at" type="String (ISO 8601)">
    Date and time at which Seam created the error.
  </ResponseField>

  <ResponseField name="is_bridge_error" type="Boolean">
    Indicates whether the error is related to [Seam Bridge](/capability-guides/seam-bridge).
  </ResponseField>

  <ResponseField name="is_connected_account_error" type="Boolean">
    Indicates that the error is a [connected account](/api/connected_accounts/object) error.
  </ResponseField>

  <ResponseField name="is_device_error" type="Boolean">
    Indicates that the error is not a device error.
  </ResponseField>
</Accordion>

### `device_disconnected`

Indicates that the device is disconnected.

***

### `device_offline`

Indicates that the device is offline.

***

### `device_removed`

Indicates that the device has been removed.

***

### `hub_disconnected`

Indicates that the hub is disconnected.

***

### `missing_device_credentials`

Indicates that device credentials are missing.

***

### `subscription_required`

Indicates that a subscription is required to connect.

***

### Access Codes

#### `empty_backup_access_code_pool`

Indicates that the [backup access code pool](/low-level-apis/smart-locks/access-codes/backup-access-codes) is empty.

***

### Locks

#### `august_lock_not_authorized`

Indicates that the user is not authorized to use the August lock.

***

### Thermostats

#### `auxiliary_heat_running`

Indicates that the auxiliary heat is running.

***

### Connected Account

<Note>
  These errors are inherited from the [Connected Account](/api/connected_accounts/errors) resource. When they are set on the parent connected account, they are propagated to this resource's errors list.
</Note>

#### `account_disconnected`

Indicates that the account is disconnected.

***

#### `bridge_disconnected`

Indicates that the Seam API cannot communicate with [Seam Bridge](/capability-guides/seam-bridge), for example, if the Seam Bridge executable has stopped or if the computer running the Seam Bridge executable is offline. See also [Troubleshooting Your Access Control System](/low-level-apis/access-systems/troubleshooting-your-access-control-system#acs_system-errors-seam_bridge_disconnected).

***

#### `dormakaba_sites_disconnected`

Indicates that one or more dormakaba sites associated with the connected account could not be connected. Contact dormakaba support.

***

#### `insufficient_permissions`

Indicates that Seam's integration user does not have sufficient permissions on the provider's system to which this device belongs, so Seam cannot manage access codes or unlock the device. See the error message for specifics, then either reauthorize the connected account in Seam or grant the integration user the required permissions in the provider's system.

***

#### `salto_ks_subscription_limit_exceeded`

Indicates that the Salto site user limit has been reached.

***

## Warnings

Each warning is an object with the following shape:

```json Example warning theme={null}
{
  "warning_code": "partial_backup_access_code_pool",
  "message": "Indicates that the backup access code is unhealthy.",
  "created_at": "2025-01-01T00:00:00.000Z"
}
```

<Accordion title="Warning object properties">
  <ResponseField name="warning_code" type="Enum (String)">
    Unique identifier of the type of warning. Enables quick recognition and categorization of the issue.

    One of the warning codes listed below.
  </ResponseField>

  <ResponseField name="message" type="String">
    Detailed description of the warning. Provides insights into the issue and potentially how to rectify it.
  </ResponseField>

  <ResponseField name="created_at" type="String (ISO 8601)">
    Date and time at which Seam created the warning.
  </ResponseField>

  <ResponseField name="active_access_code_count" type="number">
    Number of active access codes on the device when the warning was set.
  </ResponseField>

  <ResponseField name="max_active_access_code_count" type="number">
    Maximum number of active access codes supported by the device.
  </ResponseField>
</Accordion>

### `device_communication_degraded`

Indicates that the device appears to be unresponsive.

***

### `device_has_flaky_connection`

Indicates that the device has a flaky connection.

***

### `scheduled_maintenance_window`

Indicates that a scheduled maintenance window has been detected.

***

### `third_party_integration_detected`

Indicates that a third-party integration has been detected.

***

### Access Codes

#### `many_active_backup_codes`

Indicates that there are too many backup codes.

***

#### `max_access_codes_reached`

Indicates that the device has reached its maximum number of active access codes. Delete existing codes before creating new ones.

***

#### `partial_backup_access_code_pool`

Indicates that the backup access code is unhealthy.

***

#### `privacy_mode`

Indicates that the lock is in Privacy Mode. Access codes and remote unlock are blocked until Privacy Mode is disabled.

***

#### `provider_issue`

Indicates a provider-specific issue that may affect device functionality.

***

#### `salto_ks_lock_access_code_support_removed`

Indicates that a change in the reported device model has been detected for this Salto KS lock, which may occur after an IQ hub reset. Access code support may be affected. See [https://help.getseam.com/articles/5098842588-salto-ks-lock-loses-access-code-support](https://help.getseam.com/articles/5098842588-salto-ks-lock-loses-access-code-support) for troubleshooting steps.

***

#### `salto_ks_office_mode`

Indicates that the Salto KS lock is in Office Mode. Access Codes will not unlock doors.

***

#### `salto_ks_privacy_mode`

Indicates that the Salto KS lock is in Privacy Mode. Access Codes will not unlock doors.

***

### Locks

#### `accessory_keypad_setup_required`

Indicates that the accessory keypad exists, but is not linked to the Igloohome Bridge. Online access code programming will fail until the keypad is linked to the Igloohome Bridge in the Igloohome app.

***

#### `hub_required_for_additional_capabilities`

Indicates that a hub or relay must be connected to unlock additional capabilities such as remote unlock.

***

#### `keynest_unsupported_locker`

Indicates that the key is in a locker that does not support the access codes API.

***

#### `lockly_time_zone_not_configured`

Indicates that Seam detected that the Lockly device does not have a time zone configured. Time-bound codes may not work as expected.

***

#### `power_saving_mode`

Indicates that the device is in power saving mode and may have limited functionality.

***

#### `salto_ks_subscription_limit_almost_reached`

Indicates that the Salto KS site has exceeded 80% of the maximum number of allowed users. Increase your subscription limit or delete some users from your site.

***

#### `time_zone_mismatch`

Indicates that the device's configured time zone does not match its hardware UTC offset. Time-bound access codes may activate at the wrong local time.

***

#### `time_zone_unknown`

Indicates that Seam does not know the device's time zone. Set a time zone to enable time-bound access codes.

***

#### `ttlock_lock_gateway_unlocking_not_enabled`

Indicates that the Remote Unlock feature is not enabled in the settings."

***

#### `ttlock_weak_gateway_signal`

Indicates that the gateway signal is weak.

***

#### `two_n_device_missing_timezone`

Indicates that the 2N device does not have a time zone configured. Configure a time zone on the device to enable access codes.

***

#### `ultraloq_time_zone_unknown`

Indicates that Seam does not know the time zone of the Ultraloq device. Set a time zone to enable time-bound access codes.

***

#### `unreliable_online_status`

Indicates that the device may optimistically be reported as online because the provider does not reliably report its online status.

***

### Phones

#### `unknown_issue_with_phone`

Indicates that an unknown issue occurred while syncing the state of the phone with the provider. This issue may affect the proper functioning of the phone.

***

### Thermostats

#### `temperature_threshold_exceeded`

Indicates that the temperature threshold has been exceeded.

***


# Unmanaged Devices Events
Source: https://docs.seam.co/api/devices/unmanaged/events

Webhook events that Seam emits for the Unmanaged Devices resource, with example payloads and properties.

## `device.unmanaged.converted_to_managed`

An [unmanaged device](/core-concepts/devices/managed-and-unmanaged-devices) was successfully converted to a managed device.

<ResponseExample>
  ```json Example webhook payload theme={null}
  {
    "connected_account_custom_metadata": {},
    "connected_account_id": "00000000-0000-0000-0000-000000000000",
    "created_at": "2025-01-01T00:00:00.000Z",
    "customer_key": "",
    "device_custom_metadata": {},
    "device_id": "00000000-0000-0000-0000-000000000000",
    "event_description": "An [unmanaged device](/core-concepts/devices/managed-and-unmanaged-devices) was successfully converted to a managed device.",
    "event_id": "00000000-0000-0000-0000-000000000000",
    "event_type": "device.unmanaged.converted_to_managed",
    "occurred_at": "2025-01-01T00:00:00.000Z",
    "workspace_id": "00000000-0000-0000-0000-000000000000"
  }
  ```
</ResponseExample>

<Accordion title="Properties">
  <ResponseField name="connected_account_custom_metadata" type="Object">
    Custom metadata of the connected account, present when connected\_account\_id is provided.
  </ResponseField>

  <ResponseField name="connected_account_id" type="String (UUID)">
    ID of the connected account associated with the event.
  </ResponseField>

  <ResponseField name="created_at" type="String (ISO 8601)">
    Date and time at which the event was created.
  </ResponseField>

  <ResponseField name="customer_key" type="String">
    The customer key associated with the device, if any.
  </ResponseField>

  <ResponseField name="device_custom_metadata" type="Object">
    Custom metadata of the device, present when device\_id is provided.
  </ResponseField>

  <ResponseField name="device_id" type="String (UUID)">
    ID of the affected device.
  </ResponseField>

  <ResponseField name="event_description" type="String">
    Human-readable description of the event. Persisted when the event is created (so the creating code, including a provider, can supply a tailored description) and otherwise derived from the event.
  </ResponseField>

  <ResponseField name="event_id" type="String (UUID)">
    ID of the event.
  </ResponseField>

  <ResponseField name="event_type" type="Enum (String)">
    Value: `device.unmanaged.converted_to_managed`
  </ResponseField>

  <ResponseField name="occurred_at" type="String (ISO 8601)">
    Date and time at which the event occurred.
  </ResponseField>

  <ResponseField name="workspace_id" type="String (UUID)">
    ID of the workspace associated with the event.
  </ResponseField>
</Accordion>

## `device.unmanaged.connected`

The status of an [unmanaged device](/core-concepts/devices/managed-and-unmanaged-devices) changed from offline to online. That is, the `device.properties.online` property changed from `false` to `true`.

<ResponseExample>
  ```json Example webhook payload theme={null}
  {
    "connected_account_custom_metadata": {},
    "connected_account_id": "00000000-0000-0000-0000-000000000000",
    "created_at": "2025-01-01T00:00:00.000Z",
    "customer_key": "",
    "device_custom_metadata": {},
    "device_id": "00000000-0000-0000-0000-000000000000",
    "event_description": "The status of an [unmanaged device](/core-concepts/devices/managed-and-unmanaged-devices) changed from offline to online. That is, the `device.properties.online` property changed from `false` to `true`.",
    "event_id": "00000000-0000-0000-0000-000000000000",
    "event_type": "device.unmanaged.connected",
    "occurred_at": "2025-01-01T00:00:00.000Z",
    "workspace_id": "00000000-0000-0000-0000-000000000000"
  }
  ```
</ResponseExample>

<Accordion title="Properties">
  <ResponseField name="connected_account_custom_metadata" type="Object">
    Custom metadata of the connected account, present when connected\_account\_id is provided.
  </ResponseField>

  <ResponseField name="connected_account_id" type="String (UUID)">
    ID of the connected account associated with the event.
  </ResponseField>

  <ResponseField name="created_at" type="String (ISO 8601)">
    Date and time at which the event was created.
  </ResponseField>

  <ResponseField name="customer_key" type="String">
    The customer key associated with the device, if any.
  </ResponseField>

  <ResponseField name="device_custom_metadata" type="Object">
    Custom metadata of the device, present when device\_id is provided.
  </ResponseField>

  <ResponseField name="device_id" type="String (UUID)">
    ID of the affected device.
  </ResponseField>

  <ResponseField name="event_description" type="String">
    Human-readable description of the event. Persisted when the event is created (so the creating code, including a provider, can supply a tailored description) and otherwise derived from the event.
  </ResponseField>

  <ResponseField name="event_id" type="String (UUID)">
    ID of the event.
  </ResponseField>

  <ResponseField name="event_type" type="Enum (String)">
    Value: `device.unmanaged.connected`
  </ResponseField>

  <ResponseField name="occurred_at" type="String (ISO 8601)">
    Date and time at which the event occurred.
  </ResponseField>

  <ResponseField name="workspace_id" type="String (UUID)">
    ID of the workspace associated with the event.
  </ResponseField>
</Accordion>

## `device.unmanaged.disconnected`

The status of an [unmanaged device](/core-concepts/devices/managed-and-unmanaged-devices) changed from online to offline. That is, the `device.properties.online` property changed from `true` to `false`.

<ResponseExample>
  ```json Example webhook payload theme={null}
  {
    "connected_account_custom_metadata": {},
    "connected_account_errors": [],
    "connected_account_id": "00000000-0000-0000-0000-000000000000",
    "connected_account_warnings": [],
    "created_at": "2025-01-01T00:00:00.000Z",
    "customer_key": "",
    "device_custom_metadata": {},
    "device_errors": [],
    "device_id": "00000000-0000-0000-0000-000000000000",
    "device_warnings": [],
    "error_code": "account_disconnected",
    "event_description": "The status of an [unmanaged device](/core-concepts/devices/managed-and-unmanaged-devices) changed from online to offline. That is, the `device.properties.online` property changed from `true` to `false`.",
    "event_id": "00000000-0000-0000-0000-000000000000",
    "event_type": "device.unmanaged.disconnected",
    "occurred_at": "2025-01-01T00:00:00.000Z",
    "workspace_id": "00000000-0000-0000-0000-000000000000"
  }
  ```
</ResponseExample>

<Accordion title="Properties">
  <ResponseField name="connected_account_custom_metadata" type="Object">
    Custom metadata of the connected account, present when connected\_account\_id is provided.
  </ResponseField>

  <ResponseField name="connected_account_errors" type="Array">
    Errors associated with the connected account.
  </ResponseField>

  <ResponseField name="connected_account_id" type="String (UUID)">
    ID of the connected account associated with the event.
  </ResponseField>

  <ResponseField name="connected_account_warnings" type="Array">
    Warnings associated with the connected account.
  </ResponseField>

  <ResponseField name="created_at" type="String (ISO 8601)">
    Date and time at which the event was created.
  </ResponseField>

  <ResponseField name="customer_key" type="String">
    The customer key associated with the device, if any.
  </ResponseField>

  <ResponseField name="device_custom_metadata" type="Object">
    Custom metadata of the device, present when device\_id is provided.
  </ResponseField>

  <ResponseField name="device_errors" type="Array">
    Errors associated with the device.
  </ResponseField>

  <ResponseField name="device_id" type="String (UUID)">
    ID of the affected device.
  </ResponseField>

  <ResponseField name="device_warnings" type="Array">
    Warnings associated with the device.
  </ResponseField>

  <ResponseField name="error_code" type="Enum (String)">
    Error code associated with the disconnection event, if any.

    Possible values: `account_disconnected`, `hub_disconnected`, `device_disconnected`
  </ResponseField>

  <ResponseField name="event_description" type="String">
    Human-readable description of the event. Persisted when the event is created (so the creating code, including a provider, can supply a tailored description) and otherwise derived from the event.
  </ResponseField>

  <ResponseField name="event_id" type="String (UUID)">
    ID of the event.
  </ResponseField>

  <ResponseField name="event_type" type="Enum (String)">
    Value: `device.unmanaged.disconnected`
  </ResponseField>

  <ResponseField name="occurred_at" type="String (ISO 8601)">
    Date and time at which the event occurred.
  </ResponseField>

  <ResponseField name="workspace_id" type="String (UUID)">
    ID of the workspace associated with the event.
  </ResponseField>
</Accordion>


# Get an Unmanaged Device
Source: https://docs.seam.co/api/devices/unmanaged/get

/openapi.json post /devices/unmanaged/get
Returns a specified [unmanaged device](/core-concepts/devices/managed-and-unmanaged-devices).

An unmanaged device has a limited set of visible properties and a subset of supported events. You cannot control an unmanaged device. Any [access codes](/low-level-apis/smart-locks/access-codes/migrating-existing-access-codes) on an unmanaged device are unmanaged. To control an unmanaged device with Seam, [convert it to a managed device](/core-concepts/devices/managed-and-unmanaged-devices#convert-an-unmanaged-device-to-managed).

You must specify either `device_id` or `name`.

You must include at least one request parameter.



# List Unmanaged Devices
Source: https://docs.seam.co/api/devices/unmanaged/list

/openapi.json post /devices/unmanaged/list
Returns a list of all [unmanaged devices](/core-concepts/devices/managed-and-unmanaged-devices).

An unmanaged device has a limited set of visible properties and a subset of supported events. You cannot control an unmanaged device. Any [access codes](/low-level-apis/smart-locks/access-codes/migrating-existing-access-codes) on an unmanaged device are unmanaged. To control an unmanaged device with Seam, [convert it to a managed device](/core-concepts/devices/managed-and-unmanaged-devices#convert-an-unmanaged-device-to-managed).



# Unmanaged Devices
Source: https://docs.seam.co/api/devices/unmanaged/object

Learn how the unmanaged_device object exposes a limited set of properties and events for a device you cannot control until you convert it to managed.

## The unmanaged\_device Object

Represents an [unmanaged device](/core-concepts/devices/managed-and-unmanaged-devices). An unmanaged device has a limited set of visible properties and a subset of supported events. You cannot control an unmanaged device. Any [access codes](/low-level-apis/smart-locks/access-codes/migrating-existing-access-codes) on an unmanaged device are unmanaged. To control an unmanaged device with Seam, [convert it to a managed device](/core-concepts/devices/managed-and-unmanaged-devices#convert-an-unmanaged-device-to-managed).

<ResponseExample>
  ```json Unmanaged Device theme={null}
  {
    "can_program_offline_access_codes": false,
    "can_program_online_access_codes": true,
    "can_remotely_lock": true,
    "can_remotely_unlock": true,
    "can_simulate_connection": false,
    "can_simulate_disconnection": true,
    "can_simulate_removal": true,
    "capabilities_supported": [
      "access_code",
      "lock"
    ],
    "connected_account_id": "c1a3967f-24a1-4220-a9c7-7fa97c1d5603",
    "created_at": "2025-06-16T16:54:17.946342Z",
    "device_id": "f4f40e75-86fc-4896-b958-e1c7e092b2cf",
    "device_type": "schlage_lock",
    "errors": [],
    "is_managed": false,
    "location": {
      "location_name": "Front Door",
      "timezone": "America/New_York"
    },
    "custom_metadata": {
      "id": "internalId1"
    },
    "properties": {
      "accessory_keypad": {
        "battery": {
          "level": 1
        },
        "is_connected": true
      },
      "battery": {
        "level": 1,
        "status": "full"
      },
      "battery_level": 1,
      "image_alt_text": "Schlage Sense Smart Deadbolt with Camelot Trim, Front",
      "image_url": "https://connect.getseam.com/_next/image?url=https://connect.getseam.com/assets/images/devices/schlage_sense-smart-deadbolt-with-camelot-trim_front.png&q=75&w=128",
      "manufacturer": "schlage",
      "model": {
        "accessory_keypad_supported": true,
        "can_connect_accessory_keypad": true,
        "display_name": "Front Door",
        "has_built_in_keypad": false,
        "manufacturer_display_name": "Schlage",
        "offline_access_codes_supported": false,
        "online_access_codes_supported": true
      },
      "name": "Front Door",
      "offline_access_codes_enabled": false,
      "online": true,
      "online_access_codes_enabled": true
    },
    "warnings": [],
    "workspace_id": "3cd6ba1c-8a60-4c24-b487-07bf6c0b755b"
  }
  ```
</ResponseExample>

***

## Properties

<ResponseField name="can_configure_auto_lock" type="Boolean">
  Indicates whether the lock supports configuring automatic locking.
</ResponseField>

<ResponseField name="can_hvac_cool" type="Boolean">
  Indicates whether the thermostat supports cooling.
</ResponseField>

<ResponseField name="can_hvac_heat" type="Boolean">
  Indicates whether the thermostat supports heating.
</ResponseField>

<ResponseField name="can_hvac_heat_cool" type="Boolean">
  Indicates whether the thermostat supports simultaneous heating and cooling.
</ResponseField>

<ResponseField name="can_program_offline_access_codes" type="Boolean">
  Indicates whether the device supports programming offline access codes.
</ResponseField>

<ResponseField name="can_program_online_access_codes" type="Boolean">
  Indicates whether the device supports programming online access codes.
</ResponseField>

<ResponseField name="can_program_thermostat_programs_as_different_each_day" type="Boolean">
  Indicates whether the thermostat supports different climate programs for each day of the week.
</ResponseField>

<ResponseField name="can_program_thermostat_programs_as_same_each_day" type="Boolean">
  Indicates whether the thermostat supports a single climate program applied to every day.
</ResponseField>

<ResponseField name="can_program_thermostat_programs_as_weekday_weekend" type="Boolean">
  Indicates whether the thermostat supports weekday/weekend climate programs.
</ResponseField>

<ResponseField name="can_remotely_lock" type="Boolean">
  Indicates whether the device supports remote locking.
</ResponseField>

<ResponseField name="can_remotely_unlock" type="Boolean">
  Indicates whether the device supports remote unlocking.
</ResponseField>

<ResponseField name="can_run_thermostat_programs" type="Boolean">
  Indicates whether the thermostat supports running climate programs.
</ResponseField>

<ResponseField name="can_simulate_connection" type="Boolean">
  Indicates whether the device supports simulating connection in a sandbox.
</ResponseField>

<ResponseField name="can_simulate_disconnection" type="Boolean">
  Indicates whether the device supports simulating disconnection in a sandbox.
</ResponseField>

<ResponseField name="can_simulate_hub_connection" type="Boolean">
  Indicates whether the hub supports simulating connection in a sandbox.
</ResponseField>

<ResponseField name="can_simulate_hub_disconnection" type="Boolean">
  Indicates whether the hub supports simulating disconnection in a sandbox.
</ResponseField>

<ResponseField name="can_simulate_paid_subscription" type="Boolean">
  Indicates whether the device supports simulating a paid subscription in a sandbox.
</ResponseField>

<ResponseField name="can_simulate_removal" type="Boolean">
  Indicates whether the device supports simulating removal in a sandbox.
</ResponseField>

<ResponseField name="can_turn_off_hvac" type="Boolean">
  Indicates whether the thermostat can be turned off.
</ResponseField>

<ResponseField name="can_unlock_with_code" type="Boolean">
  Indicates whether the lock supports unlocking with an access code.
</ResponseField>

<ResponseField name="capabilities_supported" type="Array">
  Collection of capabilities that the device supports when connected to Seam. Values are `access_code`, which indicates that the device can manage and utilize digital PIN codes for secure access; `lock`, which indicates that the device controls a door locking mechanism, enabling the remote opening and closing of doors and other entry points; `noise_detection`, which indicates that the device supports monitoring and responding to ambient noise levels; `thermostat`, which indicates that the device can regulate and adjust indoor temperatures; `battery`, which indicates that the device can manage battery life and health; and `phone`, which indicates that the device is a mobile device, such as a smartphone. **Important:** Superseded by [capability flags](/capability-guides/device-and-system-capabilities#capability-flags).
</ResponseField>

<ResponseField name="connected_account_id" type="String (UUID)">
  Unique identifier for the account associated with the device.
</ResponseField>

<ResponseField name="created_at" type="String (ISO 8601)">
  Date and time at which the device object was created.
</ResponseField>

<ResponseField name="custom_metadata" type="Object">
  Set of key:value pairs. Adding custom metadata to a resource, such as a [Connect Webview](/core-concepts/connect-webviews/attaching-custom-data-to-the-connect-webview), [connected account](/core-concepts/connected-accounts/adding-custom-metadata-to-a-connected-account), or [device](/core-concepts/devices/adding-custom-metadata-to-a-device), enables you to store custom information, like customer details or internal IDs from your application.
</ResponseField>

<ResponseField name="device_id" type="String (UUID)">
  ID of the device.
</ResponseField>

<ResponseField name="device_type" type="Enum (String)">
  Type of the device.
</ResponseField>

<ResponseField name="errors" type="Array">
  Array of errors associated with the device. Each error object within the array contains two fields: `error_code` and `message`. `error_code` is a string that uniquely identifies the type of error, enabling quick recognition and categorization of the issue. `message` provides a more detailed description of the error, offering insights into the issue and potentially how to rectify it.
</ResponseField>

<ResponseField name="is_managed" type="Boolean">
  Indicates that Seam does not manage the device.
</ResponseField>

<ResponseField name="properties" type="Object">
  properties of the device.

  <Expandable title="properties">
    <ResponseField name="accessory_keypad" type="Object">
      Accessory keypad properties and state.

      <Expandable title="properties">
        <ResponseField name="battery" type="Object">
          Keypad battery properties.

          <Expandable title="properties">
            <ResponseField name="level" type="number">
              The level.
            </ResponseField>
          </Expandable>
        </ResponseField>

        <ResponseField name="is_connected" type="Boolean">
          Indicates if an accessory keypad is connected to the device.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="battery" type="Object">
      Represents the current status of the battery charge level.

      <Expandable title="properties">
        <ResponseField name="level" type="number">
          Battery charge level as a value between 0 and 1, inclusive.
        </ResponseField>

        <ResponseField name="status" type="Enum (String)">
          Represents the current status of the battery charge level. Values are `critical`, which indicates an extremely low level, suggesting imminent shutdown or an urgent need for charging; `low`, which signifies that the battery is under the preferred threshold and should be charged soon; `good`, which denotes a satisfactory charge level, adequate for normal use without the immediate need for recharging; and `full`, which represents a battery that is fully charged, providing the maximum duration of usage.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="battery_level" type="number">
      Indicates the battery level of the device as a decimal value between 0 and 1, inclusive.
    </ResponseField>

    <ResponseField name="image_alt_text" type="String">
      Alt text for the device image.
    </ResponseField>

    <ResponseField name="image_url" type="String">
      Image URL for the device.
    </ResponseField>

    <ResponseField name="manufacturer" type="String">
      Manufacturer of the device. When a device, such as a smart lock, is connected through a smart hub, the manufacturer of the device might be different from that of the smart hub.
    </ResponseField>

    <ResponseField name="model" type="Object">
      Device model-related properties.

      <Expandable title="properties">
        <ResponseField name="accessory_keypad_supported" type="Boolean">
          **Deprecated**. use device.properties.model.can\_connect\_accessory\_keypad

          The accessory keypad supported.
        </ResponseField>

        <ResponseField name="can_connect_accessory_keypad" type="Boolean">
          Indicates whether the device can connect a accessory keypad.
        </ResponseField>

        <ResponseField name="display_name" type="String">
          Display name of the device model.
        </ResponseField>

        <ResponseField name="has_built_in_keypad" type="Boolean">
          Indicates whether the device has a built in accessory keypad.
        </ResponseField>

        <ResponseField name="manufacturer_display_name" type="String">
          Display name that corresponds to the manufacturer-specific terminology for the device.
        </ResponseField>

        <ResponseField name="offline_access_codes_supported" type="Boolean">
          **Deprecated**. use device.can\_program\_offline\_access\_codes.

          The offline access codes supported.
        </ResponseField>

        <ResponseField name="online_access_codes_supported" type="Boolean">
          **Deprecated**. use device.can\_program\_online\_access\_codes.

          The online access codes supported.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="name" type="String">
      **Deprecated**. use device.display\_name instead

      Name of the device.
    </ResponseField>

    <ResponseField name="offline_access_codes_enabled" type="Boolean">
      **Deprecated**. use device.can\_program\_offline\_access\_codes

      Indicates whether it is currently possible to use offline access codes for the device.
    </ResponseField>

    <ResponseField name="online" type="Boolean">
      Indicates whether the device is online.
    </ResponseField>

    <ResponseField name="online_access_codes_enabled" type="Boolean">
      **Deprecated**. use device.can\_program\_online\_access\_codes

      Indicates whether it is currently possible to use online access codes for the device.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="warnings" type="Array">
  Array of warnings associated with the device. Each warning object within the array contains two fields: `warning_code` and `message`. `warning_code` is a string that uniquely identifies the type of warning, enabling quick recognition and categorization of the issue. `message` provides a more detailed description of the warning, offering insights into the issue and potentially how to rectify it.
</ResponseField>

<ResponseField name="workspace_id" type="String (UUID)">
  Unique identifier for the Seam workspace associated with the device.
</ResponseField>

<ResponseField name="location" type="Object">
  Location information for the device.

  <Expandable title="properties">
    <ResponseField name="location_name" type="String">
      Name of the device location.
    </ResponseField>

    <ResponseField name="room_name" type="String">
      Name of the room within the device location, when the provider reports one.
    </ResponseField>

    <ResponseField name="time_zone" type="String">
      Time zone of the device location.
    </ResponseField>

    <ResponseField name="timezone" type="String">
      **Deprecated**. Use `time_zone` instead.

      Time zone of the device location.
    </ResponseField>
  </Expandable>
</ResponseField>

## access codes

<ResponseField name="offline_access_codes_enabled" type="Boolean">
  **Deprecated**. use device.can\_program\_offline\_access\_codes

  Indicates whether it is currently possible to use offline access codes for the device.
</ResponseField>

<ResponseField name="online_access_codes_enabled" type="Boolean">
  **Deprecated**. use device.can\_program\_online\_access\_codes

  Indicates whether it is currently possible to use online access codes for the device.
</ResponseField>

## hardware

<ResponseField name="accessory_keypad" type="Object">
  Accessory keypad properties and state.

  <Expandable title="properties">
    <ResponseField name="battery" type="Object">
      Keypad battery properties.

      <Expandable title="properties">
        <ResponseField name="level" type="number">
          The level.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="is_connected" type="Boolean">
      Indicates if an accessory keypad is connected to the device.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="battery" type="Object">
  Represents the current status of the battery charge level.

  <Expandable title="properties">
    <ResponseField name="level" type="number">
      Battery charge level as a value between 0 and 1, inclusive.
    </ResponseField>

    <ResponseField name="status" type="Enum (String)">
      Represents the current status of the battery charge level. Values are `critical`, which indicates an extremely low level, suggesting imminent shutdown or an urgent need for charging; `low`, which signifies that the battery is under the preferred threshold and should be charged soon; `good`, which denotes a satisfactory charge level, adequate for normal use without the immediate need for recharging; and `full`, which represents a battery that is fully charged, providing the maximum duration of usage.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="battery_level" type="number">
  Indicates the battery level of the device as a decimal value between 0 and 1, inclusive.
</ResponseField>

<ResponseField name="image_alt_text" type="String">
  Alt text for the device image.
</ResponseField>

<ResponseField name="image_url" type="String">
  Image URL for the device.
</ResponseField>

<ResponseField name="manufacturer" type="String">
  Manufacturer of the device. When a device, such as a smart lock, is connected through a smart hub, the manufacturer of the device might be different from that of the smart hub.
</ResponseField>


# Update an Unmanaged Device
Source: https://docs.seam.co/api/devices/unmanaged/update

/openapi.json post /devices/unmanaged/update
Updates a specified [unmanaged device](/core-concepts/devices/managed-and-unmanaged-devices). To convert an unmanaged device to managed, set `is_managed` to `true`.

An unmanaged device has a limited set of visible properties and a subset of supported events. You cannot control an unmanaged device. Any [access codes](/low-level-apis/smart-locks/access-codes/migrating-existing-access-codes) on an unmanaged device are unmanaged. To control an unmanaged device with Seam, [convert it to a managed device](/core-concepts/devices/managed-and-unmanaged-devices#convert-an-unmanaged-device-to-managed).



# Update a Device
Source: https://docs.seam.co/api/devices/update

/openapi.json post /devices/update
Updates a specified [device](/core-concepts/devices).

You can add or change [custom metadata](/core-concepts/devices/adding-custom-metadata-to-a-device) for a device, change the device's name, or [convert a managed device to unmanaged](/core-concepts/devices/managed-and-unmanaged-devices).



# Get an Event
Source: https://docs.seam.co/api/events/get

/openapi.json post /events/get
Returns a specified event. This endpoint returns the same event that would be sent to a [webhook](/developer-tools/webhooks), but it enables you to retrieve an event that already took place.

You must include at least one request parameter.



# List Events
Source: https://docs.seam.co/api/events/list

/openapi.json post /events/list
Returns a list of all events. This endpoint returns the same events that would be sent to a [webhook](/developer-tools/webhooks), but it enables you to filter or see events that already took place.

You must include at least one request parameter.



# The Event Object
Source: https://docs.seam.co/api/events/object

Learn how the event object represents an occurrence in your workspace, such as a device action or status change, that you can list and react to.

## The event Object

<ResponseExample>
  ```json Event theme={null}
  {
    "connected_account_id": "2e3f4a5b-6c7d-8e9f-0a1b-2c3d4e5f6a7b",
    "created_at": "2025-06-15T16:54:18.000000Z",
    "device_id": "b3c4d5e6-f7a8-49bc-def1-23456789abcd",
    "event_description": "The status of a device changed from offline to online. That is, the device.properties.online property changed from false to true. Note that some devices operate entirely in offline mode, so Seam never emits a device.connected event for these devices.",
    "event_id": "6d7e8f9a-1b2c-3d4e-5f6a-7b8c9d0e1f2a",
    "event_type": "device.connected",
    "occurred_at": "2025-06-15T16:54:17.946329Z",
    "workspace_id": "9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d"
  }
  ```
</ResponseExample>

***

## Properties

<ResponseField name="created_at" type="String (ISO 8601)">
  Date and time at which the event was created.
</ResponseField>

<ResponseField name="event_description" type="String">
  Human-readable description of the event. Persisted when the event is created (so the creating code, including a provider, can supply a tailored description) and otherwise derived from the event.
</ResponseField>

<ResponseField name="event_id" type="String (UUID)">
  ID of the event.
</ResponseField>

<ResponseField name="event_type" type="Enum (String)">
  The event type.

  <Accordion title="Enum values">
    * `access_code.created`
    * `access_code.changed`
    * `access_code.name_changed`
    * `access_code.code_changed`
    * `access_code.time_frame_changed`
    * `access_code.mutations_requested`
    * `access_code.scheduled_on_device`
    * `access_code.set_on_device`
    * `access_code.removed_from_device`
    * `access_code.delay_in_setting_on_device`
    * `access_code.failed_to_set_on_device`
    * `access_code.deleted`
    * `access_code.delay_in_removing_from_device`
    * `access_code.failed_to_remove_from_device`
    * `access_code.modified_external_to_seam`
    * `access_code.deleted_external_to_seam`
    * `access_code.backup_access_code_pulled`
    * `access_code.unmanaged.converted_to_managed`
    * `access_code.unmanaged.failed_to_convert_to_managed`
    * `access_code.unmanaged.created`
    * `access_code.unmanaged.removed`
    * `access_grant.created`
    * `access_grant.deleted`
    * `access_grant.access_granted_to_all_doors`
    * `access_grant.access_granted_to_door`
    * `access_grant.access_to_door_lost`
    * `access_grant.access_times_changed`
    * `access_grant.could_not_create_requested_access_methods`
    * `access_method.issued`
    * `access_method.revoked`
    * `access_method.card_encoding_required`
    * `access_method.deleted`
    * `access_method.reissued`
    * `access_method.created`
    * `access_method.delay_in_issuing`
    * `access_method.failed_to_issue`
    * `acs_system.connected`
    * `acs_system.added`
    * `acs_system.disconnected`
    * `acs_credential.deleted`
    * `acs_credential.issued`
    * `acs_credential.reissued`
    * `acs_credential.invalidated`
    * `acs_user.created`
    * `acs_user.deleted`
    * `acs_encoder.added`
    * `acs_encoder.removed`
    * `acs_access_group.deleted`
    * `acs_entrance.added`
    * `acs_entrance.removed`
    * `client_session.deleted`
    * `connected_account.connected`
    * `connected_account.created`
    * `connected_account.successful_login`
    * `connected_account.disconnected`
    * `connected_account.completed_first_sync`
    * `connected_account.deleted`
    * `connected_account.completed_first_sync_after_reconnection`
    * `connected_account.reauthorization_requested`
    * `action_attempt.lock_door.succeeded`
    * `action_attempt.lock_door.failed`
    * `action_attempt.unlock_door.succeeded`
    * `action_attempt.unlock_door.failed`
    * `action_attempt.simulate_keypad_code_entry.succeeded`
    * `action_attempt.simulate_keypad_code_entry.failed`
    * `action_attempt.simulate_manual_lock_via_keypad.succeeded`
    * `action_attempt.simulate_manual_lock_via_keypad.failed`
    * `connect_webview.login_succeeded`
    * `connect_webview.login_failed`
    * `device.connected`
    * `device.added`
    * `device.converted_to_unmanaged`
    * `device.unmanaged.converted_to_managed`
    * `device.unmanaged.connected`
    * `device.disconnected`
    * `device.unmanaged.disconnected`
    * `device.tampered`
    * `device.low_battery`
    * `device.battery_status_changed`
    * `device.removed`
    * `device.deleted`
    * `device.third_party_integration_detected`
    * `device.third_party_integration_no_longer_detected`
    * `device.salto.privacy_mode_activated`
    * `device.salto.privacy_mode_deactivated`
    * `device.connection_became_flaky`
    * `device.connection_stabilized`
    * `device.error.subscription_required`
    * `device.error.subscription_required.resolved`
    * `device.accessory_keypad_connected`
    * `device.accessory_keypad_disconnected`
    * `noise_sensor.noise_threshold_triggered`
    * `lock.locked`
    * `lock.unlocked`
    * `lock.access_denied`
    * `thermostat.climate_preset_activated`
    * `thermostat.manually_adjusted`
    * `thermostat.temperature_threshold_exceeded`
    * `thermostat.temperature_threshold_no_longer_exceeded`
    * `thermostat.temperature_reached_set_point`
    * `thermostat.temperature_changed`
    * `device.name_changed`
    * `camera.activated`
    * `device.doorbell_rang`
    * `phone.deactivated`
    * `space.device_membership_changed`
    * `space.created`
    * `space.deleted`
  </Accordion>
</ResponseField>

<ResponseField name="occurred_at" type="String (ISO 8601)">
  Date and time at which the event occurred.
</ResponseField>

<ResponseField name="workspace_id" type="String (UUID)">
  ID of the workspace associated with the event.
</ResponseField>


# Introduction
Source: https://docs.seam.co/api/index

The Seam API lets you control smart locks, thermostats, access control systems, and more through a unified REST interface.

The Seam API is organized around REST. It accepts JSON request bodies, returns JSON responses, and uses standard HTTP response codes and verbs.

You can use the Seam API in a [sandbox workspace](/core-concepts/workspaces) without affecting live devices. The API key you use determines whether the request runs in sandbox or production mode.

**Just getting started?** Check out the [quickstart guide](/quickstart).

```
Base URL: https://connect.getseam.com
```

<CardGroup>
  <Card title="Install an SDK" icon="download" href="/api/installation">
    JavaScript, Python, Ruby, PHP, C#, or Go.
  </Card>

  <Card title="Authentication" icon="key" href="/api/authentication">
    API keys, client sessions, or personal access tokens.
  </Card>

  <Card title="MCP for AI Agents" icon="plug" href="/api/mcp-installation">
    Connect Seam to AI assistants via MCP.
  </Card>
</CardGroup>

***

## Granting Access

Use [Access Grants](/api/access_grants/object) to give people access to physical spaces. Tell Seam *who* should have access, *where*, and *when* — Seam automatically creates the right credential and programs it to the device.

<Card title="Access Grants" icon="id-badge" href="/api/access_grants/object">
  The primary API for granting access — create, update, revoke, and manage the full lifecycle.
</Card>

Access Grants support all access methods through a single API:

<CardGroup>
  <Card title="PIN Codes" icon="input-numeric">
    Generate keypad codes for smart locks. Ongoing or time-bound.
  </Card>

  <Card title="Key Cards" icon="id-card">
    Encode plastic cards for access control systems.
  </Card>

  <Card title="Mobile Keys" icon="mobile">
    Issue mobile credentials via app or Instant Key URL.
  </Card>

  <Card title="Remote Unlock" icon="lock-open">
    Unlock doors remotely via API call.
  </Card>
</CardGroup>

***

## Devices and Systems

Connect and control IoT devices and access control systems.

<CardGroup>
  <Card title="Devices" icon="microchip" href="/core-concepts/devices">
    List, get, and update connected devices.
  </Card>

  <Card title="Locks" icon="lock" href="/api/locks/object">
    Lock and unlock smart locks.
  </Card>

  <Card title="Thermostats" icon="temperature-half" href="/capability-guides/thermostats">
    Set temperature, HVAC mode, and climate presets.
  </Card>

  <Card title="Noise Sensors" icon="volume-high" href="/api/noise_sensors/object">
    Monitor noise levels and configure thresholds.
  </Card>

  <Card title="ACS" icon="server" href="/api/acs/object">
    Manage access control system users, credentials, entrances, and encoders.
  </Card>
</CardGroup>

***

## Setup

Connect device accounts and configure your workspace.

<CardGroup>
  <Card title="Connect Webviews" icon="window-restore" href="/api/connect_webviews/object">
    Authorization flows to link user device accounts.
  </Card>

  <Card title="Connected Accounts" icon="link" href="/api/connected_accounts/object">
    Manage linked manufacturer accounts.
  </Card>

  <Card title="User Identities" icon="user" href="/api/user_identities/object">
    Map your users to Seam for cross-system identity.
  </Card>

  <Card title="Workspaces" icon="briefcase" href="/core-concepts/workspaces">
    Sandbox and production workspaces.
  </Card>

  <Card title="Client Sessions" icon="user-shield" href="/api/client_sessions/object">
    Scoped sessions for frontend apps.
  </Card>

  <Card title="Customers" icon="users" href="/capability-guides/customer-portals/customers">
    Customer portals and data.
  </Card>

  <Card title="Spaces" icon="building" href="/api/spaces/object">
    Organize devices and entrances into named groups.
  </Card>
</CardGroup>

***

## Monitoring

Track events, subscribe to webhooks, and poll for action completion.

<CardGroup>
  <Card title="Events" icon="timeline" href="/api/events/object">
    Query device and system events.
  </Card>

  <Card title="Webhooks" icon="bell" href="/developer-tools/webhooks">
    Real-time event notifications.
  </Card>

  <Card title="Action Attempts" icon="spinner" href="/api/action_attempts/object">
    Poll async operations until completion.
  </Card>
</CardGroup>

***

## Low-Level APIs

These APIs let you program credentials directly on devices. For most access-granting workflows, use [Access Grants](/api/access_grants/object) instead — they handle credential creation, device programming, and lifecycle management automatically.

<CardGroup>
  <Card title="Access Codes" icon="input-numeric" href="/api/access_codes/object">
    Directly program PIN codes on smart lock keypads.
  </Card>

  <Card title="Instant Keys" icon="bolt" href="/api/instant_keys/object">
    Temporary mobile keys without an app install.
  </Card>

  <Card title="Phones" icon="mobile" href="/api/phones/object">
    Manage phones for mobile access credentials.
  </Card>
</CardGroup>


# SDK Installation
Source: https://docs.seam.co/api/installation

Install a Seam SDK in your preferred language—JavaScript, Python, Ruby, PHP, or C#—to start building integrations with the Seam API in minutes.

<Check>
  **Building this integration with Claude?** Install the [Seam Docs MCP
  server](/api/mcp-installation) first. It connects Claude directly to Seam's API
  reference, integration guides, and 400+ device models so Claude can guide you
  through implementation step by step — no copy-pasting from the docs.
</Check>

Install one of the Seam SDKs in the programming language of your choice. Seam supports many programming languages, such as the following:

* JavaScript / TypeScript ([npm](https://www.npmjs.com/package/seam), [GitHub](https://github.com/seamapi/javascript))
* Python ([pip](https://pypi.org/project/seam/), [GitHub](https://github.com/seamapi/python))
* Ruby Gem ([rubygem](https://rubygems.org/gems/seam), [GitHub](https://github.com/seamapi/ruby))
* PHP ([packagist](https://packagist.org/packages/seamapi/seam), [GitHub](https://github.com/seamapi/php))
* C# ([nuget](https://www.nuget.org/packages/Seam), [GitHub](https://github.com/seamapi/csharp))

<Tabs>
  <Tab title="JavaScript">
    ```bash theme={null}
    npm i seam
    ```
  </Tab>

  <Tab title="Python">
    ```bash theme={null}
    pip install seam
    # For some development environments, use pip3 in this command instead of pip.
    ```
  </Tab>

  <Tab title="Ruby">
    ```bash theme={null}
    bundle add seam
    ```
  </Tab>

  <Tab title="PHP">
    ```bash theme={null}
    composer require seamapi/seam
    ```
  </Tab>

  <Tab title="C#">
    Install using [nuget](https://www.nuget.org/packages/Seam).
  </Tab>
</Tabs>


# Delete an Instant Key
Source: https://docs.seam.co/api/instant_keys/delete

/openapi.json post /instant_keys/delete
Deletes a specified [Instant Key](/use-cases/granting-access/using-instant-keys).



# Get an Instant Key
Source: https://docs.seam.co/api/instant_keys/get

/openapi.json post /instant_keys/get
Gets an [instant key](/use-cases/granting-access/using-instant-keys).

You must include at least one request parameter.



# List Instant Keys
Source: https://docs.seam.co/api/instant_keys/list

/openapi.json post /instant_keys/list
Returns a list of all [instant keys](/use-cases/granting-access/using-instant-keys).



# The Instant Key Object
Source: https://docs.seam.co/api/instant_keys/object

Learn how the instant_key object lets you issue a Bluetooth mobile key with one API call and share it by link, text, or email—no app install required.

## The instant\_key Object

Represents a Seam Instant Key. For issuing Bluetooth mobile keys, Instant Keys are the fastest way to share access. With a single API call, you can create a mobile key and send it through text or email or embed it in your own app.

There’s no app to install, nor account to create. Your user just taps a link and gets a lightweight, native-feeling experience using iOS App Clip or Instant Apps on Android. Further, Instant Keys work offline, so even in areas with poor cellular or Wi-Fi, like elevator banks or concrete-walled hallways, the Instant Keys still work.

<ResponseExample>
  ```json Instant Key theme={null}
  {
    "client_session_id": "bfe3b1c6-fb9e-48b1-9b5b-c762b2983af6",
    "created_at": "2025-06-14T16:54:17.946559Z",
    "expires_at": "2025-06-16T16:54:17.946559Z",
    "instant_key_id": "1d05c2f6-5b6f-4a9c-b80d-1eca26be12b9",
    "instant_key_url": "https://ik.seam.co/ABCXYZ",
    "user_identity_id": "e7a94acb-bd8a-4462-b6fb-8612d35cd7c3",
    "workspace_id": "4d1c24b2-781e-4d1a-8d77-15249ad57c8a"
  }
  ```
</ResponseExample>

***

## Properties

<ResponseField name="client_session_id" type="String (UUID)">
  ID of the client session associated with the Instant Key.
</ResponseField>

<ResponseField name="created_at" type="String (ISO 8601)">
  Date and time at which the Instant Key was created.
</ResponseField>

<ResponseField name="customization" type="Object">
  Customization applied to the Instant Key UI.

  <Expandable title="properties">
    <ResponseField name="logo_url" type="String">
      URL of the logo displayed on the Instant Key.
    </ResponseField>

    <ResponseField name="primary_color" type="String">
      Primary color used in the Instant Key UI.
    </ResponseField>

    <ResponseField name="secondary_color" type="String">
      Secondary color used in the Instant Key UI.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="customization_profile_id" type="String (UUID)">
  ID of the customization profile associated with the Instant Key.
</ResponseField>

<ResponseField name="expires_at" type="String (ISO 8601)">
  Date and time at which the Instant Key expires.
</ResponseField>

<ResponseField name="instant_key_id" type="String (UUID)">
  ID of the Instant Key.
</ResponseField>

<ResponseField name="instant_key_url" type="String">
  Shareable URL for the Instant Key. Use the URL to deliver the Instant Key to your user through a link in a text message or email or by embedding it in your web app.
</ResponseField>

<ResponseField name="user_identity_id" type="String (UUID)">
  ID of the user identity associated with the Instant Key.
</ResponseField>

<ResponseField name="workspace_id" type="String (UUID)">
  ID of the workspace that contains the Instant Key.
</ResponseField>


# Configure Auto-Lock
Source: https://docs.seam.co/api/locks/configure_auto_lock

/openapi.json post /locks/configure_auto_lock
Configures the auto-lock setting for a specified [lock](/low-level-apis/smart-locks).



# Lock Errors and Warnings
Source: https://docs.seam.co/api/locks/errors

Errors and warnings that Seam reports on the Lock resource, each with its code and meaning.

<Note>
  These are Lock-specific errors and warnings. For errors and warnings common to all devices, see [Device Errors and Warnings](/api/devices/errors).
</Note>

## Errors

Each error is an object with the following shape:

```json Example error theme={null}
{
  "error_code": "salto_ks_subscription_limit_exceeded",
  "message": "Indicates that the Salto site user limit has been reached.",
  "created_at": "2025-01-01T00:00:00.000Z",
  "is_connected_account_error": true,
  "is_device_error": true
}
```

<Accordion title="Error object properties">
  <ResponseField name="error_code" type="Enum (String)">
    Unique identifier of the type of error. Enables quick recognition and categorization of the issue.

    One of the error codes listed below.
  </ResponseField>

  <ResponseField name="message" type="String">
    Detailed description of the error. Provides insights into the issue and potentially how to rectify it.
  </ResponseField>

  <ResponseField name="created_at" type="String (ISO 8601)">
    Date and time at which Seam created the error.
  </ResponseField>

  <ResponseField name="is_connected_account_error" type="Boolean">
    Indicates that the error is a [connected account](/api/connected_accounts/object) error.
  </ResponseField>

  <ResponseField name="is_device_error" type="Boolean">
    Indicates that the error is not a device error.
  </ResponseField>
</Accordion>

### `august_lock_not_authorized`

Indicates that the user is not authorized to use the August lock.

***

### `dormakaba_sites_disconnected`

Indicates that one or more dormakaba sites associated with the connected account could not be connected. Contact dormakaba support.

***

### `salto_ks_subscription_limit_exceeded`

Indicates that the Salto site user limit has been reached.

***

## Warnings

Each warning is an object with the following shape:

```json Example warning theme={null}
{
  "warning_code": "ttlock_lock_gateway_unlocking_not_enabled",
  "message": "Indicates that the Remote Unlock feature is not enabled in the settings.\"",
  "created_at": "2025-01-01T00:00:00.000Z"
}
```

<Accordion title="Warning object properties">
  <ResponseField name="warning_code" type="Enum (String)">
    Unique identifier of the type of warning. Enables quick recognition and categorization of the issue.

    One of the warning codes listed below.
  </ResponseField>

  <ResponseField name="message" type="String">
    Detailed description of the warning. Provides insights into the issue and potentially how to rectify it.
  </ResponseField>

  <ResponseField name="created_at" type="String (ISO 8601)">
    Date and time at which Seam created the warning.
  </ResponseField>
</Accordion>

### `accessory_keypad_setup_required`

Indicates that the accessory keypad exists, but is not linked to the Igloohome Bridge. Online access code programming will fail until the keypad is linked to the Igloohome Bridge in the Igloohome app.

***

### `hub_required_for_additional_capabilities`

Indicates that a hub or relay must be connected to unlock additional capabilities such as remote unlock.

***

### `keynest_unsupported_locker`

Indicates that the key is in a locker that does not support the access codes API.

***

### `lockly_time_zone_not_configured`

Indicates that Seam detected that the Lockly device does not have a time zone configured. Time-bound codes may not work as expected.

***

### `power_saving_mode`

Indicates that the device is in power saving mode and may have limited functionality.

***

### `salto_ks_subscription_limit_almost_reached`

Indicates that the Salto KS site has exceeded 80% of the maximum number of allowed users. Increase your subscription limit or delete some users from your site.

***

### `time_zone_mismatch`

Indicates that the device's configured time zone does not match its hardware UTC offset. Time-bound access codes may activate at the wrong local time.

***

### `time_zone_unknown`

Indicates that Seam does not know the device's time zone. Set a time zone to enable time-bound access codes.

***

### `ttlock_lock_gateway_unlocking_not_enabled`

Indicates that the Remote Unlock feature is not enabled in the settings."

***

### `ttlock_weak_gateway_signal`

Indicates that the gateway signal is weak.

***

### `two_n_device_missing_timezone`

Indicates that the 2N device does not have a time zone configured. Configure a time zone on the device to enable access codes.

***

### `ultraloq_time_zone_unknown`

Indicates that Seam does not know the time zone of the Ultraloq device. Set a time zone to enable time-bound access codes.

***

### `unreliable_online_status`

Indicates that the device may optimistically be reported as online because the provider does not reliably report its online status.

***


# Lock Events
Source: https://docs.seam.co/api/locks/events

Webhook events that Seam emits for the Lock resource, with example payloads and properties.

## `lock.locked`

A [lock](/low-level-apis/smart-locks) was locked.

<ResponseExample>
  ```json Example webhook payload theme={null}
  {
    "access_code_id": "00000000-0000-0000-0000-000000000000",
    "access_code_is_managed": true,
    "action_attempt_id": "00000000-0000-0000-0000-000000000000",
    "code": "1234",
    "connected_account_custom_metadata": {},
    "connected_account_id": "00000000-0000-0000-0000-000000000000",
    "created_at": "2025-01-01T00:00:00.000Z",
    "customer_key": "",
    "device_custom_metadata": {},
    "device_id": "00000000-0000-0000-0000-000000000000",
    "event_description": "A [lock](/low-level-apis/smart-locks) was locked.",
    "event_id": "00000000-0000-0000-0000-000000000000",
    "event_type": "lock.locked",
    "is_via_bluetooth": true,
    "is_via_nfc": true,
    "method": "keycode",
    "occurred_at": "2025-01-01T00:00:00.000Z",
    "workspace_id": "00000000-0000-0000-0000-000000000000"
  }
  ```
</ResponseExample>

<Accordion title="Properties">
  <ResponseField name="access_code_id" type="String (UUID)">
    ID of the access code that was used to lock the device.
  </ResponseField>

  <ResponseField name="access_code_is_managed" type="Boolean">
    Whether the access code is managed by Seam (true) or unmanaged (false). Only present when access\_code\_id is set.
  </ResponseField>

  <ResponseField name="action_attempt_id" type="String (UUID)">
    ID of the Seam action attempt that triggered this lock. Present only when the lock was initiated through Seam (via a `LOCK_DOOR` action attempt).
  </ResponseField>

  <ResponseField name="code" type="String">
    Code (PIN) that was used to lock the device, if known. Taken from the matched managed or unmanaged access code, or from the code reported by the provider when no access code matched.
  </ResponseField>

  <ResponseField name="connected_account_custom_metadata" type="Object">
    Custom metadata of the connected account, present when connected\_account\_id is provided.
  </ResponseField>

  <ResponseField name="connected_account_id" type="String (UUID)">
    ID of the connected account associated with the event.
  </ResponseField>

  <ResponseField name="created_at" type="String (ISO 8601)">
    Date and time at which the event was created.
  </ResponseField>

  <ResponseField name="customer_key" type="String">
    The customer key associated with the device, if any.
  </ResponseField>

  <ResponseField name="device_custom_metadata" type="Object">
    Custom metadata of the device, present when device\_id is provided.
  </ResponseField>

  <ResponseField name="device_id" type="String (UUID)">
    ID of the affected device.
  </ResponseField>

  <ResponseField name="event_description" type="String">
    Human-readable description of the event. Persisted when the event is created (so the creating code, including a provider, can supply a tailored description) and otherwise derived from the event.
  </ResponseField>

  <ResponseField name="event_id" type="String (UUID)">
    ID of the event.
  </ResponseField>

  <ResponseField name="event_type" type="Enum (String)">
    Value: `lock.locked`
  </ResponseField>

  <ResponseField name="is_via_bluetooth" type="Boolean">
    Whether the lock action was performed over Bluetooth by a remote client (such as the provider's mobile app), rather than a direct physical interaction or a Seam-initiated remote action.
  </ResponseField>

  <ResponseField name="is_via_nfc" type="Boolean">
    Whether the lock action was performed by an NFC credential tap (such as an Apple Home Key or an NFC key fob) presented to the lock, rather than a direct physical interaction or a Seam-initiated remote action.
  </ResponseField>

  <ResponseField name="method" type="Enum (String)">
    Method by which the lock was locked. `keycode`: an access code was used (see `access_code_id`). `manual`: a physical action such as a thumbturn or button press. `remote`: a remote action via an app, Bluetooth, or the Seam API (see `action_attempt_id` if Seam-initiated; see `is_via_bluetooth` or `is_via_nfc` for the transport). `automatic`: triggered automatically, for example by an auto-relock timer. `unknown`: could not be determined.

    Possible values: `keycode`, `manual`, `automatic`, `unknown`, `remote`, `card`
  </ResponseField>

  <ResponseField name="occurred_at" type="String (ISO 8601)">
    Date and time at which the event occurred.
  </ResponseField>

  <ResponseField name="workspace_id" type="String (UUID)">
    ID of the workspace associated with the event.
  </ResponseField>
</Accordion>

## `lock.unlocked`

A [lock](/low-level-apis/smart-locks) was unlocked.

<ResponseExample>
  ```json Example webhook payload theme={null}
  {
    "access_code_id": "00000000-0000-0000-0000-000000000000",
    "access_code_is_managed": true,
    "action_attempt_id": "00000000-0000-0000-0000-000000000000",
    "code": "1234",
    "connected_account_custom_metadata": {},
    "connected_account_id": "00000000-0000-0000-0000-000000000000",
    "created_at": "2025-01-01T00:00:00.000Z",
    "customer_key": "",
    "device_custom_metadata": {},
    "device_id": "00000000-0000-0000-0000-000000000000",
    "event_description": "A [lock](/low-level-apis/smart-locks) was unlocked.",
    "event_id": "00000000-0000-0000-0000-000000000000",
    "event_type": "lock.unlocked",
    "is_via_bluetooth": true,
    "is_via_nfc": true,
    "method": "keycode",
    "occurred_at": "2025-01-01T00:00:00.000Z",
    "workspace_id": "00000000-0000-0000-0000-000000000000"
  }
  ```
</ResponseExample>

<Accordion title="Properties">
  <ResponseField name="access_code_id" type="String (UUID)">
    ID of the access code that was used to unlock the affected device.
  </ResponseField>

  <ResponseField name="access_code_is_managed" type="Boolean">
    Whether the access code is managed by Seam (true) or unmanaged (false). Only present when access\_code\_id is set.
  </ResponseField>

  <ResponseField name="action_attempt_id" type="String (UUID)">
    ID of the Seam action attempt that triggered this unlock. Present only when the unlock was initiated through Seam (via an `UNLOCK_DOOR` action attempt).
  </ResponseField>

  <ResponseField name="code" type="String">
    Code (PIN) that was used to unlock the affected device, if known. Taken from the matched managed or unmanaged access code, or from the code reported by the provider when no access code matched.
  </ResponseField>

  <ResponseField name="connected_account_custom_metadata" type="Object">
    Custom metadata of the connected account, present when connected\_account\_id is provided.
  </ResponseField>

  <ResponseField name="connected_account_id" type="String (UUID)">
    ID of the connected account associated with the event.
  </ResponseField>

  <ResponseField name="created_at" type="String (ISO 8601)">
    Date and time at which the event was created.
  </ResponseField>

  <ResponseField name="customer_key" type="String">
    The customer key associated with the device, if any.
  </ResponseField>

  <ResponseField name="device_custom_metadata" type="Object">
    Custom metadata of the device, present when device\_id is provided.
  </ResponseField>

  <ResponseField name="device_id" type="String (UUID)">
    ID of the affected device.
  </ResponseField>

  <ResponseField name="event_description" type="String">
    Human-readable description of the event. Persisted when the event is created (so the creating code, including a provider, can supply a tailored description) and otherwise derived from the event.
  </ResponseField>

  <ResponseField name="event_id" type="String (UUID)">
    ID of the event.
  </ResponseField>

  <ResponseField name="event_type" type="Enum (String)">
    Value: `lock.unlocked`
  </ResponseField>

  <ResponseField name="is_via_bluetooth" type="Boolean">
    Whether the unlock action was performed over Bluetooth by a remote client (such as the provider's mobile app), rather than a direct physical interaction or a Seam-initiated remote action.
  </ResponseField>

  <ResponseField name="is_via_nfc" type="Boolean">
    Whether the unlock action was performed by an NFC credential tap (such as an Apple Home Key or an NFC key fob) presented to the lock, rather than a direct physical interaction or a Seam-initiated remote action.
  </ResponseField>

  <ResponseField name="method" type="Enum (String)">
    Method by which the lock was unlocked. `keycode`: an [access code](/low-level-apis/smart-locks/access-codes) was used (see `access_code_id`). `manual`: a physical action such as a thumbturn or handle press. `remote`: a remote action via an app, Bluetooth, or the Seam API (see `action_attempt_id` if Seam-initiated; see `is_via_bluetooth` or `is_via_nfc` for the transport). `automatic`: triggered automatically, for example by a time-based schedule. `unknown`: could not be determined.

    Possible values: `keycode`, `manual`, `automatic`, `unknown`, `remote`, `card`
  </ResponseField>

  <ResponseField name="occurred_at" type="String (ISO 8601)">
    Date and time at which the event occurred.
  </ResponseField>

  <ResponseField name="workspace_id" type="String (UUID)">
    ID of the workspace associated with the event.
  </ResponseField>
</Accordion>

## `lock.access_denied`

The [lock](/low-level-apis/smart-locks) denied access to a user after one or more consecutive invalid attempts to unlock the device.

<ResponseExample>
  ```json Example webhook payload theme={null}
  {
    "access_code_id": "00000000-0000-0000-0000-000000000000",
    "connected_account_custom_metadata": {},
    "connected_account_id": "00000000-0000-0000-0000-000000000000",
    "created_at": "2025-01-01T00:00:00.000Z",
    "customer_key": "",
    "device_custom_metadata": {},
    "device_id": "00000000-0000-0000-0000-000000000000",
    "event_description": "The [lock](/low-level-apis/smart-locks) denied access to a user after one or more consecutive invalid attempts to unlock the device.",
    "event_id": "00000000-0000-0000-0000-000000000000",
    "event_type": "lock.access_denied",
    "occurred_at": "2025-01-01T00:00:00.000Z",
    "reason": {
      "message": "",
      "reason_code": "unknown_code"
    },
    "workspace_id": "00000000-0000-0000-0000-000000000000"
  }
  ```
</ResponseExample>

<Accordion title="Properties">
  <ResponseField name="access_code_id" type="String (UUID)">
    ID of the access code that was used in the unlock attempts.
  </ResponseField>

  <ResponseField name="connected_account_custom_metadata" type="Object">
    Custom metadata of the connected account, present when connected\_account\_id is provided.
  </ResponseField>

  <ResponseField name="connected_account_id" type="String (UUID)">
    ID of the connected account associated with the event.
  </ResponseField>

  <ResponseField name="created_at" type="String (ISO 8601)">
    Date and time at which the event was created.
  </ResponseField>

  <ResponseField name="customer_key" type="String">
    The customer key associated with the device, if any.
  </ResponseField>

  <ResponseField name="device_custom_metadata" type="Object">
    Custom metadata of the device, present when device\_id is provided.
  </ResponseField>

  <ResponseField name="device_id" type="String (UUID)">
    ID of the affected device.
  </ResponseField>

  <ResponseField name="event_description" type="String">
    Human-readable description of the event. Persisted when the event is created (so the creating code, including a provider, can supply a tailored description) and otherwise derived from the event.
  </ResponseField>

  <ResponseField name="event_id" type="String (UUID)">
    ID of the event.
  </ResponseField>

  <ResponseField name="event_type" type="Enum (String)">
    Value: `lock.access_denied`
  </ResponseField>

  <ResponseField name="occurred_at" type="String (ISO 8601)">
    Date and time at which the event occurred.
  </ResponseField>

  <ResponseField name="reason" type="Object">
    Why access was denied, when the provider reports a determinable cause. Omitted when unknown.

    <Expandable title="properties">
      <ResponseField name="message" type="String">
        Human-readable explanation of why access was denied.
      </ResponseField>

      <ResponseField name="reason_code" type="Enum (String)">
        Normalized reason a lock denied access. Provider-agnostic; not all providers report every value.

        Possible values: `unknown_code`, `expired_code`, `blocklisted_code`, `too_many_attempts`, `blocked_by_privacy_mode`, `credential_error`
      </ResponseField>
    </Expandable>
  </ResponseField>

  <ResponseField name="workspace_id" type="String (UUID)">
    ID of the workspace associated with the event.
  </ResponseField>
</Accordion>


# Get a Lock
Source: https://docs.seam.co/api/locks/get

/openapi.json post /locks/get
Deprecated. Use `/devices/get` instead.

Returns a specified [lock](/low-level-apis/smart-locks).

You must include at least one request parameter.



# List Locks
Source: https://docs.seam.co/api/locks/list

/openapi.json post /locks/list
Returns a list of all [locks](/low-level-apis/smart-locks).



# Lock a Lock
Source: https://docs.seam.co/api/locks/lock_door

/openapi.json post /locks/lock_door
Locks a [lock](/low-level-apis/smart-locks). See also [Locking and Unlocking Smart Locks](/low-level-apis/smart-locks/lock-and-unlock).



# The Lock Object
Source: https://docs.seam.co/api/locks/object

Learn how the device object represents a smart lock connected to Seam, including its lock-specific properties, capabilities, errors, and events.

## The device Object for Locks

Represents a [lock](/low-level-apis/smart-locks).

The Seam API enables you to control connected smart locks from a wide variety of manufacturers, including locks that provide online and offline [access code](/low-level-apis/smart-locks/access-codes) programming.

Depending on the smart lock brand and model, actions that you can perform include remote unlock, remote lock, and programming access codes. You can also view a lock's properties, capabilities, and status. Further, you can monitor for unlock and lock events.

See also [Webhooks](/developer-tools/webhooks).

<ResponseExample>
  ```json Lock Device theme={null}
  {
    "can_program_online_access_codes": true,
    "can_remotely_lock": true,
    "can_remotely_unlock": true,
    "capabilities_supported": [
      "access_code",
      "lock"
    ],
    "connected_account_id": "8e3a4f1b-2c7d-4a9e-8b5f-3d2c1a0b9e8f",
    "created_at": "2025-03-27T02:08:16.418Z",
    "space_ids": [],
    "custom_metadata": {
      "id": "internalId1"
    },
    "device_id": "a69569e1-133b-4a9d-b883-018641bfe543",
    "device_type": "schlage_lock",
    "display_name": "FRONT DOOR",
    "errors": [],
    "is_managed": true,
    "location": {
      "location_name": "Front Door",
      "timezone": "America/New_York"
    },
    "nickname": "Front Door",
    "properties": {
      "appearance": {
        "name": "FRONT DOOR"
      },
      "battery": {
        "level": 0.48,
        "status": "good"
      },
      "battery_level": 0.48,
      "code_constraints": [
        {
          "constraint_type": "name_length",
          "max_length": 9
        }
      ],
      "has_native_entry_events": true,
      "image_alt_text": "Schlage Sense Smart Deadbolt with Camelot Trim, Front",
      "image_url": "https://connect.getseam.com/_next/image?url=https://connect.getseam.com/assets/images/devices/schlage_sense-smart-deadbolt-with-camelot-trim_front.png&q=75&w=128",
      "locked": false,
      "manufacturer": "schlage",
      "model": {
        "accessory_keypad_supported": false,
        "can_connect_accessory_keypad": false,
        "display_name": "Encode",
        "has_built_in_keypad": true,
        "manufacturer_display_name": "Schlage",
        "offline_access_codes_supported": false,
        "online_access_codes_supported": true
      },
      "name": "FRONT DOOR",
      "offline_access_codes_enabled": false,
      "online": true,
      "online_access_codes_enabled": true,
      "schlage_metadata": {
        "device_id": "a69569e1-133b-4a9d-b883-018641bfe543",
        "device_name": "FRONT DOOR",
        "model": "Encode"
      },
      "serial_number": "34000000000531e0",
      "supported_code_lengths": [
        4,
        5,
        6,
        7,
        8
      ],
      "supports_backup_access_code_pool": true,
      "supports_offline_access_codes": false
    },
    "warnings": [],
    "workspace_id": "5d7f2e1a-9c8b-4f3e-8d2c-1a0b9e8f7c6d"
  }
  ```
</ResponseExample>

***

## Properties

<ResponseField name="can_configure_auto_lock" type="Boolean">
  Indicates whether the lock supports configuring automatic locking.
</ResponseField>

<ResponseField name="can_hvac_cool" type="Boolean">
  Indicates whether the thermostat supports cooling.
</ResponseField>

<ResponseField name="can_hvac_heat" type="Boolean">
  Indicates whether the thermostat supports heating.
</ResponseField>

<ResponseField name="can_hvac_heat_cool" type="Boolean">
  Indicates whether the thermostat supports simultaneous heating and cooling.
</ResponseField>

<ResponseField name="can_program_offline_access_codes" type="Boolean">
  Indicates whether the device supports programming offline access codes.
</ResponseField>

<ResponseField name="can_program_online_access_codes" type="Boolean">
  Indicates whether the device supports programming online access codes.
</ResponseField>

<ResponseField name="can_program_thermostat_programs_as_different_each_day" type="Boolean">
  Indicates whether the thermostat supports different climate programs for each day of the week.
</ResponseField>

<ResponseField name="can_program_thermostat_programs_as_same_each_day" type="Boolean">
  Indicates whether the thermostat supports a single climate program applied to every day.
</ResponseField>

<ResponseField name="can_program_thermostat_programs_as_weekday_weekend" type="Boolean">
  Indicates whether the thermostat supports weekday/weekend climate programs.
</ResponseField>

<ResponseField name="can_remotely_lock" type="Boolean">
  Indicates whether the device supports remote locking.
</ResponseField>

<ResponseField name="can_remotely_unlock" type="Boolean">
  Indicates whether the device supports remote unlocking.
</ResponseField>

<ResponseField name="can_run_thermostat_programs" type="Boolean">
  Indicates whether the thermostat supports running climate programs.
</ResponseField>

<ResponseField name="can_simulate_connection" type="Boolean">
  Indicates whether the device supports simulating connection in a sandbox.
</ResponseField>

<ResponseField name="can_simulate_disconnection" type="Boolean">
  Indicates whether the device supports simulating disconnection in a sandbox.
</ResponseField>

<ResponseField name="can_simulate_hub_connection" type="Boolean">
  Indicates whether the hub supports simulating connection in a sandbox.
</ResponseField>

<ResponseField name="can_simulate_hub_disconnection" type="Boolean">
  Indicates whether the hub supports simulating disconnection in a sandbox.
</ResponseField>

<ResponseField name="can_simulate_paid_subscription" type="Boolean">
  Indicates whether the device supports simulating a paid subscription in a sandbox.
</ResponseField>

<ResponseField name="can_simulate_removal" type="Boolean">
  Indicates whether the device supports simulating removal in a sandbox.
</ResponseField>

<ResponseField name="can_turn_off_hvac" type="Boolean">
  Indicates whether the thermostat can be turned off.
</ResponseField>

<ResponseField name="can_unlock_with_code" type="Boolean">
  Indicates whether the lock supports unlocking with an access code.
</ResponseField>

<ResponseField name="capabilities_supported" type="Array">
  Collection of capabilities that the device supports when connected to Seam. Values are `access_code`, which indicates that the device can manage and utilize digital PIN codes for secure access; `lock`, which indicates that the device controls a door locking mechanism, enabling the remote opening and closing of doors and other entry points; `noise_detection`, which indicates that the device supports monitoring and responding to ambient noise levels; `thermostat`, which indicates that the device can regulate and adjust indoor temperatures; `battery`, which indicates that the device can manage battery life and health; and `phone`, which indicates that the device is a mobile device, such as a smartphone. **Important:** Superseded by [capability flags](/capability-guides/device-and-system-capabilities#capability-flags).
</ResponseField>

<ResponseField name="connected_account_id" type="String (UUID)">
  Unique identifier for the account associated with the device.
</ResponseField>

<ResponseField name="created_at" type="String (ISO 8601)">
  Date and time at which the device object was created.
</ResponseField>

<ResponseField name="custom_metadata" type="Object">
  Set of key:value pairs. Adding custom metadata to a resource, such as a [Connect Webview](/core-concepts/connect-webviews/attaching-custom-data-to-the-connect-webview), [connected account](/core-concepts/connected-accounts/adding-custom-metadata-to-a-connected-account), or [device](/core-concepts/devices/adding-custom-metadata-to-a-device), enables you to store custom information, like customer details or internal IDs from your application.
</ResponseField>

<ResponseField name="device_id" type="String (UUID)">
  ID of the device.
</ResponseField>

<ResponseField name="device_type" type="Enum (String)">
  Type of the device.
</ResponseField>

<ResponseField name="display_name" type="String">
  Display name of the device, defaults to nickname (if it is set) or `properties.appearance.name`, otherwise. Enables administrators and users to identify the device easily, especially when there are numerous devices.
</ResponseField>

<ResponseField name="errors" type="Array">
  Array of errors associated with the device. Each error object within the array contains two fields: `error_code` and `message`. `error_code` is a string that uniquely identifies the type of error, enabling quick recognition and categorization of the issue. `message` provides a more detailed description of the error, offering insights into the issue and potentially how to rectify it.
</ResponseField>

<ResponseField name="is_managed" type="Boolean">
  Indicates whether Seam manages the device. See also [Managed and Unmanaged Devices](/core-concepts/devices/managed-and-unmanaged-devices).
</ResponseField>

<ResponseField name="nickname" type="String">
  Optional nickname to describe the device, settable through Seam.
</ResponseField>

<ResponseField name="properties" type="Object">
  Properties of the device.

  <Expandable title="properties">
    <ResponseField name="accessory_keypad" type="Object">
      Accessory keypad properties and state.

      <Expandable title="properties">
        <ResponseField name="battery" type="Object">
          Keypad battery properties.

          <Expandable title="properties">
            <ResponseField name="level" type="number">
              The level.
            </ResponseField>
          </Expandable>
        </ResponseField>

        <ResponseField name="is_connected" type="Boolean">
          Indicates if an accessory keypad is connected to the device.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="appearance" type="Object">
      Appearance-related properties, as reported by the device.

      <Expandable title="properties">
        <ResponseField name="name" type="String">
          Name of the device as seen from the provider API and application, not settable through Seam.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="battery" type="Object">
      Represents the current status of the battery charge level.

      <Expandable title="properties">
        <ResponseField name="level" type="number">
          Battery charge level as a value between 0 and 1, inclusive.
        </ResponseField>

        <ResponseField name="status" type="Enum (String)">
          Represents the current status of the battery charge level. Values are `critical`, which indicates an extremely low level, suggesting imminent shutdown or an urgent need for charging; `low`, which signifies that the battery is under the preferred threshold and should be charged soon; `good`, which denotes a satisfactory charge level, adequate for normal use without the immediate need for recharging; and `full`, which represents a battery that is fully charged, providing the maximum duration of usage.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="battery_level" type="number">
      Indicates the battery level of the device as a decimal value between 0 and 1, inclusive.
    </ResponseField>

    <ResponseField name="currently_triggering_noise_threshold_ids" type="Array">
      Array of noise threshold IDs that are currently triggering.
    </ResponseField>

    <ResponseField name="has_direct_power" type="Boolean">
      Indicates whether the device has direct power.
    </ResponseField>

    <ResponseField name="image_alt_text" type="String">
      Alt text for the device image.
    </ResponseField>

    <ResponseField name="image_url" type="String">
      Image URL for the device.
    </ResponseField>

    <ResponseField name="manufacturer" type="String">
      Manufacturer of the device. When a device, such as a smart lock, is connected through a smart hub, the manufacturer of the device might be different from that of the smart hub.
    </ResponseField>

    <ResponseField name="model" type="Object">
      Device model-related properties.

      <Expandable title="properties">
        <ResponseField name="accessory_keypad_supported" type="Boolean">
          **Deprecated**. use device.properties.model.can\_connect\_accessory\_keypad

          The accessory keypad supported.
        </ResponseField>

        <ResponseField name="can_connect_accessory_keypad" type="Boolean">
          Indicates whether the device can connect a accessory keypad.
        </ResponseField>

        <ResponseField name="display_name" type="String">
          Display name of the device model.
        </ResponseField>

        <ResponseField name="has_built_in_keypad" type="Boolean">
          Indicates whether the device has a built in accessory keypad.
        </ResponseField>

        <ResponseField name="manufacturer_display_name" type="String">
          Display name that corresponds to the manufacturer-specific terminology for the device.
        </ResponseField>

        <ResponseField name="offline_access_codes_supported" type="Boolean">
          **Deprecated**. use device.can\_program\_offline\_access\_codes.

          The offline access codes supported.
        </ResponseField>

        <ResponseField name="online_access_codes_supported" type="Boolean">
          **Deprecated**. use device.can\_program\_online\_access\_codes.

          The online access codes supported.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="name" type="String">
      **Deprecated**. use device.display\_name instead

      Name of the device.
    </ResponseField>

    <ResponseField name="noise_level_decibels" type="number">
      Indicates current noise level in decibels, if the device supports noise detection.
    </ResponseField>

    <ResponseField name="offline_access_codes_enabled" type="Boolean">
      **Deprecated**. use device.can\_program\_offline\_access\_codes

      Indicates whether it is currently possible to use offline access codes for the device.
    </ResponseField>

    <ResponseField name="online" type="Boolean">
      Indicates whether the device is online.
    </ResponseField>

    <ResponseField name="online_access_codes_enabled" type="Boolean">
      **Deprecated**. use device.can\_program\_online\_access\_codes

      Indicates whether it is currently possible to use online access codes for the device.
    </ResponseField>

    <ResponseField name="serial_number" type="String">
      Serial number of the device.
    </ResponseField>

    <ResponseField name="supports_accessory_keypad" type="Boolean">
      **Deprecated**. use device.properties.model.can\_connect\_accessory\_keypad

      The supports accessory keypad.
    </ResponseField>

    <ResponseField name="supports_offline_access_codes" type="Boolean">
      **Deprecated**. use offline\_access\_codes\_enabled

      The supports offline access codes.
    </ResponseField>

    <ResponseField name="assa_abloy_credential_service_metadata" type="Object">
      ASSA ABLOY Credential Service metadata for the phone.

      <Expandable title="properties">
        <ResponseField name="endpoints" type="Array">
          Endpoints associated with the phone.

          <Expandable title="properties">
            <ResponseField name="endpoint_id" type="String">
              ID of the associated endpoint.
            </ResponseField>

            <ResponseField name="is_active" type="Boolean">
              Indicated whether the endpoint is active.
            </ResponseField>
          </Expandable>
        </ResponseField>

        <ResponseField name="has_active_endpoint" type="Boolean">
          Indicates whether the credential service has active endpoints associated with the phone.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="salto_space_credential_service_metadata" type="Object">
      Salto Space credential service metadata for the phone.

      <Expandable title="properties">
        <ResponseField name="has_active_phone" type="Boolean">
          Indicates whether the credential service has an active associated phone.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="akiles_metadata" type="Object">
      Metadata for an Akiles device.

      <Expandable title="properties">
        <ResponseField name="_member_group_id" type="String">
          Group ID to which to add users for an Akiles device.
        </ResponseField>

        <ResponseField name="gadget_id" type="String">
          Gadget ID for an Akiles device.
        </ResponseField>

        <ResponseField name="gadget_name" type="String">
          Gadget name for an Akiles device.
        </ResponseField>

        <ResponseField name="product_name" type="String">
          Product name for an Akiles device.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="aqara_metadata" type="Object">
      Metadata for an Aqara device.

      <Expandable title="properties">
        <ResponseField name="device_name" type="String">
          Device name for an Aqara device.
        </ResponseField>

        <ResponseField name="did" type="String">
          Device ID (did) for an Aqara device.
        </ResponseField>

        <ResponseField name="firmware_version" type="String">
          Firmware version for an Aqara device.
        </ResponseField>

        <ResponseField name="model" type="String">
          Model identifier for an Aqara device.
        </ResponseField>

        <ResponseField name="model_type" type="number">
          Model type for an Aqara device.
        </ResponseField>

        <ResponseField name="parent_did" type="String">
          Parent gateway device ID for an Aqara device.
        </ResponseField>

        <ResponseField name="position_id" type="String">
          Position (room) ID for an Aqara device.
        </ResponseField>

        <ResponseField name="time_zone" type="String">
          Time zone reported for an Aqara device (e.g. GMT-07:00).
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="assa_abloy_vostio_metadata" type="Object">
      Metadata for an ASSA ABLOY Vostio system.

      <Expandable title="properties">
        <ResponseField name="encoder_name" type="String">
          Encoder name for an ASSA ABLOY Vostio system.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="august_metadata" type="Object">
      Metadata for an August device.

      <Expandable title="properties">
        <ResponseField name="has_keypad" type="Boolean">
          Indicates whether an August device has a keypad.
        </ResponseField>

        <ResponseField name="house_id" type="String">
          House ID for an August device.
        </ResponseField>

        <ResponseField name="house_name" type="String">
          House name for an August device.
        </ResponseField>

        <ResponseField name="keypad_battery_level" type="String">
          Keypad battery level for an August device.
        </ResponseField>

        <ResponseField name="lock_id" type="String">
          Lock ID for an August device.
        </ResponseField>

        <ResponseField name="lock_name" type="String">
          Lock name for an August device.
        </ResponseField>

        <ResponseField name="model" type="String">
          Model for an August device.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="avigilon_alta_metadata" type="Object">
      Metadata for an Avigilon Alta system.

      <Expandable title="properties">
        <ResponseField name="entry_name" type="String">
          Entry name for an Avigilon Alta system.
        </ResponseField>

        <ResponseField name="entry_relays_total_count" type="number">
          Total count of entry relays for an Avigilon Alta system.
        </ResponseField>

        <ResponseField name="org_name" type="String">
          Organization name for an Avigilon Alta system.
        </ResponseField>

        <ResponseField name="site_id" type="number">
          Site ID for an Avigilon Alta system.
        </ResponseField>

        <ResponseField name="site_name" type="String">
          Site name for an Avigilon Alta system.
        </ResponseField>

        <ResponseField name="zone_id" type="number">
          Zone ID for an Avigilon Alta system.
        </ResponseField>

        <ResponseField name="zone_name" type="String">
          Zone name for an Avigilon Alta system.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="brivo_metadata" type="Object">
      Metadata for a Brivo device.

      <Expandable title="properties">
        <ResponseField name="activation_enabled" type="Boolean">
          Indicates whether the Brivo access point has activation (remote unlock) enabled.
        </ResponseField>

        <ResponseField name="device_name" type="String">
          Device name for a Brivo device.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="controlbyweb_metadata" type="Object">
      Metadata for a ControlByWeb device.

      <Expandable title="properties">
        <ResponseField name="device_id" type="String">
          Device ID for a ControlByWeb device.
        </ResponseField>

        <ResponseField name="device_name" type="String">
          Device name for a ControlByWeb device.
        </ResponseField>

        <ResponseField name="relay_name" type="String">
          Relay name for a ControlByWeb device.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="dormakaba_oracode_metadata" type="Object">
      Metadata for a dormakaba Oracode device.

      <Expandable title="properties">
        <ResponseField name="device_id" type="String">
          Device ID for a dormakaba Oracode device.
        </ResponseField>

        <ResponseField name="door_id" type="number">
          Door ID for a dormakaba Oracode device.
        </ResponseField>

        <ResponseField name="door_is_wireless" type="Boolean">
          Indicates whether a door is wireless for a dormakaba Oracode device.
        </ResponseField>

        <ResponseField name="door_name" type="String">
          Door name for a dormakaba Oracode device.
        </ResponseField>

        <ResponseField name="iana_timezone" type="String">
          IANA time zone for a dormakaba Oracode device.
        </ResponseField>

        <ResponseField name="predefined_time_slots" type="Array">
          Predefined time slots for a dormakaba Oracode device.

          <Expandable title="properties">
            <ResponseField name="check_in_time" type="String">
              Check in time for a time slot for a dormakaba Oracode device.
            </ResponseField>

            <ResponseField name="check_out_time" type="String">
              Checkout time for a time slot for a dormakaba Oracode device.
            </ResponseField>

            <ResponseField name="dormakaba_oracode_user_level_id" type="String (UUID)">
              ID of a user level for a dormakaba Oracode device.
            </ResponseField>

            <ResponseField name="dormakaba_oracode_user_level_prefix" type="number">
              Prefix for a user level for a dormakaba Oracode device.
            </ResponseField>

            <ResponseField name="is_24_hour" type="Boolean">
              Indicates whether a time slot for a dormakaba Oracode device is a 24-hour time slot.
            </ResponseField>

            <ResponseField name="is_biweekly_mode" type="Boolean">
              Indicates whether a time slot for a dormakaba Oracode device is in biweekly mode.
            </ResponseField>

            <ResponseField name="is_master" type="Boolean">
              Indicates whether a time slot for a dormakaba Oracode device is a master time slot.
            </ResponseField>

            <ResponseField name="is_one_shot" type="Boolean">
              Indicates whether a time slot for a dormakaba Oracode device is a one-shot time slot.
            </ResponseField>

            <ResponseField name="name" type="String">
              Name of a time slot for a dormakaba Oracode device.
            </ResponseField>

            <ResponseField name="prefix" type="number">
              Prefix for a time slot for a dormakaba Oracode device.
            </ResponseField>
          </Expandable>
        </ResponseField>

        <ResponseField name="site_id" type="number">
          **Deprecated**. Previously marked as "@DEPRECATED."

          Site ID for a dormakaba Oracode device.
        </ResponseField>

        <ResponseField name="site_name" type="String">
          Site name for a dormakaba Oracode device.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="ecobee_metadata" type="Object">
      Metadata for an ecobee device.

      <Expandable title="properties">
        <ResponseField name="device_name" type="String">
          Device name for an ecobee device.
        </ResponseField>

        <ResponseField name="ecobee_device_id" type="String">
          Device ID for an ecobee device.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="four_suites_metadata" type="Object">
      Metadata for a 4SUITES device.

      <Expandable title="properties">
        <ResponseField name="device_id" type="number">
          Device ID for a 4SUITES device.
        </ResponseField>

        <ResponseField name="device_name" type="String">
          Device name for a 4SUITES device.
        </ResponseField>

        <ResponseField name="reclose_delay_in_seconds" type="number">
          Reclose delay, in seconds, for a 4SUITES device.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="genie_metadata" type="Object">
      Metadata for a Genie device.

      <Expandable title="properties">
        <ResponseField name="device_name" type="String">
          Lock name for a Genie device.
        </ResponseField>

        <ResponseField name="door_name" type="String">
          Door name for a Genie device.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="honeywell_resideo_metadata" type="Object">
      Metadata for a Honeywell Resideo device.

      <Expandable title="properties">
        <ResponseField name="device_name" type="String">
          Device name for a Honeywell Resideo device.
        </ResponseField>

        <ResponseField name="honeywell_resideo_device_id" type="String">
          Device ID for a Honeywell Resideo device.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="igloo_metadata" type="Object">
      Metadata for an igloo device.

      <Expandable title="properties">
        <ResponseField name="bridge_id" type="String">
          Bridge ID for an igloo device.
        </ResponseField>

        <ResponseField name="device_id" type="String">
          Device ID for an igloo device.
        </ResponseField>

        <ResponseField name="model" type="String">
          Model for an igloo device.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="igloohome_metadata" type="Object">
      Metadata for an igloohome device.

      <Expandable title="properties">
        <ResponseField name="bridge_id" type="String">
          Bridge ID for an igloohome device.
        </ResponseField>

        <ResponseField name="bridge_name" type="String">
          Bridge name for an igloohome device.
        </ResponseField>

        <ResponseField name="device_id" type="String">
          Device ID for an igloohome device.
        </ResponseField>

        <ResponseField name="device_name" type="String">
          Device name for an igloohome device.
        </ResponseField>

        <ResponseField name="is_accessory_keypad_linked_to_bridge" type="Boolean">
          Indicates whether a keypad is linked to a bridge for an igloohome device.
        </ResponseField>

        <ResponseField name="keypad_id" type="String">
          Keypad ID for an igloohome device.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="keynest_metadata" type="Object">
      Metadata for a KeyNest device.

      <Expandable title="properties">
        <ResponseField name="address" type="String">
          Address for a KeyNest device.
        </ResponseField>

        <ResponseField name="current_or_last_store_id" type="number">
          Current or last store ID for a KeyNest device.
        </ResponseField>

        <ResponseField name="current_status" type="String">
          Current status for a KeyNest device.
        </ResponseField>

        <ResponseField name="current_user_company" type="String">
          Current user company for a KeyNest device.
        </ResponseField>

        <ResponseField name="current_user_email" type="String">
          Current user email for a KeyNest device.
        </ResponseField>

        <ResponseField name="current_user_name" type="String">
          Current user name for a KeyNest device.
        </ResponseField>

        <ResponseField name="current_user_phone_number" type="String">
          Current user phone number for a KeyNest device.
        </ResponseField>

        <ResponseField name="default_office_id" type="number">
          Default office ID for a KeyNest device.
        </ResponseField>

        <ResponseField name="device_name" type="String">
          Device name for a KeyNest device.
        </ResponseField>

        <ResponseField name="fob_id" type="number">
          Fob ID for a KeyNest device.
        </ResponseField>

        <ResponseField name="handover_method" type="String">
          Handover method for a KeyNest device.
        </ResponseField>

        <ResponseField name="has_photo" type="Boolean">
          Whether the KeyNest device has a photo.
        </ResponseField>

        <ResponseField name="is_quadient_locker" type="Boolean">
          Whether the key is in a locker that does not support the access codes API.
        </ResponseField>

        <ResponseField name="key_id" type="String">
          Key ID for a KeyNest device.
        </ResponseField>

        <ResponseField name="key_notes" type="String">
          Key notes for a KeyNest device.
        </ResponseField>

        <ResponseField name="keynest_app_user" type="String">
          KeyNest app user for a KeyNest device.
        </ResponseField>

        <ResponseField name="last_movement" type="String">
          Last movement timestamp for a KeyNest device.
        </ResponseField>

        <ResponseField name="property_id" type="String">
          Property ID for a KeyNest device.
        </ResponseField>

        <ResponseField name="property_postcode" type="String">
          Property postcode for a KeyNest device.
        </ResponseField>

        <ResponseField name="status_type" type="String">
          Status type for a KeyNest device.
        </ResponseField>

        <ResponseField name="subscription_plan" type="String">
          Subscription plan for a KeyNest device.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="kisi_metadata" type="Object">
      Metadata for a Kisi device.

      <Expandable title="properties">
        <ResponseField name="description" type="String">
          Description for a Kisi device.
        </ResponseField>

        <ResponseField name="lock_id" type="number">
          Lock ID for a Kisi device.
        </ResponseField>

        <ResponseField name="lock_name" type="String">
          Lock name for a Kisi device.
        </ResponseField>

        <ResponseField name="place_name" type="String">
          Place name for a Kisi device.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="korelock_metadata" type="Object">
      Metadata for a Korelock device.

      <Expandable title="properties">
        <ResponseField name="device_id" type="String">
          Device ID for a Korelock device.
        </ResponseField>

        <ResponseField name="device_name" type="String">
          Device name for a Korelock device.
        </ResponseField>

        <ResponseField name="firmware_version" type="String">
          Firmware version for a Korelock device.
        </ResponseField>

        <ResponseField name="location_id" type="String">
          Location ID for a Korelock device. Required for timebound access codes.
        </ResponseField>

        <ResponseField name="model_code" type="String">
          Model code for a Korelock device.
        </ResponseField>

        <ResponseField name="serial_number" type="String">
          Serial number for a Korelock device.
        </ResponseField>

        <ResponseField name="wifi_signal_strength" type="number">
          WiFi signal strength (0-1) for a Korelock device.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="kwikset_metadata" type="Object">
      Metadata for a Kwikset device.

      <Expandable title="properties">
        <ResponseField name="device_id" type="String">
          Device ID for a Kwikset device.
        </ResponseField>

        <ResponseField name="device_name" type="String">
          Device name for a Kwikset device.
        </ResponseField>

        <ResponseField name="model_number" type="String">
          Model number for a Kwikset device.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="lockly_metadata" type="Object">
      Metadata for a Lockly device.

      <Expandable title="properties">
        <ResponseField name="device_id" type="String">
          Device ID for a Lockly device.
        </ResponseField>

        <ResponseField name="device_name" type="String">
          Device name for a Lockly device.
        </ResponseField>

        <ResponseField name="model" type="String">
          Model for a Lockly device.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="minut_metadata" type="Object">
      Metadata for a Minut device.

      <Expandable title="properties">
        <ResponseField name="device_id" type="String">
          Device ID for a Minut device.
        </ResponseField>

        <ResponseField name="device_name" type="String">
          Device name for a Minut device.
        </ResponseField>

        <ResponseField name="latest_sensor_values" type="Object">
          Latest sensor values for a Minut device.

          <Expandable title="properties">
            <ResponseField name="accelerometer_z" type="Object">
              Latest accelerometer Z-axis reading for a Minut device.

              <Expandable title="properties">
                <ResponseField name="time" type="String">
                  Time of latest accelerometer Z-axis reading for a Minut device.
                </ResponseField>

                <ResponseField name="value" type="number">
                  Value of latest accelerometer Z-axis reading for a Minut device.
                </ResponseField>
              </Expandable>
            </ResponseField>

            <ResponseField name="humidity" type="Object">
              Latest humidity reading for a Minut device.

              <Expandable title="properties">
                <ResponseField name="time" type="String">
                  Time of latest humidity reading for a Minut device.
                </ResponseField>

                <ResponseField name="value" type="number">
                  Value of latest humidity reading for a Minut device.
                </ResponseField>
              </Expandable>
            </ResponseField>

            <ResponseField name="pressure" type="Object">
              Latest pressure reading for a Minut device.

              <Expandable title="properties">
                <ResponseField name="time" type="String">
                  Time of latest pressure reading for a Minut device.
                </ResponseField>

                <ResponseField name="value" type="number">
                  Value of latest pressure reading for a Minut device.
                </ResponseField>
              </Expandable>
            </ResponseField>

            <ResponseField name="sound" type="Object">
              Latest sound reading for a Minut device.

              <Expandable title="properties">
                <ResponseField name="time" type="String">
                  Time of latest sound reading for a Minut device.
                </ResponseField>

                <ResponseField name="value" type="number">
                  Value of latest sound reading for a Minut device.
                </ResponseField>
              </Expandable>
            </ResponseField>

            <ResponseField name="temperature" type="Object">
              Latest temperature reading for a Minut device.

              <Expandable title="properties">
                <ResponseField name="time" type="String">
                  Time of latest temperature reading for a Minut device.
                </ResponseField>

                <ResponseField name="value" type="number">
                  Value of latest temperature reading for a Minut device.
                </ResponseField>
              </Expandable>
            </ResponseField>
          </Expandable>
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="nest_metadata" type="Object">
      Metadata for a Google Nest device.

      <Expandable title="properties">
        <ResponseField name="device_custom_name" type="String">
          Custom device name for a Google Nest device. The device owner sets this value.
        </ResponseField>

        <ResponseField name="device_name" type="String">
          Device name for a Google Nest device. Google sets this value.
        </ResponseField>

        <ResponseField name="display_name" type="String">
          Display name for a Google Nest device.
        </ResponseField>

        <ResponseField name="nest_device_id" type="String">
          Device ID for a Google Nest device.
        </ResponseField>

        <ResponseField name="nest_structure_id" type="String">
          ID of the Google Nest structure containing the device.
        </ResponseField>

        <ResponseField name="structure_name" type="String">
          Name of the Google Nest structure containing the device. The device owner sets this value.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="noiseaware_metadata" type="Object">
      Metadata for a NoiseAware device.

      <Expandable title="properties">
        <ResponseField name="device_id" type="String">
          Device ID for a NoiseAware device.
        </ResponseField>

        <ResponseField name="device_model" type="Enum (String)">
          Device model for a NoiseAware device.
        </ResponseField>

        <ResponseField name="device_name" type="String">
          Device name for a NoiseAware device.
        </ResponseField>

        <ResponseField name="noise_level_decibel" type="number">
          Noise level, in decibels, for a NoiseAware device.
        </ResponseField>

        <ResponseField name="noise_level_nrs" type="number">
          Noise level, expressed as a Noise Risk Score (NRS), for a NoiseAware device.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="nuki_metadata" type="Object">
      Metadata for a Nuki device.

      <Expandable title="properties">
        <ResponseField name="device_id" type="String">
          Device ID for a Nuki device.
        </ResponseField>

        <ResponseField name="device_name" type="String">
          Device name for a Nuki device.
        </ResponseField>

        <ResponseField name="keypad_2_paired" type="Boolean">
          Indicates whether keypad 2 is paired for a Nuki device.
        </ResponseField>

        <ResponseField name="keypad_battery_critical" type="Boolean">
          Indicates whether the keypad battery is in a critical state for a Nuki device.
        </ResponseField>

        <ResponseField name="keypad_paired" type="Boolean">
          Indicates whether the keypad is paired for a Nuki device.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="omnitec_metadata" type="Object">
      Metadata for an Omnitec device.

      <Expandable title="properties">
        <ResponseField name="has_gateway" type="Boolean">
          Whether the Omnitec lock has a connected gateway for remote operations.
        </ResponseField>

        <ResponseField name="lock_alias" type="String">
          Operator-assigned alias for an Omnitec device.
        </ResponseField>

        <ResponseField name="lock_id" type="number">
          Lock ID for an Omnitec device.
        </ResponseField>

        <ResponseField name="lock_mac" type="String">
          Bluetooth MAC address for an Omnitec device.
        </ResponseField>

        <ResponseField name="lock_name" type="String">
          Lock name for an Omnitec device.
        </ResponseField>

        <ResponseField name="time_zone" type="String">
          IANA time zone for the Omnitec device, used to schedule time-bound access codes at the correct local time (accounting for DST).
        </ResponseField>

        <ResponseField name="timezone_raw_offset_ms" type="number">
          Static UTC offset of the Omnitec lock in milliseconds. Does not account for DST.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="ring_metadata" type="Object">
      Metadata for a Ring device.

      <Expandable title="properties">
        <ResponseField name="device_id" type="String">
          Device ID for a Ring device.
        </ResponseField>

        <ResponseField name="device_name" type="String">
          Device name for a Ring device.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="salto_ks_metadata" type="Object">
      Metadata for a Salto KS device.

      <Expandable title="properties">
        <ResponseField name="battery_level" type="String">
          Battery level for a Salto KS device.
        </ResponseField>

        <ResponseField name="customer_reference" type="String">
          Customer reference for a Salto KS device.
        </ResponseField>

        <ResponseField name="has_custom_pin_subscription" type="Boolean">
          Indicates whether the site has a Salto KS subscription that supports custom PINs.
        </ResponseField>

        <ResponseField name="lock_id" type="String">
          Lock ID for a Salto KS device.
        </ResponseField>

        <ResponseField name="lock_type" type="String">
          Lock type for a Salto KS device.
        </ResponseField>

        <ResponseField name="locked_state" type="String">
          Locked state for a Salto KS device.
        </ResponseField>

        <ResponseField name="model" type="String">
          Model for a Salto KS device.
        </ResponseField>

        <ResponseField name="site_id" type="String">
          Site ID for the Salto KS site to which the device belongs.
        </ResponseField>

        <ResponseField name="site_name" type="String">
          Site name for the Salto KS site to which the device belongs.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="salto_metadata" type="Object">
      **Deprecated**. Use `salto_ks_metadata` instead.

      Metada for a Salto device.

      <Expandable title="properties">
        <ResponseField name="battery_level" type="String">
          Battery level for a Salto device.
        </ResponseField>

        <ResponseField name="customer_reference" type="String">
          Customer reference for a Salto device.
        </ResponseField>

        <ResponseField name="lock_id" type="String">
          Lock ID for a Salto device.
        </ResponseField>

        <ResponseField name="lock_type" type="String">
          Lock type for a Salto device.
        </ResponseField>

        <ResponseField name="locked_state" type="String">
          Locked state for a Salto device.
        </ResponseField>

        <ResponseField name="model" type="String">
          Model for a Salto device.
        </ResponseField>

        <ResponseField name="site_id" type="String">
          Site ID for the Salto KS site to which the device belongs.
        </ResponseField>

        <ResponseField name="site_name" type="String">
          Site name for the Salto KS site to which the device belongs.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="schlage_metadata" type="Object">
      Metadata for a Schlage device.

      <Expandable title="properties">
        <ResponseField name="device_id" type="String">
          Device ID for a Schlage device.
        </ResponseField>

        <ResponseField name="device_name" type="String">
          Device name for a Schlage device.
        </ResponseField>

        <ResponseField name="model" type="String">
          Model for a Schlage device.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="seam_bridge_metadata" type="Object">
      Metadata for Seam Bridge.

      <Expandable title="properties">
        <ResponseField name="device_num" type="number">
          Device number for Seam Bridge.
        </ResponseField>

        <ResponseField name="name" type="String">
          Name for Seam Bridge.
        </ResponseField>

        <ResponseField name="unlock_method" type="Enum (String)">
          Unlock method for Seam Bridge.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="sensi_metadata" type="Object">
      Metadata for a Sensi device.

      <Expandable title="properties">
        <ResponseField name="device_id" type="String">
          Device ID for a Sensi device.
        </ResponseField>

        <ResponseField name="device_name" type="String">
          Device name for a Sensi device.
        </ResponseField>

        <ResponseField name="dual_setpoints_not_supported" type="Boolean">
          Set to true when the device does not support the /dual-setpoints API endpoint.
        </ResponseField>

        <ResponseField name="enforced_setpoint_range_celsius" type="Array">
          Enforced setpoint range in Celsius for a Sensi device, derived from an OutOfRange API error.
        </ResponseField>

        <ResponseField name="product_type" type="String">
          Product type for a Sensi device.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="smartthings_metadata" type="Object">
      Metadata for a SmartThings device.

      <Expandable title="properties">
        <ResponseField name="device_id" type="String">
          Device ID for a SmartThings device.
        </ResponseField>

        <ResponseField name="device_name" type="String">
          Device name for a SmartThings device.
        </ResponseField>

        <ResponseField name="location_id" type="String">
          Location ID for a SmartThings device.
        </ResponseField>

        <ResponseField name="model" type="String">
          Model for a SmartThings device.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="tado_metadata" type="Object">
      Metadata for a tado° device.

      <Expandable title="properties">
        <ResponseField name="device_type" type="String">
          Device type for a tado° device.
        </ResponseField>

        <ResponseField name="serial_no" type="String">
          Serial number for a tado° device.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="tedee_metadata" type="Object">
      Metadata for a Tedee device.

      <Expandable title="properties">
        <ResponseField name="bridge_id" type="number">
          Bridge ID for a Tedee device.
        </ResponseField>

        <ResponseField name="bridge_name" type="String">
          Bridge name for a Tedee device.
        </ResponseField>

        <ResponseField name="device_id" type="number">
          Device ID for a Tedee device.
        </ResponseField>

        <ResponseField name="device_model" type="String">
          Device model for a Tedee device.
        </ResponseField>

        <ResponseField name="device_name" type="String">
          Device name for a Tedee device.
        </ResponseField>

        <ResponseField name="keypad_id" type="number">
          Keypad ID for a Tedee device.
        </ResponseField>

        <ResponseField name="serial_number" type="String">
          Serial number for a Tedee device.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="ttlock_metadata" type="Object">
      Metadata for a TTLock device.

      <Expandable title="properties">
        <ResponseField name="feature_value" type="String">
          Feature value for a TTLock device.
        </ResponseField>

        <ResponseField name="features" type="Object">
          Features for a TTLock device.

          <Expandable title="properties">
            <ResponseField name="auto_lock_time_config" type="Boolean">
              Indicates whether a TTLock device supports auto-lock time configuration.
            </ResponseField>

            <ResponseField name="incomplete_keyboard_passcode" type="Boolean">
              Indicates whether a TTLock device supports an incomplete keyboard passcode.
            </ResponseField>

            <ResponseField name="lock_command" type="Boolean">
              Indicates whether a TTLock device supports the lock command.
            </ResponseField>

            <ResponseField name="passcode" type="Boolean">
              Indicates whether a TTLock device supports a passcode.
            </ResponseField>

            <ResponseField name="passcode_management" type="Boolean">
              Indicates whether a TTLock device supports passcode management.
            </ResponseField>

            <ResponseField name="unlock_via_gateway" type="Boolean">
              Indicates whether a TTLock device supports unlock via gateway.
            </ResponseField>

            <ResponseField name="wifi" type="Boolean">
              Indicates whether a TTLock device supports Wi-Fi.
            </ResponseField>
          </Expandable>
        </ResponseField>

        <ResponseField name="has_gateway" type="Boolean">
          Indicates whether a TTLock device has a gateway.
        </ResponseField>

        <ResponseField name="lock_alias" type="String">
          Lock alias for a TTLock device.
        </ResponseField>

        <ResponseField name="lock_id" type="number">
          Lock ID for a TTLock device.
        </ResponseField>

        <ResponseField name="timezone_raw_offset_ms" type="number">
          Lock-side timezone offset in milliseconds east of UTC, as configured in the TTLock app. Source of truth for the lock's wall-clock interpretation of access code start/end times — a misconfigured value here is the typical cause of customer "codes offset by N hours" reports. Diagnostic only; Seam does not convert times based on this value.
        </ResponseField>

        <ResponseField name="wireless_keypads" type="Array">
          Wireless keypads for a TTLock device.

          <Expandable title="properties">
            <ResponseField name="wireless_keypad_id" type="number">
              ID for a wireless keypad for a TTLock device.
            </ResponseField>

            <ResponseField name="wireless_keypad_name" type="String">
              Name for a wireless keypad for a TTLock device.
            </ResponseField>
          </Expandable>
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="two_n_metadata" type="Object">
      Metadata for a 2N device.

      <Expandable title="properties">
        <ResponseField name="device_id" type="number">
          Device ID for a 2N device.
        </ResponseField>

        <ResponseField name="device_name" type="String">
          Device name for a 2N device.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="ultraloq_metadata" type="Object">
      Metadata for an Ultraloq device.

      <Expandable title="properties">
        <ResponseField name="device_id" type="String">
          Device ID for an Ultraloq device.
        </ResponseField>

        <ResponseField name="device_name" type="String">
          Device name for an Ultraloq device.
        </ResponseField>

        <ResponseField name="device_type" type="String">
          Device type for an Ultraloq device.
        </ResponseField>

        <ResponseField name="time_zone" type="String">
          IANA timezone for the Ultraloq device.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="visionline_metadata" type="Object">
      Metadata for an ASSA ABLOY Visionline system.

      <Expandable title="properties">
        <ResponseField name="encoder_id" type="String">
          Encoder ID for an ASSA ABLOY Visionline system.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="wyze_metadata" type="Object">
      Metadata for a Wyze device.

      <Expandable title="properties">
        <ResponseField name="device_id" type="String">
          Device ID for a Wyze device.
        </ResponseField>

        <ResponseField name="device_info_model" type="String">
          Device information model for a Wyze device.
        </ResponseField>

        <ResponseField name="device_name" type="String">
          Device name for a Wyze device.
        </ResponseField>

        <ResponseField name="keypad_uuid" type="String">
          Keypad UUID for a Wyze device.
        </ResponseField>

        <ResponseField name="locker_status_hardlock" type="number">
          Locker status (hardlock) for a Wyze device.
        </ResponseField>

        <ResponseField name="product_model" type="String">
          Product model for a Wyze device.
        </ResponseField>

        <ResponseField name="product_name" type="String">
          Product name for a Wyze device.
        </ResponseField>

        <ResponseField name="product_type" type="String">
          Product type for a Wyze device.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="auto_lock_delay_seconds" type="number">
      The delay in seconds before the lock automatically locks after being unlocked.
    </ResponseField>

    <ResponseField name="auto_lock_enabled" type="Boolean">
      Indicates whether automatic locking is enabled.
    </ResponseField>

    <ResponseField name="backup_access_code_pool_enabled" type="Boolean">
      Indicates whether the [backup access code pool](/low-level-apis/smart-locks/access-codes/backup-access-codes) is currently enabled for the device. To disable it, set this to `false` using [/devices/update](/api/devices/update).
    </ResponseField>

    <ResponseField name="code_constraints" type="Array">
      Constraints on access codes for the device. Seam represents each constraint as an object with a `constraint_type` property. Depending on the constraint type, there may also be additional properties. Note that some constraints are manufacturer- or device-specific.

      <Expandable title="properties">
        <ResponseField name="constraint_type" type="Enum (String)">
          The constraint type.
        </ResponseField>

        <ResponseField name="max_length" type="number">
          Maximum name length constraint for access codes.
        </ResponseField>

        <ResponseField name="min_length" type="number">
          Minimum name length constraint for access codes.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="door_open" type="Boolean">
      Indicates whether the door is open.
    </ResponseField>

    <ResponseField name="has_native_entry_events" type="Boolean">
      Indicates whether the device supports native entry events.
    </ResponseField>

    <ResponseField name="keypad_battery" type="Object">
      Keypad battery status.

      <Expandable title="properties">
        <ResponseField name="level" type="number">
          Keypad battery charge level.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="locked" type="Boolean">
      Indicates whether the lock is locked.
    </ResponseField>

    <ResponseField name="max_active_codes_supported" type="number">
      Maximum number of active access codes that the device supports.
    </ResponseField>

    <ResponseField name="offline_time_frame_options" type="Array">
      Time frames that may be requested when creating an offline access code, expressed as a list of options. The caller picks one option (by matching the requested duration when the options' duration ranges do not overlap, or by `display_name` when they do) and satisfies that one option's rules. When `undefined`, any time frame works.

      <Expandable title="properties">
        <ResponseField name="display_name" type="String">
          Label for this option. For a single-option device, the product name (for example, `algoPIN` or `SmartPIN`); for a multi-option device, a label that distinguishes it (for example, `Hourly` or `Fixed start times`).
        </ResponseField>

        <ResponseField name="end_date_recurrence_rule" type="String">
          iCalendar recurrence rule (RRULE) that the end date must fall on. Constrains which calendar dates are selectable, independent of the time-of-day rules.
        </ResponseField>

        <ResponseField name="matching_start_end_time" type="Boolean">
          When `true`, the start and end must fall at the same time of day (the caller picks which). Mutually exclusive with `time_pairs`.
        </ResponseField>

        <ResponseField name="max_duration" type="String">
          Maximum duration this option covers, as an ISO 8601 duration (for example, `PT672H` or `P367D`). Omitted when there is no maximum.
        </ResponseField>

        <ResponseField name="min_duration" type="String">
          Minimum duration this option covers, as an ISO 8601 duration (for example, `PT1H` or `P29D`). Omitted when there is no minimum.
        </ResponseField>

        <ResponseField name="start_date_recurrence_rule" type="String">
          iCalendar recurrence rule (RRULE) that the start date must fall on (for example, `FREQ=MONTHLY;BYDAY=1MO,3MO`). Constrains which calendar dates are selectable, independent of the time-of-day rules.
        </ResponseField>

        <ResponseField name="time_pairs" type="Array">
          Fixed start/end time pairings the caller chooses from. Mutually exclusive with `matching_start_end_time`.

          <Expandable title="properties">
            <ResponseField name="display_name" type="String">
              Label for the start/end time pairing.
            </ResponseField>

            <ResponseField name="end_time" type="String">
              End time of day as a 24-hour `HH:MM` value, interpreted in the option's `time_zone`. An `end_time` earlier on the clock than `start_time` means the end falls on a later date.
            </ResponseField>

            <ResponseField name="start_time" type="String">
              Start time of day as a 24-hour `HH:MM` value, interpreted in the option's `time_zone`.
            </ResponseField>
          </Expandable>
        </ResponseField>

        <ResponseField name="time_zone" type="String">
          IANA time zone for interpreting `time_pairs` and the date recurrence rules. Present only when the option fixes times or dates.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="online_time_frame_options" type="Array">
      Time frames that may be requested when creating an online access code, expressed as a list of options. The caller picks one option (by matching the requested duration when the options' duration ranges do not overlap, or by `display_name` when they do) and satisfies that one option's rules. When `undefined`, any time frame works.

      <Expandable title="properties">
        <ResponseField name="display_name" type="String">
          Label for this option. For a single-option device, the product name (for example, `algoPIN` or `SmartPIN`); for a multi-option device, a label that distinguishes it (for example, `Hourly` or `Fixed start times`).
        </ResponseField>

        <ResponseField name="end_date_recurrence_rule" type="String">
          iCalendar recurrence rule (RRULE) that the end date must fall on. Constrains which calendar dates are selectable, independent of the time-of-day rules.
        </ResponseField>

        <ResponseField name="matching_start_end_time" type="Boolean">
          When `true`, the start and end must fall at the same time of day (the caller picks which). Mutually exclusive with `time_pairs`.
        </ResponseField>

        <ResponseField name="max_duration" type="String">
          Maximum duration this option covers, as an ISO 8601 duration (for example, `PT672H` or `P367D`). Omitted when there is no maximum.
        </ResponseField>

        <ResponseField name="min_duration" type="String">
          Minimum duration this option covers, as an ISO 8601 duration (for example, `PT1H` or `P29D`). Omitted when there is no minimum.
        </ResponseField>

        <ResponseField name="start_date_recurrence_rule" type="String">
          iCalendar recurrence rule (RRULE) that the start date must fall on (for example, `FREQ=MONTHLY;BYDAY=1MO,3MO`). Constrains which calendar dates are selectable, independent of the time-of-day rules.
        </ResponseField>

        <ResponseField name="time_pairs" type="Array">
          Fixed start/end time pairings the caller chooses from. Mutually exclusive with `matching_start_end_time`.

          <Expandable title="properties">
            <ResponseField name="display_name" type="String">
              Label for the start/end time pairing.
            </ResponseField>

            <ResponseField name="end_time" type="String">
              End time of day as a 24-hour `HH:MM` value, interpreted in the option's `time_zone`. An `end_time` earlier on the clock than `start_time` means the end falls on a later date.
            </ResponseField>

            <ResponseField name="start_time" type="String">
              Start time of day as a 24-hour `HH:MM` value, interpreted in the option's `time_zone`.
            </ResponseField>
          </Expandable>
        </ResponseField>

        <ResponseField name="time_zone" type="String">
          IANA time zone for interpreting `time_pairs` and the date recurrence rules. Present only when the option fixes times or dates.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="supported_code_lengths" type="Array">
      Supported code lengths for access codes.
    </ResponseField>

    <ResponseField name="supports_backup_access_code_pool" type="Boolean">
      Indicates whether the device supports a [backup access code pool](/low-level-apis/smart-locks/access-codes/backup-access-codes).
    </ResponseField>

    <ResponseField name="active_thermostat_schedule" type="Object">
      **Deprecated**. Use `active_thermostat_schedule_id` with `/thermostats/schedules/get` instead.

      Active [thermostat schedule](/capability-guides/thermostats/creating-and-managing-thermostat-schedules).

      <Expandable title="properties">
        <ResponseField name="climate_preset_key" type="String">
          Key of the [climate preset](/capability-guides/thermostats/creating-and-managing-climate-presets) to use for the [thermostat schedule](/capability-guides/thermostats/creating-and-managing-thermostat-schedules).
        </ResponseField>

        <ResponseField name="created_at" type="String (ISO 8601)">
          Date and time at which the [thermostat schedule](/capability-guides/thermostats/creating-and-managing-thermostat-schedules) was created.
        </ResponseField>

        <ResponseField name="device_id" type="String (UUID)">
          ID of the desired [thermostat](/capability-guides/thermostats) device.
        </ResponseField>

        <ResponseField name="ends_at" type="String (ISO 8601)">
          Date and time at which the [thermostat schedule](/capability-guides/thermostats/creating-and-managing-thermostat-schedules) ends, in [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) format.
        </ResponseField>

        <ResponseField name="errors" type="Array">
          Errors associated with the [thermostat schedule](/capability-guides/thermostats/creating-and-managing-thermostat-schedules).

          <Expandable title="properties">
            <ResponseField name="created_at" type="String (ISO 8601)">
              Date and time at which Seam created the error.
            </ResponseField>

            <ResponseField name="error_code" type="String">
              Unique identifier of the type of error. Enables quick recognition and categorization of the issue.
            </ResponseField>

            <ResponseField name="message" type="String">
              Detailed description of the error. Provides insights into the issue and potentially how to rectify it.
            </ResponseField>
          </Expandable>
        </ResponseField>

        <ResponseField name="is_override_allowed" type="Boolean">
          Indicates whether a person at the thermostat can change the thermostat's settings after the [thermostat schedule](/capability-guides/thermostats/creating-and-managing-thermostat-schedules) starts.
        </ResponseField>

        <ResponseField name="max_override_period_minutes" type="number">
          Number of minutes for which a person at the thermostat can change the thermostat's settings after the activation of the scheduled [climate preset](/capability-guides/thermostats/creating-and-managing-climate-presets). See also [Specifying Manual Override Permissions](/capability-guides/thermostats/creating-and-managing-thermostat-schedules#specifying-manual-override-permissions).
        </ResponseField>

        <ResponseField name="name" type="String">
          User-friendly name to identify the [thermostat schedule](/capability-guides/thermostats/creating-and-managing-thermostat-schedules).
        </ResponseField>

        <ResponseField name="starts_at" type="String (ISO 8601)">
          Date and time at which the [thermostat schedule](/capability-guides/thermostats/creating-and-managing-thermostat-schedules) starts, in [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) format.
        </ResponseField>

        <ResponseField name="thermostat_schedule_id" type="String (UUID)">
          ID of the [thermostat schedule](/capability-guides/thermostats/creating-and-managing-thermostat-schedules).
        </ResponseField>

        <ResponseField name="workspace_id" type="String (UUID)">
          ID of the workspace that contains the thermostat schedule.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="active_thermostat_schedule_id" type="String (UUID)">
      ID of the active [thermostat schedule](/capability-guides/thermostats/creating-and-managing-thermostat-schedules).
    </ResponseField>

    <ResponseField name="available_climate_preset_modes" type="Array">
      Climate preset modes that the thermostat supports, such as "home", "away", "wake", "sleep", "occupied", and "unoccupied".
    </ResponseField>

    <ResponseField name="available_climate_presets" type="Array">
      Available [climate presets](/capability-guides/thermostats/creating-and-managing-climate-presets) for the thermostat.

      <Expandable title="properties">
        <ResponseField name="can_delete" type="Boolean">
          Indicates whether the [climate preset](/capability-guides/thermostats/creating-and-managing-climate-presets) key can be deleted.
        </ResponseField>

        <ResponseField name="can_edit" type="Boolean">
          Indicates whether the [climate preset](/capability-guides/thermostats/creating-and-managing-climate-presets) key can be edited.
        </ResponseField>

        <ResponseField name="can_use_with_thermostat_daily_programs" type="Boolean">
          Indicates whether the [climate preset](/capability-guides/thermostats/creating-and-managing-climate-presets) key can be programmed in a thermostat daily program.
        </ResponseField>

        <ResponseField name="climate_preset_key" type="String">
          Unique key to identify the [climate preset](/capability-guides/thermostats/creating-and-managing-climate-presets).
        </ResponseField>

        <ResponseField name="climate_preset_mode" type="Enum (String)">
          The climate preset mode for the thermostat, based on the available climate preset modes reported by the device.
        </ResponseField>

        <ResponseField name="cooling_set_point_celsius" type="number">
          Temperature to which the thermostat should cool (in °C). See also [Set Points](/capability-guides/thermostats/understanding-thermostat-concepts/set-points).
        </ResponseField>

        <ResponseField name="cooling_set_point_fahrenheit" type="number">
          Temperature to which the thermostat should cool (in °F). See also [Set Points](/capability-guides/thermostats/understanding-thermostat-concepts/set-points).
        </ResponseField>

        <ResponseField name="display_name" type="String">
          Display name for the [climate preset](/capability-guides/thermostats/creating-and-managing-climate-presets).
        </ResponseField>

        <ResponseField name="ecobee_metadata" type="Object">
          Metadata specific to the Ecobee climate, if applicable.

          <Expandable title="properties">
            <ResponseField name="climate_ref" type="String">
              Reference to the Ecobee climate, if applicable.
            </ResponseField>

            <ResponseField name="is_optimized" type="Boolean">
              Indicates if the climate preset is optimized by Ecobee.
            </ResponseField>

            <ResponseField name="owner" type="Enum (String)">
              Indicates whether the climate preset is owned by the user or the system.
            </ResponseField>
          </Expandable>
        </ResponseField>

        <ResponseField name="fan_mode_setting" type="Enum (String)">
          Desired [fan mode setting](/capability-guides/thermostats/configure-current-climate-settings#fan-mode-settings), such as `on`, `auto`, or `circulate`.
        </ResponseField>

        <ResponseField name="heating_set_point_celsius" type="number">
          Temperature to which the thermostat should heat (in °C). See also [Set Points](/capability-guides/thermostats/understanding-thermostat-concepts/set-points).
        </ResponseField>

        <ResponseField name="heating_set_point_fahrenheit" type="number">
          Temperature to which the thermostat should heat (in °F). See also [Set Points](/capability-guides/thermostats/understanding-thermostat-concepts/set-points).
        </ResponseField>

        <ResponseField name="hvac_mode_setting" type="Enum (String)">
          Desired [HVAC mode](/capability-guides/thermostats/understanding-thermostat-concepts/hvac-mode) setting, such as `heat`, `cool`, `heat_cool`, or `off`.
        </ResponseField>

        <ResponseField name="manual_override_allowed" type="Boolean">
          **Deprecated**. Use 'thermostat\_schedule.is\_override\_allowed'

          Indicates whether a person at the thermostat can change the thermostat's settings. See [Specifying Manual Override Permissions](/capability-guides/thermostats/creating-and-managing-thermostat-schedules#specifying-manual-override-permissions).
        </ResponseField>

        <ResponseField name="name" type="String">
          User-friendly name to identify the [climate preset](/capability-guides/thermostats/creating-and-managing-climate-presets).
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="available_fan_mode_settings" type="Array">
      Fan mode settings that the thermostat supports.
    </ResponseField>

    <ResponseField name="available_hvac_mode_settings" type="Array">
      HVAC mode settings that the thermostat supports.
    </ResponseField>

    <ResponseField name="current_climate_setting" type="Object">
      Current climate setting.

      <Expandable title="properties">
        <ResponseField name="can_delete" type="Boolean">
          Indicates whether the [climate preset](/capability-guides/thermostats/creating-and-managing-climate-presets) key can be deleted.
        </ResponseField>

        <ResponseField name="can_edit" type="Boolean">
          Indicates whether the [climate preset](/capability-guides/thermostats/creating-and-managing-climate-presets) key can be edited.
        </ResponseField>

        <ResponseField name="can_use_with_thermostat_daily_programs" type="Boolean">
          Indicates whether the [climate preset](/capability-guides/thermostats/creating-and-managing-climate-presets) key can be programmed in a thermostat daily program.
        </ResponseField>

        <ResponseField name="climate_preset_key" type="String">
          Unique key to identify the [climate preset](/capability-guides/thermostats/creating-and-managing-climate-presets).
        </ResponseField>

        <ResponseField name="climate_preset_mode" type="Enum (String)">
          The climate preset mode for the thermostat, based on the available climate preset modes reported by the device.
        </ResponseField>

        <ResponseField name="cooling_set_point_celsius" type="number">
          Temperature to which the thermostat should cool (in °C). See also [Set Points](/capability-guides/thermostats/understanding-thermostat-concepts/set-points).
        </ResponseField>

        <ResponseField name="cooling_set_point_fahrenheit" type="number">
          Temperature to which the thermostat should cool (in °F). See also [Set Points](/capability-guides/thermostats/understanding-thermostat-concepts/set-points).
        </ResponseField>

        <ResponseField name="display_name" type="String">
          Display name for the [climate preset](/capability-guides/thermostats/creating-and-managing-climate-presets).
        </ResponseField>

        <ResponseField name="ecobee_metadata" type="Object">
          Metadata specific to the Ecobee climate, if applicable.

          <Expandable title="properties">
            <ResponseField name="climate_ref" type="String">
              Reference to the Ecobee climate, if applicable.
            </ResponseField>

            <ResponseField name="is_optimized" type="Boolean">
              Indicates if the climate preset is optimized by Ecobee.
            </ResponseField>

            <ResponseField name="owner" type="Enum (String)">
              Indicates whether the climate preset is owned by the user or the system.
            </ResponseField>
          </Expandable>
        </ResponseField>

        <ResponseField name="fan_mode_setting" type="Enum (String)">
          Desired [fan mode setting](/capability-guides/thermostats/configure-current-climate-settings#fan-mode-settings), such as `on`, `auto`, or `circulate`.
        </ResponseField>

        <ResponseField name="heating_set_point_celsius" type="number">
          Temperature to which the thermostat should heat (in °C). See also [Set Points](/capability-guides/thermostats/understanding-thermostat-concepts/set-points).
        </ResponseField>

        <ResponseField name="heating_set_point_fahrenheit" type="number">
          Temperature to which the thermostat should heat (in °F). See also [Set Points](/capability-guides/thermostats/understanding-thermostat-concepts/set-points).
        </ResponseField>

        <ResponseField name="hvac_mode_setting" type="Enum (String)">
          Desired [HVAC mode](/capability-guides/thermostats/understanding-thermostat-concepts/hvac-mode) setting, such as `heat`, `cool`, `heat_cool`, or `off`.
        </ResponseField>

        <ResponseField name="manual_override_allowed" type="Boolean">
          **Deprecated**. Use 'thermostat\_schedule.is\_override\_allowed'

          Indicates whether a person at the thermostat can change the thermostat's settings. See [Specifying Manual Override Permissions](/capability-guides/thermostats/creating-and-managing-thermostat-schedules#specifying-manual-override-permissions).
        </ResponseField>

        <ResponseField name="name" type="String">
          User-friendly name to identify the [climate preset](/capability-guides/thermostats/creating-and-managing-climate-presets).
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="default_climate_setting" type="Object">
      **Deprecated**. use fallback\_climate\_preset\_key to specify a fallback climate preset instead.

      The default climate setting.

      <Expandable title="properties">
        <ResponseField name="can_delete" type="Boolean">
          Indicates whether the [climate preset](/capability-guides/thermostats/creating-and-managing-climate-presets) key can be deleted.
        </ResponseField>

        <ResponseField name="can_edit" type="Boolean">
          Indicates whether the [climate preset](/capability-guides/thermostats/creating-and-managing-climate-presets) key can be edited.
        </ResponseField>

        <ResponseField name="can_use_with_thermostat_daily_programs" type="Boolean">
          Indicates whether the [climate preset](/capability-guides/thermostats/creating-and-managing-climate-presets) key can be programmed in a thermostat daily program.
        </ResponseField>

        <ResponseField name="climate_preset_key" type="String">
          Unique key to identify the [climate preset](/capability-guides/thermostats/creating-and-managing-climate-presets).
        </ResponseField>

        <ResponseField name="climate_preset_mode" type="Enum (String)">
          The climate preset mode for the thermostat, based on the available climate preset modes reported by the device.
        </ResponseField>

        <ResponseField name="cooling_set_point_celsius" type="number">
          Temperature to which the thermostat should cool (in °C). See also [Set Points](/capability-guides/thermostats/understanding-thermostat-concepts/set-points).
        </ResponseField>

        <ResponseField name="cooling_set_point_fahrenheit" type="number">
          Temperature to which the thermostat should cool (in °F). See also [Set Points](/capability-guides/thermostats/understanding-thermostat-concepts/set-points).
        </ResponseField>

        <ResponseField name="display_name" type="String">
          Display name for the [climate preset](/capability-guides/thermostats/creating-and-managing-climate-presets).
        </ResponseField>

        <ResponseField name="ecobee_metadata" type="Object">
          Metadata specific to the Ecobee climate, if applicable.

          <Expandable title="properties">
            <ResponseField name="climate_ref" type="String">
              Reference to the Ecobee climate, if applicable.
            </ResponseField>

            <ResponseField name="is_optimized" type="Boolean">
              Indicates if the climate preset is optimized by Ecobee.
            </ResponseField>

            <ResponseField name="owner" type="Enum (String)">
              Indicates whether the climate preset is owned by the user or the system.
            </ResponseField>
          </Expandable>
        </ResponseField>

        <ResponseField name="fan_mode_setting" type="Enum (String)">
          Desired [fan mode setting](/capability-guides/thermostats/configure-current-climate-settings#fan-mode-settings), such as `on`, `auto`, or `circulate`.
        </ResponseField>

        <ResponseField name="heating_set_point_celsius" type="number">
          Temperature to which the thermostat should heat (in °C). See also [Set Points](/capability-guides/thermostats/understanding-thermostat-concepts/set-points).
        </ResponseField>

        <ResponseField name="heating_set_point_fahrenheit" type="number">
          Temperature to which the thermostat should heat (in °F). See also [Set Points](/capability-guides/thermostats/understanding-thermostat-concepts/set-points).
        </ResponseField>

        <ResponseField name="hvac_mode_setting" type="Enum (String)">
          Desired [HVAC mode](/capability-guides/thermostats/understanding-thermostat-concepts/hvac-mode) setting, such as `heat`, `cool`, `heat_cool`, or `off`.
        </ResponseField>

        <ResponseField name="manual_override_allowed" type="Boolean">
          **Deprecated**. Use 'thermostat\_schedule.is\_override\_allowed'

          Indicates whether a person at the thermostat can change the thermostat's settings. See [Specifying Manual Override Permissions](/capability-guides/thermostats/creating-and-managing-thermostat-schedules#specifying-manual-override-permissions).
        </ResponseField>

        <ResponseField name="name" type="String">
          User-friendly name to identify the [climate preset](/capability-guides/thermostats/creating-and-managing-climate-presets).
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="fallback_climate_preset_key" type="String">
      Key of the [fallback climate preset](/capability-guides/thermostats/creating-and-managing-climate-presets/setting-the-fallback-climate-preset) for the thermostat.
    </ResponseField>

    <ResponseField name="fan_mode_setting" type="Enum (String)">
      **Deprecated**. Use `current_climate_setting.fan_mode_setting` instead.

      The fan mode setting.
    </ResponseField>

    <ResponseField name="is_cooling" type="Boolean">
      Indicates whether the connected HVAC system is currently cooling, as reported by the thermostat.
    </ResponseField>

    <ResponseField name="is_fan_running" type="Boolean">
      Indicates whether the fan in the connected HVAC system is currently running, as reported by the thermostat.
    </ResponseField>

    <ResponseField name="is_heating" type="Boolean">
      Indicates whether the connected HVAC system is currently heating, as reported by the thermostat.
    </ResponseField>

    <ResponseField name="is_temporary_manual_override_active" type="Boolean">
      Indicates whether the current thermostat settings differ from the most recent active program or schedule that Seam activated. For this condition to occur, `current_climate_setting.manual_override_allowed` must also be `true`.
    </ResponseField>

    <ResponseField name="max_cooling_set_point_celsius" type="number">
      Maximum [cooling set point](/capability-guides/thermostats/understanding-thermostat-concepts/set-points#cooling-set-point) in °C.
    </ResponseField>

    <ResponseField name="max_cooling_set_point_fahrenheit" type="number">
      Maximum [cooling set point](/capability-guides/thermostats/understanding-thermostat-concepts/set-points#cooling-set-point) in °F.
    </ResponseField>

    <ResponseField name="max_heating_set_point_celsius" type="number">
      Maximum [heating set point](/capability-guides/thermostats/understanding-thermostat-concepts/set-points#heating-set-point) in °C.
    </ResponseField>

    <ResponseField name="max_heating_set_point_fahrenheit" type="number">
      Maximum [heating set point](/capability-guides/thermostats/understanding-thermostat-concepts/set-points#heating-set-point) in °F.
    </ResponseField>

    <ResponseField name="max_thermostat_daily_program_periods_per_day" type="number">
      Maximum number of periods that the thermostat can support per day. For example, if the thermostat supports 4 periods per day, this value is 4.
    </ResponseField>

    <ResponseField name="max_unique_climate_presets_per_thermostat_weekly_program" type="number">
      Maximum number of climate presets that the thermostat can support for weekly programming.
    </ResponseField>

    <ResponseField name="min_cooling_set_point_celsius" type="number">
      Minimum [cooling set point](/capability-guides/thermostats/understanding-thermostat-concepts/set-points#cooling-set-point) in °C.
    </ResponseField>

    <ResponseField name="min_cooling_set_point_fahrenheit" type="number">
      Minimum [cooling set point](/capability-guides/thermostats/understanding-thermostat-concepts/set-points#cooling-set-point) in °F.
    </ResponseField>

    <ResponseField name="min_heating_cooling_delta_celsius" type="number">
      Minimum [temperature difference](/capability-guides/thermostats/understanding-thermostat-concepts/set-points#minimum-heating-cooling-temperature-delta) in °C between the cooling and heating set points when in heat-cool (auto) mode.
    </ResponseField>

    <ResponseField name="min_heating_cooling_delta_fahrenheit" type="number">
      Minimum [temperature difference](/capability-guides/thermostats/understanding-thermostat-concepts/set-points#minimum-heating-cooling-temperature-delta) in °F between the cooling and heating set points when in heat-cool (auto) mode.
    </ResponseField>

    <ResponseField name="min_heating_set_point_celsius" type="number">
      Minimum [heating set point](/capability-guides/thermostats/understanding-thermostat-concepts/set-points#heating-set-point) in °C.
    </ResponseField>

    <ResponseField name="min_heating_set_point_fahrenheit" type="number">
      Minimum [heating set point](/capability-guides/thermostats/understanding-thermostat-concepts/set-points#heating-set-point) in °F.
    </ResponseField>

    <ResponseField name="relative_humidity" type="number">
      Reported relative humidity, as a value between 0 and 1, inclusive.
    </ResponseField>

    <ResponseField name="temperature_celsius" type="number">
      Reported temperature in °C.
    </ResponseField>

    <ResponseField name="temperature_fahrenheit" type="number">
      Reported temperature in °F.
    </ResponseField>

    <ResponseField name="temperature_threshold" type="Object">
      Current [temperature threshold](/capability-guides/thermostats/setting-and-monitoring-temperature-thresholds) set for the thermostat.

      <Expandable title="properties">
        <ResponseField name="lower_limit_celsius" type="number">
          Lower limit in °C within the current [temperature threshold](/capability-guides/thermostats/setting-and-monitoring-temperature-thresholds) set for the thermostat.
        </ResponseField>

        <ResponseField name="lower_limit_fahrenheit" type="number">
          Lower limit in °F within the current [temperature threshold](/capability-guides/thermostats/setting-and-monitoring-temperature-thresholds) set for the thermostat.
        </ResponseField>

        <ResponseField name="upper_limit_celsius" type="number">
          Upper limit in °C within the current [temperature threshold](/capability-guides/thermostats/setting-and-monitoring-temperature-thresholds) set for the thermostat.
        </ResponseField>

        <ResponseField name="upper_limit_fahrenheit" type="number">
          Upper limit in °F within the current [temperature threshold](/capability-guides/thermostats/setting-and-monitoring-temperature-thresholds) set for the thermostat.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="thermostat_daily_program_period_precision_minutes" type="number">
      Precision of the thermostat's period in minutes. For example, if the thermostat supports 15-minute periods, this value is 15. All values are relative to the top of the hour, so for 15 minutes, the periods would be 0, 15, 30, and 45 minutes past the hour.
    </ResponseField>

    <ResponseField name="thermostat_daily_programs" type="Array">
      Configured [daily programs](/capability-guides/thermostats/creating-and-managing-thermostat-programs) for the thermostat.

      <Expandable title="properties">
        <ResponseField name="created_at" type="String (ISO 8601)">
          Date and time at which the thermostat daily program was created.
        </ResponseField>

        <ResponseField name="device_id" type="String (UUID)">
          ID of the thermostat device on which the thermostat daily program is configured.
        </ResponseField>

        <ResponseField name="name" type="String">
          User-friendly name to identify the thermostat daily program.
        </ResponseField>

        <ResponseField name="periods" type="Array">
          Array of thermostat daily program periods.

          <Expandable title="properties">
            <ResponseField name="climate_preset_key" type="String">
              Key of the [climate preset](/capability-guides/thermostats/creating-and-managing-climate-presets) to activate at the `starts_at_time`.
            </ResponseField>

            <ResponseField name="starts_at_time" type="String">
              Time at which the thermostat daily program period starts, in [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) format.
            </ResponseField>
          </Expandable>
        </ResponseField>

        <ResponseField name="thermostat_daily_program_id" type="String (UUID)">
          ID of the thermostat daily program.
        </ResponseField>

        <ResponseField name="workspace_id" type="String (UUID)">
          ID of the workspace that contains the thermostat daily program.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="thermostat_weekly_program" type="Object">
      Current [weekly program](/capability-guides/thermostats/creating-and-managing-thermostat-programs) for the thermostat.

      <Expandable title="properties">
        <ResponseField name="created_at" type="String (ISO 8601)">
          Date and time at which the thermostat weekly program was created.
        </ResponseField>

        <ResponseField name="friday_program_id" type="String (UUID)">
          ID of the thermostat daily program to run on Fridays.
        </ResponseField>

        <ResponseField name="monday_program_id" type="String (UUID)">
          ID of the thermostat daily program to run on Mondays.
        </ResponseField>

        <ResponseField name="saturday_program_id" type="String (UUID)">
          ID of the thermostat daily program to run on Saturdays.
        </ResponseField>

        <ResponseField name="sunday_program_id" type="String (UUID)">
          ID of the thermostat daily program to run on Sundays.
        </ResponseField>

        <ResponseField name="thursday_program_id" type="String (UUID)">
          ID of the thermostat daily program to run on Thursdays.
        </ResponseField>

        <ResponseField name="tuesday_program_id" type="String (UUID)">
          ID of the thermostat daily program to run on Tuesdays.
        </ResponseField>

        <ResponseField name="wednesday_program_id" type="String (UUID)">
          ID of the thermostat daily program to run on Wednesdays.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="space_ids" type="Array">
  IDs of the spaces the device is in.
</ResponseField>

<ResponseField name="warnings" type="Array">
  Array of warnings associated with the device. Each warning object within the array contains two fields: `warning_code` and `message`. `warning_code` is a string that uniquely identifies the type of warning, enabling quick recognition and categorization of the issue. `message` provides a more detailed description of the warning, offering insights into the issue and potentially how to rectify it.
</ResponseField>

<ResponseField name="workspace_id" type="String (UUID)">
  Unique identifier for the Seam workspace associated with the device.
</ResponseField>

## Access Codes

<ResponseField name="offline_access_codes_enabled" type="Boolean">
  **Deprecated**. use device.can\_program\_offline\_access\_codes

  Indicates whether it is currently possible to use offline access codes for the device.
</ResponseField>

<ResponseField name="online_access_codes_enabled" type="Boolean">
  **Deprecated**. use device.can\_program\_online\_access\_codes

  Indicates whether it is currently possible to use online access codes for the device.
</ResponseField>

<ResponseField name="supports_accessory_keypad" type="Boolean">
  **Deprecated**. use device.properties.model.can\_connect\_accessory\_keypad

  The supports accessory keypad.
</ResponseField>

<ResponseField name="supports_offline_access_codes" type="Boolean">
  **Deprecated**. use offline\_access\_codes\_enabled

  The supports offline access codes.
</ResponseField>

<ResponseField name="backup_access_code_pool_enabled" type="Boolean">
  Indicates whether the [backup access code pool](/low-level-apis/smart-locks/access-codes/backup-access-codes) is currently enabled for the device. To disable it, set this to `false` using [/devices/update](/api/devices/update).
</ResponseField>

<ResponseField name="code_constraints" type="Array">
  Constraints on access codes for the device. Seam represents each constraint as an object with a `constraint_type` property. Depending on the constraint type, there may also be additional properties. Note that some constraints are manufacturer- or device-specific.

  <Expandable title="properties">
    <ResponseField name="constraint_type" type="Enum (String)">
      The constraint type.
    </ResponseField>

    <ResponseField name="max_length" type="number">
      Maximum name length constraint for access codes.
    </ResponseField>

    <ResponseField name="min_length" type="number">
      Minimum name length constraint for access codes.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="has_native_entry_events" type="Boolean">
  Indicates whether the device supports native entry events.
</ResponseField>

<ResponseField name="keypad_battery" type="Object">
  Keypad battery status.

  <Expandable title="properties">
    <ResponseField name="level" type="number">
      Keypad battery charge level.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="max_active_codes_supported" type="number">
  Maximum number of active access codes that the device supports.
</ResponseField>

<ResponseField name="offline_time_frame_options" type="Array">
  Time frames that may be requested when creating an offline access code, expressed as a list of options. The caller picks one option (by matching the requested duration when the options' duration ranges do not overlap, or by `display_name` when they do) and satisfies that one option's rules. When `undefined`, any time frame works.

  <Expandable title="properties">
    <ResponseField name="display_name" type="String">
      Label for this option. For a single-option device, the product name (for example, `algoPIN` or `SmartPIN`); for a multi-option device, a label that distinguishes it (for example, `Hourly` or `Fixed start times`).
    </ResponseField>

    <ResponseField name="end_date_recurrence_rule" type="String">
      iCalendar recurrence rule (RRULE) that the end date must fall on. Constrains which calendar dates are selectable, independent of the time-of-day rules.
    </ResponseField>

    <ResponseField name="matching_start_end_time" type="Boolean">
      When `true`, the start and end must fall at the same time of day (the caller picks which). Mutually exclusive with `time_pairs`.
    </ResponseField>

    <ResponseField name="max_duration" type="String">
      Maximum duration this option covers, as an ISO 8601 duration (for example, `PT672H` or `P367D`). Omitted when there is no maximum.
    </ResponseField>

    <ResponseField name="min_duration" type="String">
      Minimum duration this option covers, as an ISO 8601 duration (for example, `PT1H` or `P29D`). Omitted when there is no minimum.
    </ResponseField>

    <ResponseField name="start_date_recurrence_rule" type="String">
      iCalendar recurrence rule (RRULE) that the start date must fall on (for example, `FREQ=MONTHLY;BYDAY=1MO,3MO`). Constrains which calendar dates are selectable, independent of the time-of-day rules.
    </ResponseField>

    <ResponseField name="time_pairs" type="Array">
      Fixed start/end time pairings the caller chooses from. Mutually exclusive with `matching_start_end_time`.

      <Expandable title="properties">
        <ResponseField name="display_name" type="String">
          Label for the start/end time pairing.
        </ResponseField>

        <ResponseField name="end_time" type="String">
          End time of day as a 24-hour `HH:MM` value, interpreted in the option's `time_zone`. An `end_time` earlier on the clock than `start_time` means the end falls on a later date.
        </ResponseField>

        <ResponseField name="start_time" type="String">
          Start time of day as a 24-hour `HH:MM` value, interpreted in the option's `time_zone`.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="time_zone" type="String">
      IANA time zone for interpreting `time_pairs` and the date recurrence rules. Present only when the option fixes times or dates.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="online_time_frame_options" type="Array">
  Time frames that may be requested when creating an online access code, expressed as a list of options. The caller picks one option (by matching the requested duration when the options' duration ranges do not overlap, or by `display_name` when they do) and satisfies that one option's rules. When `undefined`, any time frame works.

  <Expandable title="properties">
    <ResponseField name="display_name" type="String">
      Label for this option. For a single-option device, the product name (for example, `algoPIN` or `SmartPIN`); for a multi-option device, a label that distinguishes it (for example, `Hourly` or `Fixed start times`).
    </ResponseField>

    <ResponseField name="end_date_recurrence_rule" type="String">
      iCalendar recurrence rule (RRULE) that the end date must fall on. Constrains which calendar dates are selectable, independent of the time-of-day rules.
    </ResponseField>

    <ResponseField name="matching_start_end_time" type="Boolean">
      When `true`, the start and end must fall at the same time of day (the caller picks which). Mutually exclusive with `time_pairs`.
    </ResponseField>

    <ResponseField name="max_duration" type="String">
      Maximum duration this option covers, as an ISO 8601 duration (for example, `PT672H` or `P367D`). Omitted when there is no maximum.
    </ResponseField>

    <ResponseField name="min_duration" type="String">
      Minimum duration this option covers, as an ISO 8601 duration (for example, `PT1H` or `P29D`). Omitted when there is no minimum.
    </ResponseField>

    <ResponseField name="start_date_recurrence_rule" type="String">
      iCalendar recurrence rule (RRULE) that the start date must fall on (for example, `FREQ=MONTHLY;BYDAY=1MO,3MO`). Constrains which calendar dates are selectable, independent of the time-of-day rules.
    </ResponseField>

    <ResponseField name="time_pairs" type="Array">
      Fixed start/end time pairings the caller chooses from. Mutually exclusive with `matching_start_end_time`.

      <Expandable title="properties">
        <ResponseField name="display_name" type="String">
          Label for the start/end time pairing.
        </ResponseField>

        <ResponseField name="end_time" type="String">
          End time of day as a 24-hour `HH:MM` value, interpreted in the option's `time_zone`. An `end_time` earlier on the clock than `start_time` means the end falls on a later date.
        </ResponseField>

        <ResponseField name="start_time" type="String">
          Start time of day as a 24-hour `HH:MM` value, interpreted in the option's `time_zone`.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="time_zone" type="String">
      IANA time zone for interpreting `time_pairs` and the date recurrence rules. Present only when the option fixes times or dates.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="supported_code_lengths" type="Array">
  Supported code lengths for access codes.
</ResponseField>

<ResponseField name="supports_backup_access_code_pool" type="Boolean">
  Indicates whether the device supports a [backup access code pool](/low-level-apis/smart-locks/access-codes/backup-access-codes).
</ResponseField>

## Locks

<ResponseField name="auto_lock_delay_seconds" type="number">
  The delay in seconds before the lock automatically locks after being unlocked.
</ResponseField>

<ResponseField name="auto_lock_enabled" type="Boolean">
  Indicates whether automatic locking is enabled.
</ResponseField>

<ResponseField name="door_open" type="Boolean">
  Indicates whether the door is open.
</ResponseField>

<ResponseField name="locked" type="Boolean">
  Indicates whether the lock is locked.
</ResponseField>


# Simulate a Keypad Code Entry
Source: https://docs.seam.co/api/locks/simulate/keypad_code_entry

/openapi.json post /locks/simulate/keypad_code_entry
Simulates the entry of a code on a keypad. You can only perform this action for [August](/device-and-system-integration-guides/august-locks) devices within [sandbox workspaces](/core-concepts/workspaces#sandbox-workspaces).



# Simulate a Manual Lock Action Using a Keypad
Source: https://docs.seam.co/api/locks/simulate/manual_lock_via_keypad

/openapi.json post /locks/simulate/manual_lock_via_keypad
Simulates a manual lock action using a keypad. You can only perform this action for [August](/device-and-system-integration-guides/august-locks) devices within [sandbox workspaces](/core-concepts/workspaces#sandbox-workspaces).



# Unlock a Lock
Source: https://docs.seam.co/api/locks/unlock_door

/openapi.json post /locks/unlock_door
Unlocks a [lock](/low-level-apis/smart-locks). See also [Locking and Unlocking Smart Locks](/low-level-apis/smart-locks/lock-and-unlock).



# MCP Installation
Source: https://docs.seam.co/api/mcp-installation

Connect the Seam Docs MCP server to Claude to search Seam's API reference and device database from inside your conversations.

<img alt="" />

The **Seam Docs MCP Server** is a public, read-only [Model Context Protocol](https://modelcontextprotocol.io/) server that gives Claude and other MCP-compatible clients access to Seam's developer documentation and device database. Connect it once, then ask Claude questions about the Seam API, capabilities, webhooks, SDK usage, and the 400+ supported device models — across smart locks, thermostats, access control systems, and noise sensors. Claude grounds its answers in the most up-to-date Seam docs.

The server is intended for developers integrating with Seam who want Claude to answer Seam questions accurately, whether they're looking up an API endpoint, checking which lock models support mobile keys, or finding the right integration guide. It is read-only: it cannot control devices, manage access codes, create resources, or perform any other write operations against the Seam API.

## Server Details

| Property       | Value                       |
| -------------- | --------------------------- |
| Server URL     | `https://mcp.seam.co/mcp`   |
| Transport      | Streamable HTTP             |
| Authentication | None — the server is public |

<Info>
  No API key, account, or sign-up is required to use the Seam Docs MCP server.
  It only reads and returns Seam's public documentation.
</Info>

## What You Can Ask

Once connected, you can ask Claude questions like the following, and Claude will fetch the answer from the Seam docs and device database:

* "How do I unlock a Schlage Encode lock with the Seam API?"
* "Show me the webhook payload for `lock.locked`."
* "What's the difference between an access code and an access grant?"
* "Which smart lock models support mobile keys and remote unlock?"
* "Compare August and Yale lock features for a hospitality deployment."
* "Find the right integration guide for property management workflows."
* "Does Seam support Salto KS access control systems?"
* "How do I create a Connect Webview from the Python SDK?"

## Connect From Claude.ai

1. Sign in to [claude.ai](https://claude.ai).
2. Open **Settings → Connectors**.
3. Click **Add custom connector**.
4. Set the **URL** to `https://mcp.seam.co/mcp`.
5. Set the **Name** to `Seam Docs`.
6. Save. No authentication is required.

The connector is now available to Claude in any new conversation.

## Connect From Claude Desktop

1. Open Claude Desktop and go to **Settings → Connectors**.
2. Click **Add custom connector**.
3. Set the **URL** to `https://mcp.seam.co/mcp`.
4. Set the **Name** to `Seam Docs`.
5. Save and restart Claude Desktop if prompted.

## Connect From Claude Code

Run the following command from your terminal:

```bash theme={null}
claude mcp add --transport http seam-docs https://mcp.seam.co/mcp
```

Or add the following entry to your Claude Code MCP configuration file:

```json theme={null}
{
  "mcpServers": {
    "seam-docs": {
      "type": "http",
      "url": "https://mcp.seam.co/mcp"
    }
  }
}
```

## Available Tools

The Seam Docs MCP server exposes three read-only tools:

| Tool                | Display Name      | Description                                                                                              |
| ------------------- | ----------------- | -------------------------------------------------------------------------------------------------------- |
| `search_docs`       | Search Seam Docs  | Semantic search across all Seam documentation and the 400+ supported device models, ranked by relevance. |
| `get_doc`           | Get Doc Page      | Fetch the full content of any Seam documentation or device page.                                         |
| `list_doc_sections` | List Doc Sections | Browse the Seam documentation tree to discover available content.                                        |

Claude selects the appropriate tool automatically based on your prompt.

## Troubleshooting

* **403 Forbidden on connection** — The server only accepts requests from approved origins (`mcp.seam.co`, `claude.ai`, `app.claude.ai`, and `localhost`). Requests from other origins are rejected.
* **Empty search results** — If `search_docs` returns nothing, broaden your query. Use Seam API resource names (for example, `access_codes`) rather than SDK-specific method names, and use generic capability terms (for example, "mobile keys") when searching for devices.
* **Connection refused** — Confirm that your network allows outbound HTTPS to `mcp.seam.co`. Some corporate firewalls block custom MCP endpoints.

## Support

For questions or issues with the Seam Docs MCP server, contact [support@seam.co](mailto:support@seam.co).


# List Noise Sensors
Source: https://docs.seam.co/api/noise_sensors/list

/openapi.json post /noise_sensors/list
Returns a list of all [noise sensors](/capability-guides/noise-sensors).



# Create a Noise Threshold
Source: https://docs.seam.co/api/noise_sensors/noise_thresholds/create

/openapi.json post /noise_sensors/noise_thresholds/create
Creates a new [noise threshold](/capability-guides/noise-sensors/configure-noise-threshold-settings) for a [noise sensor](/capability-guides/noise-sensors). Thresholds represent the limits of noise tolerated at a property, which can be customized for each hour of the day. Each device has its own default thresholds, but you can use the Seam API to modify them.



# Delete a Noise Threshold
Source: https://docs.seam.co/api/noise_sensors/noise_thresholds/delete

/openapi.json post /noise_sensors/noise_thresholds/delete
Deletes a [noise threshold](/capability-guides/noise-sensors/configure-noise-threshold-settings) from a [noise sensor](/capability-guides/noise-sensors).



# Noise Thresholds Events
Source: https://docs.seam.co/api/noise_sensors/noise_thresholds/events

Webhook events that Seam emits for the Noise Thresholds resource, with example payloads and properties.

## `noise_sensor.noise_threshold_triggered`

Extended periods of noise or noise exceeding a [threshold](/capability-guides/noise-sensors#what-is-a-threshold) were detected.

<ResponseExample>
  ```json Example webhook payload theme={null}
  {
    "connected_account_custom_metadata": {},
    "connected_account_id": "00000000-0000-0000-0000-000000000000",
    "created_at": "2025-01-01T00:00:00.000Z",
    "customer_key": "",
    "device_custom_metadata": {},
    "device_id": "00000000-0000-0000-0000-000000000000",
    "event_description": "Extended periods of noise or noise exceeding a [threshold](/capability-guides/noise-sensors#what-is-a-threshold) were detected.",
    "event_id": "00000000-0000-0000-0000-000000000000",
    "event_type": "noise_sensor.noise_threshold_triggered",
    "minut_metadata": {},
    "noise_level_decibels": 0,
    "noise_level_nrs": 0,
    "noise_threshold_id": "00000000-0000-0000-0000-000000000000",
    "noise_threshold_name": "",
    "noiseaware_metadata": {},
    "occurred_at": "2025-01-01T00:00:00.000Z",
    "workspace_id": "00000000-0000-0000-0000-000000000000"
  }
  ```
</ResponseExample>

<Accordion title="Properties">
  <ResponseField name="connected_account_custom_metadata" type="Object">
    Custom metadata of the connected account, present when connected\_account\_id is provided.
  </ResponseField>

  <ResponseField name="connected_account_id" type="String (UUID)">
    ID of the connected account associated with the event.
  </ResponseField>

  <ResponseField name="created_at" type="String (ISO 8601)">
    Date and time at which the event was created.
  </ResponseField>

  <ResponseField name="customer_key" type="String">
    The customer key associated with the device, if any.
  </ResponseField>

  <ResponseField name="device_custom_metadata" type="Object">
    Custom metadata of the device, present when device\_id is provided.
  </ResponseField>

  <ResponseField name="device_id" type="String (UUID)">
    ID of the affected device.
  </ResponseField>

  <ResponseField name="event_description" type="String">
    Human-readable description of the event. Persisted when the event is created (so the creating code, including a provider, can supply a tailored description) and otherwise derived from the event.
  </ResponseField>

  <ResponseField name="event_id" type="String (UUID)">
    ID of the event.
  </ResponseField>

  <ResponseField name="event_type" type="Enum (String)">
    Value: `noise_sensor.noise_threshold_triggered`
  </ResponseField>

  <ResponseField name="minut_metadata" type="Object">
    Metadata from Minut.
  </ResponseField>

  <ResponseField name="noise_level_decibels" type="number">
    Detected noise level in decibels.
  </ResponseField>

  <ResponseField name="noise_level_nrs" type="number">
    Detected noise level in Noiseaware Noise Risk Score (NRS).
  </ResponseField>

  <ResponseField name="noise_threshold_id" type="String (UUID)">
    ID of the noise threshold that was triggered.
  </ResponseField>

  <ResponseField name="noise_threshold_name" type="String">
    Name of the noise threshold that was triggered.
  </ResponseField>

  <ResponseField name="noiseaware_metadata" type="Object">
    Metadata from Noiseaware.
  </ResponseField>

  <ResponseField name="occurred_at" type="String (ISO 8601)">
    Date and time at which the event occurred.
  </ResponseField>

  <ResponseField name="workspace_id" type="String (UUID)">
    ID of the workspace associated with the event.
  </ResponseField>
</Accordion>


# Get a Noise Threshold
Source: https://docs.seam.co/api/noise_sensors/noise_thresholds/get

/openapi.json post /noise_sensors/noise_thresholds/get
Returns a specified [noise threshold](/capability-guides/noise-sensors/configure-noise-threshold-settings) for a [noise sensor](/capability-guides/noise-sensors).



# List Noise Thresholds
Source: https://docs.seam.co/api/noise_sensors/noise_thresholds/list

/openapi.json post /noise_sensors/noise_thresholds/list
Returns a list of all [noise thresholds](/capability-guides/noise-sensors/configure-noise-threshold-settings) for a [noise sensor](/capability-guides/noise-sensors).



# Noise Thresholds
Source: https://docs.seam.co/api/noise_sensors/noise_thresholds/object

Learn how the noise_threshold object sets the limits of noise tolerated at a property, customizable for each hour of the day on a noise sensor.

## The noise\_threshold Object

Represents a [noise threshold](/capability-guides/noise-sensors/configure-noise-threshold-settings) for a [noise sensor](/capability-guides/noise-sensors). Thresholds represent the limits of noise tolerated at a property, which can be customized for each hour of the day. Each device has its own default thresholds, but you can use the Seam API to modify them.

<ResponseExample>
  ```json Noise Threshold theme={null}
  {
    "device_id": "69b9e908-039b-413a-904e-5edee653ca27",
    "ends_daily_at": "09:00:00[America/Los_Angeles]",
    "name": "My Noise Threshold",
    "noise_threshold_decibels": 21,
    "noise_threshold_id": "f8cef69d-625f-464c-aed4-287c06e0d7fe",
    "noise_threshold_nrs": 5,
    "starts_daily_at": "07:00:00[America/Los_Angeles]"
  }
  ```
</ResponseExample>

***

## Properties

<ResponseField name="device_id" type="String (UUID)">
  Unique identifier for the device that contains the noise threshold.
</ResponseField>

<ResponseField name="ends_daily_at" type="String">
  Time at which the noise threshold should become inactive daily.
</ResponseField>

<ResponseField name="name" type="String">
  Name of the noise threshold.
</ResponseField>

<ResponseField name="noise_threshold_decibels" type="number">
  Noise level in decibels for the noise threshold.
</ResponseField>

<ResponseField name="noise_threshold_id" type="String (UUID)">
  Unique identifier for the noise threshold.
</ResponseField>

<ResponseField name="noise_threshold_nrs" type="number">
  Noise level in Noiseaware Noise Risk Score (NRS) for the noise threshold. This parameter is only relevant for [Noiseaware sensors](/device-and-system-integration-guides/noiseaware-sensors).
</ResponseField>

<ResponseField name="starts_daily_at" type="String">
  Time at which the noise threshold should become active daily.
</ResponseField>


# Update a Noise Threshold
Source: https://docs.seam.co/api/noise_sensors/noise_thresholds/update

/openapi.json post /noise_sensors/noise_thresholds/update
Updates a [noise threshold](/capability-guides/noise-sensors/configure-noise-threshold-settings) for a [noise sensor](/capability-guides/noise-sensors).



# The Noise Sensor Object
Source: https://docs.seam.co/api/noise_sensors/object

Learn how the device object represents a noise sensor that measures sound levels, lets you configure thresholds, and emits disturbance events.

## The device Object for Noise Sensors

Represents a [noise sensor](/capability-guides/noise-sensors).

Noise sensors are devices that measure that sound level in a given area. You can use noise sensors to monitor noise levels remotely and receive notifications when the noise volume is too loud. The Seam API enables you to configure the [noise thresholds](/capability-guides/noise-sensors/configure-noise-threshold-settings) of a noise sensor and receive events when a disturbance is detected. You can also [simulate triggering a noise threshold](/api/noise_sensors/simulate/trigger_noise_threshold).

The Seam API represents a noise sensor as a `device` resource that includes both basic device properties and noise sensor-specific properties.

***

## Endpoints

[**`/noise_sensors/list`**](./list)

Returns a list of all [noise sensors](/capability-guides/noise-sensors).


# Simulate Triggering a Noise Threshold
Source: https://docs.seam.co/api/noise_sensors/simulate/trigger_noise_threshold

/openapi.json post /noise_sensors/simulate/trigger_noise_threshold
Simulates the triggering of a [noise threshold](/capability-guides/noise-sensors/configure-noise-threshold-settings) for a [noise sensor](/capability-guides/noise-sensors) in a [sandbox workspace](/core-concepts/workspaces#sandbox-workspaces).



# Pagination
Source: https://docs.seam.co/api/pagination

Learn how to paginate Seam API list endpoints using the limit and page_cursor parameters and the pagination response object for faster, efficient apps.

For endpoints that can return long lists of resources, using pagination makes your app faster and more efficient. The Seam API and our JavaScript, Python, PHP, and Ruby SDKs support pagination for `list` endpoints.

<Info>
  Currently, we support pagination for access codes, access system users,
  Connect Webviews, connected accounts, and devices.
</Info>

To fetch and process resources across multiple pages in the Seam API, use the `limit` and `page_cursor` parameters, along with the `pagination` response object. The `pagination` object provides the following information:

<table>
  <thead>
    <tr>
      <th>Property</th>
      <th>Type</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        <code>next\_page\_cursor</code>
      </td>

      <td>String</td>

      <td>
        Opaque value that you use to select the next page of results through the
        <code>page\_cursor</code> parameter.
      </td>
    </tr>

    <tr>
      <td>
        <code>has\_next\_page</code>
      </td>

      <td>Boolean</td>

      <td>
        Indicates whether there is another page of results after this one.
      </td>
    </tr>

    <tr>
      <td>
        <code>next\_page\_url</code>
      </td>

      <td>String (URI)</td>
      <td>URL to get the next page of results.</td>
    </tr>
  </tbody>
</table>

For pagination in the Seam SDKs, use the corresponding paginator class, for example, `SeamPaginator` in the Seam JavaScript and Python SDKs and `Paginator` in the Seam PHP and Ruby SDKs.

The following examples show you how to use pagination in a variety of scenarios:

## Manually Fetch Pages

You can specify the number of records per page and the desired page of results. The first `list` request returns the first set of records, as well as the `pagination` object. If `pagination.has_next_page` is `true`, you can request an additional page of records. For all `list` requests after the first, use the `pagination.next_page_cursor` as the value for the `page_cursor` parameter.

The following example gets the first page of 20 devices and then the second page of 20 devices:

<Tabs>
  <Tab title="JavaScript">
    **Code:**

    ```javascript theme={null}
    const pages = seam.createPaginator(
      seam.devices.list({
        limit: 20,
      }),
    )

    const [devices, { hasNextPage, nextPageCursor }] = await pages.firstPage()

    if (hasNextPage) {
      const [moreDevices] = await pages.nextPage(nextPageCursor)
    }
    ```

    **Output:**

    ```json theme={null}
    [
      {
        device_id: '11111111-1111-1111-1111-444444444444',
        ...
      },
      ...
    ]
    ```
  </Tab>

  <Tab title="cURL">
    **Request:**

    ```bash theme={null}
    # Use GET or POST.
    curl -X 'GET' \
      'https://connect.getseam.com/devices/list' \
      -H 'accept: application/json' \
      -H "Authorization: Bearer ${SEAM_API_KEY}" \
      -H 'Content-Type: application/json' \
      -d '{
        "limit": 20
      }'

    curl -X 'GET' \
      'https://connect.getseam.com/devices/list' \
      -H 'accept: application/json' \
      -H "Authorization: Bearer ${SEAM_API_KEY}" \
      -H 'Content-Type: application/json' \
      -d "{
        \"limit\": 20
        \"page_cursor\": \"${next_page_cursor}\"
      }"
    ```

    **Response:**

    ```json theme={null}
    {
      "devices": [
        {
          "device_id": "11111111-1111-1111-1111-444444444444",
          ...
        },
        ...
      ],
      "pagination": {
        "next_page_cursor": "[string]",
        "has_next_page": true,
        "next_page_url": "[URI]"
      },
      "ok": true
    }
    ```
  </Tab>

  <Tab title="Python">
    **Code:**

    ```python theme={null}
    paginator = seam.create_paginator(seam.devices.list, {"limit": 20})

    devices, pagination = paginator.first_page()

    if pagination.has_next_page:
        more_devices, _ = paginator.next_page(pagination.next_page_cursor)
    ```

    **Output:**

    ```
    [
      Device(
        device_id='11111111-1111-1111-1111-444444444444',
        ...
      ),
      ...
    ]
    ```
  </Tab>

  <Tab title="Ruby">
    **Code:**

    ```ruby theme={null}
    paginator = seam.create_paginator(seam.devices.method(:list), {limit: 20})

    devices, pagination = paginator.first_page

    if pagination.has_next_page?
      more_devices, _ = paginator.next_page(pagination.next_page_cursor)
    end
    ```

    **Output:**

    ```
    [
      <Seam::Device:0x004d8
        device_id="11111111-1111-1111-1111-444444444444"
        ...
      >,
      ...
    ]
    ```
  </Tab>

  <Tab title="PHP">
    **Code:**

    ```php theme={null}
    $pages = $seam->createPaginator(
        fn($params) => $seam->devices->list(...$params),
        ["limit" => 2]
    );

    [$devices, $pagination] = $pages->firstPage();

    if ($pagination->has_next_page) {
        [$moreDevices] = $pages->nextPage($pagination->next_page_cursor);
    }
    ```

    **Output:**

    ```json theme={null}
    [
      {
        "device_id": "11111111-1111-1111-1111-444444444444",
        ...
      },
      ...
    ]
    ```
  </Tab>

  <Tab title="C#">
    **Code:**

    ```csharp theme={null}
    // Coming soon!
    ```

    **Output:**

    ```json theme={null}
    // Coming soon!
    ```
  </Tab>
</Tabs>

***

## Resume Pagination

You can get the first page on initial load, store the state, and then get the next page at a later time using the stored state.

The following example gets the first page of 20 records from the list of devices and, later, gets the next page of 20 devices:

<Tabs>
  <Tab title="JavaScript">
    **Code:**

    ```javascript theme={null}
    // Get the first page of devices.
    const params = { limit: 20 }

    const pages = seam.createPaginator(seam.devices.list(params))

    const [devices, pagination] = await pages.firstPage()

    // Store the state, for example, in memory, a file, or a database.
    localStorage.setItem('/seam/devices/list', JSON.stringify([params, pagination]))

    // Later, get the next page of devices.
    const [params = {}, { hasNextPage = false, nextPageCursor = null } = {}] =
      JSON.parse(localStorage.getItem('/seam/devices/list') ?? '[]')

    if (hasNextPage) {
      const pages = seam.createPaginator(seam.devices.list(params))
      const [moreDevices] = await pages.nextPage(nextPageCursor)
    }
    ```

    **Output:**

    ```json theme={null}
    [
      {
        device_id: '11111111-1111-1111-1111-444444444444',
        ...
      },
      ...
    ]

    [
      {
        device_id: '11111111-1111-1111-2222-444444444444',
        ...
      },
      ...
    ]
    ```
  </Tab>

  <Tab title="cURL">
    **Request:**

    ```bash theme={null}
    # Get the first page.
    # Use GET or POST.
    curl -X 'GET' \
      'https://connect.getseam.com/devices/list' \
      -H 'accept: application/json' \
      -H "Authorization: Bearer ${SEAM_API_KEY}" \
      -H 'Content-Type: application/json' \
      -d '{
        "limit": 20
      }'

    # Store the state, for example, in memory, a file, or a database.

    # At a later time, retrieve the stored state.
    # Then, get the next page using the stored state.
    curl -X 'GET' \
      'https://connect.getseam.com/devices/list' \
      -H 'accept: application/json' \
      -H "Authorization: Bearer ${SEAM_API_KEY}" \
      -H 'Content-Type: application/json' \
      -d "{
        \"limit\": 20
        \"page_cursor\": \"${next_page_cursor}\"
      }"
    ```

    **Response:**

    ```json theme={null}
    {
      "devices": [
        {
          "device_id": "11111111-1111-1111-1111-444444444444",
          ...
        },
        ...
      ],
      "pagination": {
        "next_page_cursor": "[string]",
        "has_next_page": true,
        "next_page_url": "[URI]"
      },
      "ok": true
    }

    {
      "devices": [
        {
          "device_id": "11111111-1111-1111-2222-444444444444",
          ...
        },
        ...
      ],
      "pagination": {
        "next_page_cursor": "[string]",
        "has_next_page": true,
        "next_page_url": "[URI]"
      },
      "ok": true
    }
    ```
  </Tab>

  <Tab title="Python">
    **Code:**

    ```python theme={null}
    # Get the first page.
    params = {"limit": 20}
    paginator = seam.create_paginator(seam.devices.list, params)

    devices, pagination = paginator.first_page()

    # Store the state, for example, in memory, a file, or a database.
    pagination_state = {
        "params": params,
        "next_page_cursor": pagination.next_page_cursor,
        "has_next_page": pagination.has_next_page,
    }
    with open("/tmp/seam_devices_list.json", "w") as f:
        json.dump(pagination_state, f)

    # Get the next page at a later time using the stored state.
    with open("/tmp/seam_devices_list.json", "r") as f:
        pagination_state = json.load(f)

    if pagination_state.get("has_next_page"):
        paginator = seam.create_paginator(
            seam.devices.list, pagination_state["params"]
        )
        more_devices, _ = paginator.next_page(
            pagination_state["next_page_cursor"]
        )
    ```

    **Output:**

    ```
    [
      Device(
        device_id='11111111-1111-1111-1111-444444444444',
        ...
      ),
      ...
    ]

    [
      Device(
        device_id='11111111-1111-1111-2222-444444444444',
        ...
      ),
      ...
    ]
    ```
  </Tab>

  <Tab title="Ruby">
    **Code:**

    ```ruby theme={null}
    # Get the first page.
    params = {limit: 20}
    paginator = seam.create_paginator(seam.devices.method(:list), params)

    devices, pagination = paginator.first_page

    # Store the state, for example, in memory, a file, or a database.
    pagination_state = {
      "params" => params,
      "next_page_cursor" => pagination.next_page_cursor,
      "has_next_page" => pagination.has_next_page?
    }
    File.write("/tmp/seam_devices_list.json", JSON.dump(pagination_state))

    # Get the next page at a later time using the stored state.
    pagination_state_json = File.read("/tmp/seam_devices_list.json")
    pagination_state = JSON.parse(pagination_state_json)

    if pagination_state["has_next_page"]
      paginator = seam.create_paginator(
        seam.devices.method(:list), pagination_state["params"]
      )
      more_devices, _ = paginator.next_page(
        pagination_state["next_page_cursor"]
      )
    ```

    **Output:**

    ```
    [
      <Seam::Device:0x004d8
        device_id="11111111-1111-1111-1111-444444444444"
        ...
        >,
      ...
    ]

    [
      <Seam::Device:0x004d8
        device_id="11111111-1111-1111-2222-444444444444"
        ...
        >,
      ...
    ]
    ```
  </Tab>

  <Tab title="PHP">
    **Code:**

    ```php theme={null}
    // Get the first page.
    $params = ["limit" => 20];

    $pages = $seam->createPaginator(
        fn($p) => $seam->devices->list(...$p),
        $params
    );

    [$devices, $pagination] = $pages->firstPage();

    // Store the state, for example, in memory, a file, or a database.
    file_put_contents(
        "/tmp/seam_devices_list.json",
        json_encode([$params, $pagination])
    );

    // Get the next page at a later time using the stored state.
    $stored_data = json_decode(
        file_get_contents("/tmp/seam_devices_list.json") ?: "[]",
        false
    );

    $params = $stored_data[0] ?? [];
    $pagination =
        $stored_data[1] ??
        (object) ["has_next_page" => false, "next_page_cursor" => null];

    if ($pagination->has_next_page) {
        $pages = $seam->createPaginator(
            fn($p) => $seam->devices->list(...$p),
            $params
        );
        [$moreDevices] = $pages->nextPage($pagination->next_page_cursor);
    }
    ```

    **Output:**

    ```json theme={null}
    [
      {
        "device_id": "11111111-1111-1111-1111-444444444444",
        ...
      },
      ...
    ]

    [
      {
        "device_id": "11111111-1111-1111-2222-444444444444",
        ...
      },
      ...
    ]
    ```
  </Tab>

  <Tab title="C#">
    **Code:**

    ```csharp theme={null}
    // Coming soon!
    ```

    **Output:**

    ```json theme={null}
    // Coming soon!
    ```
  </Tab>
</Tabs>

***

## Iterate Over All Pages

You can iterate over all pages of records.

The following example uses a loop to get all pages of records for a list of 65 devices, at 20 records per page:

<Tabs>
  <Tab title="JavaScript">
    **Code:**

    ```javascript theme={null}
    const pages = seam.createPaginator(
      seam.devices.list({
        limit: 20,
      }),
    )

    for await (const devices of pages) {
      console.log(`There are ${devices.length} devices on this page.`)
    }
    ```

    **Output:**

    ```
    There are 20 devices on this page.
    There are 20 devices on this page.
    There are 20 devices on this page.
    There are 5 devices on this page.
    ```
  </Tab>

  <Tab title="cURL">
    **Request:**

    ```bash theme={null}
    # Get the first page.
    # Use GET or POST.
    response=$(curl -X 'GET' \
      'https://connect.getseam.com/devices/list' \
      -H 'accept: application/json' \
      -H "Authorization: Bearer ${SEAM_API_KEY}" \
      -H 'Content-Type: application/json' \
      -d '{
        "limit": 20
      }')

    echo "$response" | jq -r '.devices | length' | xargs -I {} echo "There are {} devices on this page."

    # Extract pagination info.
    next_cursor=$(echo "$response" | jq -r '.pagination.next_page_cursor')
    has_next=$(echo "$response" | jq -r '.pagination.has_next_page')

    # Process subsequent pages.
    while [ "$has_next" = "true" ] && [ ! -z "$next_cursor" ]; do
      response=$(curl -X 'GET' \
      'https://connect.getseam.com/devices/list' \
      -H 'accept: application/json' \
      -H "Authorization: Bearer ${SEAM_API_KEY}" \
      -H 'Content-Type: application/json' \
      -d "{
        \"limit\": 20,
        \"page_cursor\": \"${next_cursor}\"
      }")

      echo "$response" | jq -r '.devices | length' | xargs -I {} echo "There are {} devices on this page."

      # Update pagination info.
      next_cursor=$(echo "$response" | jq -r '.pagination.next_page_cursor')
      has_next=$(echo "$response" | jq -r '.pagination.has_next_page')
    done
    ```

    **Response:**

    ```
    There are 20 devices on this page.
    There are 20 devices on this page.
    There are 20 devices on this page.
    There are 5 devices on this page.
    ```
  </Tab>

  <Tab title="Python">
    **Code:**

    ```python theme={null}
    pages = seam.create_paginator(
      seam.devices.list(
        limit=20
      )
    )

    for devices in pages:
      pprint(f"There are {len(devices)} devices on this page.")
    ```

    **Output:**

    ```
    There are 20 devices on this page.
    There are 20 devices on this page.
    There are 20 devices on this page.
    There are 5 devices on this page.
    ```
  </Tab>

  <Tab title="Ruby">
    **Code:**

    ```ruby theme={null}
    params = {limit: 20}
    pages = seam.create_paginator(seam.devices.method(:list), params)

    pages.each do |devices|
      puts "There are #{devices.length} devices on this page."
    end
    ```

    **Output:**

    ```
    There are 20 devices on this page.
    There are 20 devices on this page.
    There are 20 devices on this page.
    There are 5 devices on this page.
    ```
  </Tab>

  <Tab title="PHP">
    **Code:**

    ```php theme={null}
    $params = ["limit" => 20];

    $paginator = $seam->createPaginator(
        fn($p) => $seam->devices->list(...$p),
        $params
    );

    foreach ($paginator as $page) {
        $devices = $page->devices;
        echo "There are " . count($devices) . " devices on this page." . PHP_EOL;
    }
    ```

    **Output:**

    ```
    There are 20 devices on this page.
    There are 20 devices on this page.
    There are 20 devices on this page.
    There are 5 devices on this page.
    ```
  </Tab>

  <Tab title="C#">
    **Code:**

    ```csharp theme={null}
    // Coming soon!
    ```

    **Output:**

    ```json theme={null}
    // Coming soon!
    ```
  </Tab>
</Tabs>

***

## Iterate Over All Resources

You can iterate over all resources within all pages.

The following example uses a loop to get all records for a list of devices, at 20 records per page, and then prints out the device ID for each record:

<Tabs>
  <Tab title="JavaScript">
    **Code:**

    ```javascript theme={null}
    const pages = seam.createPaginator(
      seam.devices.list({
        limit: 20,
      }),
    )

    for await (const device of pages.flatten()) {
      console.log(device.device_id)
    }
    ```

    **Output:**

    ```
    '11111111-1111-1111-1111-444444444444'
    '11111111-1111-1111-2222-444444444444'
    ...
    ```
  </Tab>

  <Tab title="cURL">
    **Request:**

    ```bash theme={null}
    # Get the first page.
    # Use GET or POST.
    response=$(curl -X 'GET' \
      'https://connect.getseam.com/devices/list' \
      -H 'accept: application/json' \
      -H "Authorization: Bearer ${SEAM_API_KEY}" \
      -H 'Content-Type: application/json' \
      -d '{
        "limit": 20
      }')

    # Process all pages.
    while true; do
      # Extract and print the device IDs from the current page.
      echo "$response" | jq -r '.devices[].device_id'

      # Check whether there are more pages.
      has_next=$(echo "$response" | jq -r '.pagination.has_next_page')
      if [ "$has_next" != "true" ]; then
          break
      fi

      # Get the next page cursor.
      next_cursor=$(echo "$response" | jq -r '.pagination.next_page_cursor')
      if [ -z "$next_cursor" ] || [ "$next_cursor" = "null" ]; then
          break
      fi

      # Fetch the next page.
      response=$(curl -X 'GET' \
      'https://connect.getseam.com/devices/list' \
      -H 'accept: application/json' \
      -H "Authorization: Bearer ${SEAM_API_KEY}" \
      -H 'Content-Type: application/json' \
      -d "{
        \"limit\": 20,
        \"page_cursor\": \"${next_cursor}\"
      }")
    done
    ```

    **Response:**

    ```
    "11111111-1111-1111-1111-444444444444"
    "11111111-1111-1111-2222-444444444444"
    ...
    ```
  </Tab>

  <Tab title="Python">
    **Code:**

    ```python theme={null}
    paginator = seam.create_paginator(seam.devices.list, {"limit": 20})

    for device in paginator.flatten():
        print(device.device_id)
    ```

    **Output:**

    ```
    '11111111-1111-1111-1111-444444444444'
    '11111111-1111-1111-2222-444444444444'
    ...
    ```
  </Tab>

  <Tab title="Ruby">
    **Code:**

    ```ruby theme={null}
    paginator = seam.create_paginator(seam.devices.method(:list), {limit: 20})

    paginator.flatten.each do |device|
      puts device.device_id
    end
    ```

    **Output:**

    ```
    "11111111-1111-1111-1111-444444444444"
    "11111111-1111-1111-2222-444444444444"
    ...
    ```
  </Tab>

  <Tab title="PHP">
    **Code:**

    ```php theme={null}
    $pages = $seam->createPaginator(
        fn($p) => $seam->devices->list(...$p),
        ["limit" => 20]
    );

    foreach ($pages->flatten() as $device) {
        print $device->device_id . "\n";
    }
    ```

    **Output:**

    ```json theme={null}
    "11111111-1111-1111-1111-444444444444"
    "11111111-1111-1111-2222-444444444444"
    ...
    ```
  </Tab>

  <Tab title="C#">
    **Code:**

    ```csharp theme={null}
    // Coming soon!
    ```

    **Output:**

    ```json theme={null}
    // Coming soon!
    ```
  </Tab>
</Tabs>

***

## Return All Resources Across All Pages as an Array

You can iterate over all resources within all pages and return a single array or list.

The following example returns an array containing all devices:

<Tabs>
  <Tab title="JavaScript">
    **Code:**

    ```javascript theme={null}
    const pages = seam.createPaginator(
      seam.devices.list({
        limit: 20,
      }),
    )

    const devices = await pages.flattenToArray()
    ```

    **Output:**

    ```json theme={null}
    [
      {
        device_id: '11111111-1111-1111-1111-444444444444',
        ...
      },
      {
        device_id: '11111111-1111-1111-2222-444444444444',
        ...
      },
      ...
    ]
    ```
  </Tab>

  <Tab title="cURL">
    **Request:**

    ```bash theme={null}
    # Get the first page.
    # Use GET or POST.
    response=$(curl -X 'GET' \
      'https://connect.getseam.com/devices/list' \
      -H 'accept: application/json' \
      -H "Authorization: Bearer ${SEAM_API_KEY}" \
      -H 'Content-Type: application/json' \
      -d '{
        "limit": 20
      }')

    # Process all pages.
    while true; do
      # Extract all devices from the current page and add them
      # the all_devices array.
        devices=$(echo "$response" | jq -c '.devices[]')
        while IFS= read -r device; do
            [ -n "$device" ] && all_devices+=("$device")
        done <<< "$devices"

      # Check whether there are more pages.
      has_next=$(echo "$response" | jq -r '.pagination.has_next_page')
      if [ "$has_next" != "true" ]; then
          break
      fi

      # Get the next page cursor.
      next_cursor=$(echo "$response" | jq -r '.pagination.next_page_cursor')
      if [ -z "$next_cursor" ] || [ "$next_cursor" = "null" ]; then
          break
      fi

      # Fetch the next page.
      response=$(curl -X 'GET' \
      'https://connect.getseam.com/devices/list' \
      -H 'accept: application/json' \
      -H "Authorization: Bearer ${SEAM_API_KEY}" \
      -H 'Content-Type: application/json' \
      -d "{
        \"limit\": 20,
        \"page_cursor\": \"${next_cursor}\"
      }")
    done
    ```

    **Response:**

    ```json theme={null}
    [
      {
        device_id: '11111111-1111-1111-1111-444444444444',
        ...
      },
      {
        device_id: '11111111-1111-1111-2222-444444444444',
        ...
      },
      ...
    ]
    ```
  </Tab>

  <Tab title="Python">
    **Code:**

    ```python theme={null}
    paginator = seam.create_paginator(seam.devices.list, {"limit": 20})

    all_devices = paginator.flatten_to_list()
    ```

    **Output:**

    ```
    [
      Device(
        device_id='11111111-1111-1111-1111-444444444444',
        ...
      ),
      Device(
        device_id='11111111-1111-1111-2222-444444444444',
        ...
      ),
      ...
    ]
    ```
  </Tab>

  <Tab title="Ruby">
    **Code:**

    ```ruby theme={null}
    paginator = seam.create_paginator(seam.devices.method(:list), {limit: 20})

    all_devices = paginator.flatten_to_list
    ```

    **Output:**

    ```
    [
      <Seam::Device:0x004d8
        device_id="11111111-1111-1111-1111-444444444444"
        ...
        >,
      <Seam::Device:0x004d8
        device_id="11111111-1111-1111-2222-444444444444"
        ...
        >,
      ...
    ]
    ```
  </Tab>

  <Tab title="PHP">
    **Code:**

    ```php theme={null}
    $pages = $seam->createPaginator(
        fn($p) => $seam->devices->list(...$p),
        ["limit" => 20]
    );

    $deviecs = $pages->flattenToArray();
    ```

    **Output:**

    ```json theme={null}
    [
      {
        "device_id": "11111111-1111-1111-1111-444444444444",
        ...
      },
      {
        "device_id": "11111111-1111-1111-2222-444444444444",
        ...
      },
      ...
    ]
    ```
  </Tab>

  <Tab title="C#">
    **Code:**

    ```csharp theme={null}
    // Coming soon!
    ```

    **Output:**

    ```json theme={null}
    // Coming soon!
    ```
  </Tab>
</Tabs>


# Deactivate a Phone
Source: https://docs.seam.co/api/phones/deactivate

/openapi.json post /phones/deactivate
Deactivates a phone, which is useful, for example, if a user has lost their phone. For more information, see [App User Lost Phone Process](/capability-guides/mobile-access/managing-phones-for-a-user-identity#app-user-lost-phone-process).



# Phone Warnings
Source: https://docs.seam.co/api/phones/errors

Warnings that Seam reports on the Phone resource, each with its code and meaning.

## Warnings

Each warning is an object with the following shape:

```json Example warning theme={null}
{
  "warning_code": "unknown_issue_with_phone",
  "message": "Indicates that an unknown issue occurred while syncing the state of the phone with the provider. This issue may affect the proper functioning of the phone.",
  "created_at": "2025-01-01T00:00:00.000Z"
}
```

<Accordion title="Warning object properties">
  <ResponseField name="warning_code" type="Enum (String)">
    Unique identifier of the type of warning. Enables quick recognition and categorization of the issue.

    One of the warning codes listed below.
  </ResponseField>

  <ResponseField name="message" type="String">
    Detailed description of the warning. Provides insights into the issue and potentially how to rectify it.
  </ResponseField>

  <ResponseField name="created_at" type="String (ISO 8601)">
    Date and time at which Seam created the warning.
  </ResponseField>
</Accordion>

### `unknown_issue_with_phone`

Indicates that an unknown issue occurred while syncing the state of the phone with the provider. This issue may affect the proper functioning of the phone.

***


# Phone Events
Source: https://docs.seam.co/api/phones/events

Webhook events that Seam emits for the Phone resource, with example payloads and properties.

## `phone.deactivated`

A phone device was deactivated.

<ResponseExample>
  ```json Example webhook payload theme={null}
  {
    "created_at": "2025-01-01T00:00:00.000Z",
    "device_custom_metadata": {},
    "device_id": "00000000-0000-0000-0000-000000000000",
    "event_description": "A phone device was deactivated.",
    "event_id": "00000000-0000-0000-0000-000000000000",
    "event_type": "phone.deactivated",
    "occurred_at": "2025-01-01T00:00:00.000Z",
    "workspace_id": "00000000-0000-0000-0000-000000000000"
  }
  ```
</ResponseExample>

<Accordion title="Properties">
  <ResponseField name="created_at" type="String (ISO 8601)">
    Date and time at which the event was created.
  </ResponseField>

  <ResponseField name="device_custom_metadata" type="Object">
    Custom metadata of the device; present when device\_id is provided.
  </ResponseField>

  <ResponseField name="device_id" type="String (UUID)">
    ID of the affected phone device.
  </ResponseField>

  <ResponseField name="event_description" type="String">
    Human-readable description of the event. Persisted when the event is created (so the creating code, including a provider, can supply a tailored description) and otherwise derived from the event.
  </ResponseField>

  <ResponseField name="event_id" type="String (UUID)">
    ID of the event.
  </ResponseField>

  <ResponseField name="event_type" type="Enum (String)">
    Value: `phone.deactivated`
  </ResponseField>

  <ResponseField name="occurred_at" type="String (ISO 8601)">
    Date and time at which the event occurred.
  </ResponseField>

  <ResponseField name="workspace_id" type="String (UUID)">
    ID of the workspace associated with the event.
  </ResponseField>
</Accordion>


# Get a Phone
Source: https://docs.seam.co/api/phones/get

/openapi.json post /phones/get
Returns a specified [phone](/capability-guides/mobile-access/managing-phones-for-a-user-identity).



# List Phones
Source: https://docs.seam.co/api/phones/list

/openapi.json post /phones/list
Returns a list of all [phones](/capability-guides/mobile-access/managing-phones-for-a-user-identity). To filter the list of returned phones by a specific owner user identity or credential, include the `owner_user_identity_id` or `acs_credential_id`, respectively, in the request body.



# The Phone Object
Source: https://docs.seam.co/api/phones/object

Learn how the phone object represents an app user mobile phone that holds mobile credentials, including its properties and lifecycle events.

## The phone Object

Represents an app user's mobile phone.

<ResponseExample>
  ```json Phone theme={null}
  {
    "created_at": "2025-06-14T16:54:17.946540Z",
    "custom_metadata": {
      "id": "internalId1"
    },
    "device_id": "e452f665-a635-4c65-922b-9feab0e0f84f",
    "device_type": "ios_phone",
    "display_name": "My Phone",
    "errors": [],
    "nickname": "My Phone",
    "properties": {
      "assa_abloy_credential_service_metadata": {
        "endpoints": [
          {
            "endpoint_id": "c7d8e9f0-1a2b-3c4d-5e6f-7a8b9c0d1e2f",
            "is_active": true
          }
        ],
        "has_active_endpoint": true
      }
    },
    "warnings": [],
    "workspace_id": "da8639a4-28a2-4884-a4f9-b7691f4cf336"
  }
  ```
</ResponseExample>

***

## Properties

<ResponseField name="created_at" type="String (ISO 8601)">
  Date and time at which the phone was created.
</ResponseField>

<ResponseField name="custom_metadata" type="Object">
  Optional [custom metadata](/core-concepts/devices/adding-custom-metadata-to-a-device) for the phone.
</ResponseField>

<ResponseField name="device_id" type="String (UUID)">
  ID of the phone.
</ResponseField>

<ResponseField name="device_type" type="Enum (String)">
  Type of the phone device, such as `ios_phone` or `android_phone`.
</ResponseField>

<ResponseField name="display_name" type="String">
  Display name of the phone. Defaults to `nickname` (if it is set) or `properties.appearance.name`, otherwise. Enables administrators and users to identify the phone easily, especially when there are numerous phones.
</ResponseField>

<ResponseField name="errors" type="Array">
  Errors associated with the phone.

  <Expandable title="properties">
    <ResponseField name="created_at" type="String (ISO 8601)">
      Date and time at which Seam created the error.
    </ResponseField>

    <ResponseField name="error_code" type="String">
      Unique identifier of the type of error.
    </ResponseField>

    <ResponseField name="message" type="String">
      Detailed description of the error.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="nickname" type="String">
  Optional nickname to describe the phone, settable through Seam.
</ResponseField>

<ResponseField name="properties" type="Object">
  Properties of the phone.

  <Expandable title="properties">
    <ResponseField name="assa_abloy_credential_service_metadata" type="Object">
      ASSA ABLOY Credential Service metadata for the phone.

      <Expandable title="properties">
        <ResponseField name="endpoints" type="Array">
          Endpoints associated with the phone.

          <Expandable title="properties">
            <ResponseField name="endpoint_id" type="String">
              ID of the associated endpoint.
            </ResponseField>

            <ResponseField name="is_active" type="Boolean">
              Indicated whether the endpoint is active.
            </ResponseField>
          </Expandable>
        </ResponseField>

        <ResponseField name="has_active_endpoint" type="Boolean">
          Indicates whether the credential service has active endpoints associated with the phone.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="salto_space_credential_service_metadata" type="Object">
      Salto Space credential service metadata for the phone.

      <Expandable title="properties">
        <ResponseField name="has_active_phone" type="Boolean">
          Indicates whether the credential service has an active associated phone.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="warnings" type="Array">
  Warnings associated with the phone.

  <Expandable title="properties">
    <ResponseField name="created_at" type="String (ISO 8601)">
      Date and time at which Seam created the warning.
    </ResponseField>

    <ResponseField name="message" type="String">
      Detailed description of the warning.
    </ResponseField>

    <ResponseField name="warning_code" type="String">
      Unique identifier of the type of warning.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="workspace_id" type="String (UUID)">
  ID of the workspace that contains the phone.
</ResponseField>

## phone.properties

<ResponseField name="assa_abloy_credential_service_metadata" type="Object">
  ASSA ABLOY Credential Service metadata for the phone.

  <Expandable title="properties">
    <ResponseField name="endpoints" type="Array">
      Endpoints associated with the phone.

      <Expandable title="properties">
        <ResponseField name="endpoint_id" type="String">
          ID of the associated endpoint.
        </ResponseField>

        <ResponseField name="is_active" type="Boolean">
          Indicated whether the endpoint is active.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="has_active_endpoint" type="Boolean">
      Indicates whether the credential service has active endpoints associated with the phone.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="salto_space_credential_service_metadata" type="Object">
  Salto Space credential service metadata for the phone.

  <Expandable title="properties">
    <ResponseField name="has_active_phone" type="Boolean">
      Indicates whether the credential service has an active associated phone.
    </ResponseField>
  </Expandable>
</ResponseField>


# Create a Sandbox Phone
Source: https://docs.seam.co/api/phones/simulate/create_sandbox_phone

/openapi.json post /phones/simulate/create_sandbox_phone
Creates a new simulated phone in a [sandbox workspace](/core-concepts/workspaces#sandbox-workspaces). See also [Creating a Simulated Phone for a User Identity](/capability-guides/mobile-access/developing-in-a-sandbox-workspace#creating-a-simulated-phone-for-a-user-identity).



# Rate Limits and Guardrails
Source: https://docs.seam.co/api/rate-limits-and-guardrails

Learn the Seam API rate limits and guardrails, how 429 Too Many Requests responses work, and how to retry requests for reliable device load.

In order to provide reliable service for all of our customers and API load predictability for our device partners, we have a number of rate limits and guardrails in place.

## Rate Limits

For requests with rate limits, exceeding these limits results in the corresponding API calls failing with a `429 Too Many Requests` response. You must then retry your request after the appropriate amount of time.

We enforce the following rate limits on a per-device basis:

<table>
  <thead>
    <tr>
      <th>Operation</th>
      <th>Limit</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        <a href="/api/access_codes/create">
          Create an access code
        </a>
      </td>

      <td>10 access code creations per minute</td>
    </tr>

    <tr>
      <td>
        <a href="/api/access_codes/update">
          Update an access code
        </a>
      </td>

      <td>10 access code updates per minute</td>
    </tr>

    <tr>
      <td>
        <a href="/api/access_codes/delete">
          Delete an access code
        </a>
      </td>

      <td>20 access code deletions per minute</td>
    </tr>

    <tr>
      <td>
        <a href="/api/locks/lock_door">
          Lock a lock
        </a>
      </td>

      <td>15 lock requests per minute</td>
    </tr>

    <tr>
      <td>
        <a href="/api/locks/unlock_door">
          Unlock a lock
        </a>
      </td>

      <td>15 unlock requests per minute</td>
    </tr>
  </tbody>
</table>


# Add Entrances to a Space
Source: https://docs.seam.co/api/spaces/add_acs_entrances

/openapi.json post /spaces/add_acs_entrances
Adds [entrances](/low-level-apis/access-systems/retrieving-entrance-details) to a specific space.



# Add a Connected Account to a Space
Source: https://docs.seam.co/api/spaces/add_connected_account

/openapi.json post /spaces/add_connected_account
Adds a [connected account](/core-concepts/connected-accounts) to a specific space.



# Add Devices to a Space
Source: https://docs.seam.co/api/spaces/add_devices

/openapi.json post /spaces/add_devices
Adds devices to a specific space.



# Create a Space
Source: https://docs.seam.co/api/spaces/create

/openapi.json post /spaces/create
Creates a new space.



# Delete a Space
Source: https://docs.seam.co/api/spaces/delete

/openapi.json post /spaces/delete
Deletes a space.



# Space Events
Source: https://docs.seam.co/api/spaces/events

Webhook events that Seam emits for the Space resource, with example payloads and properties.

## `space.device_membership_changed`

A device was added or removed from a space.

<ResponseExample>
  ```json Example webhook payload theme={null}
  {
    "acs_entrance_ids": [],
    "created_at": "2025-01-01T00:00:00.000Z",
    "device_ids": [],
    "event_description": "A device was added or removed from a space.",
    "event_id": "00000000-0000-0000-0000-000000000000",
    "event_type": "space.device_membership_changed",
    "occurred_at": "2025-01-01T00:00:00.000Z",
    "space_id": "00000000-0000-0000-0000-000000000000",
    "space_key": "",
    "workspace_id": "00000000-0000-0000-0000-000000000000"
  }
  ```
</ResponseExample>

<Accordion title="Properties">
  <ResponseField name="acs_entrance_ids" type="Array">
    IDs of all ACS entrances currently attached to the space.
  </ResponseField>

  <ResponseField name="created_at" type="String (ISO 8601)">
    Date and time at which the event was created.
  </ResponseField>

  <ResponseField name="device_ids" type="Array">
    IDs of all devices currently attached to the space.
  </ResponseField>

  <ResponseField name="event_description" type="String">
    Human-readable description of the event. Persisted when the event is created (so the creating code, including a provider, can supply a tailored description) and otherwise derived from the event.
  </ResponseField>

  <ResponseField name="event_id" type="String (UUID)">
    ID of the event.
  </ResponseField>

  <ResponseField name="event_type" type="Enum (String)">
    Value: `space.device_membership_changed`
  </ResponseField>

  <ResponseField name="occurred_at" type="String (ISO 8601)">
    Date and time at which the event occurred.
  </ResponseField>

  <ResponseField name="space_id" type="String (UUID)">
    ID of the affected space.
  </ResponseField>

  <ResponseField name="space_key" type="String">
    Unique key for the space within the workspace.
  </ResponseField>

  <ResponseField name="workspace_id" type="String (UUID)">
    ID of the workspace associated with the event.
  </ResponseField>
</Accordion>

## `space.created`

A space was created.

<ResponseExample>
  ```json Example webhook payload theme={null}
  {
    "acs_entrance_ids": [],
    "created_at": "2025-01-01T00:00:00.000Z",
    "device_ids": [],
    "event_description": "A space was created.",
    "event_id": "00000000-0000-0000-0000-000000000000",
    "event_type": "space.created",
    "occurred_at": "2025-01-01T00:00:00.000Z",
    "space_id": "00000000-0000-0000-0000-000000000000",
    "space_key": "",
    "workspace_id": "00000000-0000-0000-0000-000000000000"
  }
  ```
</ResponseExample>

<Accordion title="Properties">
  <ResponseField name="acs_entrance_ids" type="Array">
    IDs of all ACS entrances attached to the space when it was created.
  </ResponseField>

  <ResponseField name="created_at" type="String (ISO 8601)">
    Date and time at which the event was created.
  </ResponseField>

  <ResponseField name="device_ids" type="Array">
    IDs of all devices attached to the space when it was created.
  </ResponseField>

  <ResponseField name="event_description" type="String">
    Human-readable description of the event. Persisted when the event is created (so the creating code, including a provider, can supply a tailored description) and otherwise derived from the event.
  </ResponseField>

  <ResponseField name="event_id" type="String (UUID)">
    ID of the event.
  </ResponseField>

  <ResponseField name="event_type" type="Enum (String)">
    Value: `space.created`
  </ResponseField>

  <ResponseField name="occurred_at" type="String (ISO 8601)">
    Date and time at which the event occurred.
  </ResponseField>

  <ResponseField name="space_id" type="String (UUID)">
    ID of the affected space.
  </ResponseField>

  <ResponseField name="space_key" type="String">
    Unique key for the space within the workspace.
  </ResponseField>

  <ResponseField name="workspace_id" type="String (UUID)">
    ID of the workspace associated with the event.
  </ResponseField>
</Accordion>

## `space.deleted`

A space was deleted.

<ResponseExample>
  ```json Example webhook payload theme={null}
  {
    "acs_entrance_ids": [],
    "created_at": "2025-01-01T00:00:00.000Z",
    "device_ids": [],
    "event_description": "A space was deleted.",
    "event_id": "00000000-0000-0000-0000-000000000000",
    "event_type": "space.deleted",
    "occurred_at": "2025-01-01T00:00:00.000Z",
    "space_id": "00000000-0000-0000-0000-000000000000",
    "space_key": "",
    "workspace_id": "00000000-0000-0000-0000-000000000000"
  }
  ```
</ResponseExample>

<Accordion title="Properties">
  <ResponseField name="acs_entrance_ids" type="Array">
    IDs of all ACS entrances currently attached to the space when it was deleted.
  </ResponseField>

  <ResponseField name="created_at" type="String (ISO 8601)">
    Date and time at which the event was created.
  </ResponseField>

  <ResponseField name="device_ids" type="Array">
    IDs of all devices attached to the space when it was deleted.
  </ResponseField>

  <ResponseField name="event_description" type="String">
    Human-readable description of the event. Persisted when the event is created (so the creating code, including a provider, can supply a tailored description) and otherwise derived from the event.
  </ResponseField>

  <ResponseField name="event_id" type="String (UUID)">
    ID of the event.
  </ResponseField>

  <ResponseField name="event_type" type="Enum (String)">
    Value: `space.deleted`
  </ResponseField>

  <ResponseField name="occurred_at" type="String (ISO 8601)">
    Date and time at which the event occurred.
  </ResponseField>

  <ResponseField name="space_id" type="String (UUID)">
    ID of the affected space.
  </ResponseField>

  <ResponseField name="space_key" type="String">
    Unique key for the space within the workspace.
  </ResponseField>

  <ResponseField name="workspace_id" type="String (UUID)">
    ID of the workspace associated with the event.
  </ResponseField>
</Accordion>


# Get a Space
Source: https://docs.seam.co/api/spaces/get

/openapi.json post /spaces/get
Gets a space.

You must include at least one request parameter.



# Get related Space resources
Source: https://docs.seam.co/api/spaces/get_related

/openapi.json post /spaces/get_related
Gets all related resources for one or more Spaces.

You must include at least one request parameter.



# List Spaces
Source: https://docs.seam.co/api/spaces/list

/openapi.json post /spaces/list
Returns a list of all spaces.



# The Space Object
Source: https://docs.seam.co/api/spaces/object

Learn how the space object groups devices and entrances together so you can assign access to an entire space and grant access more efficiently.

## The space Object

Represents a space that is a logical grouping of devices and entrances. You can assign access to an entire space, thereby making granting access more efficient.

<ResponseExample>
  ```json Space theme={null}
  {
    "created_at": "2025-06-16T16:54:17.946600Z",
    "display_name": "My Space",
    "name": "My Space",
    "space_id": "5afeb047-3277-4102-b8c4-99edf05b91d2",
    "workspace_id": "96bd12f9-6def-4bf4-b517-760417451ae9"
  }
  ```
</ResponseExample>

***

## Properties

<ResponseField name="acs_entrance_count" type="number">
  Number of entrances in the space.
</ResponseField>

<ResponseField name="created_at" type="String (ISO 8601)">
  Date and time at which the space was created.
</ResponseField>

<ResponseField name="customer_data" type="Object">
  Reservation/stay-related defaults for the space. Also carries the provider/PMS-supplied name under a `<connector_type>_name` key (e.g. `guesty_name`), which Seam preserves when you rename the space (read-only — managed by Seam).

  <Expandable title="properties">
    <ResponseField name="address" type="String">
      Postal address for the space.
    </ResponseField>

    <ResponseField name="default_checkin_time" type="String">
      Default check-in time for reservations at the space, as HH:mm or HH:mm:ss.
    </ResponseField>

    <ResponseField name="default_checkout_time" type="String">
      Default check-out time for reservations at the space, as HH:mm or HH:mm:ss.
    </ResponseField>

    <ResponseField name="time_zone" type="String">
      IANA time zone for the space, e.g. America/Los\_Angeles.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="customer_key" type="String">
  Customer key associated with the space.
</ResponseField>

<ResponseField name="device_count" type="number">
  Number of devices in the space.
</ResponseField>

<ResponseField name="display_name" type="String">
  Display name for the space.
</ResponseField>

<ResponseField name="geolocation" type="Object">
  Geographic coordinates (latitude and longitude) of the space.

  <Expandable title="properties">
    <ResponseField name="latitude" type="number">
      Latitude of the space, in decimal degrees.
    </ResponseField>

    <ResponseField name="longitude" type="number">
      Longitude of the space, in decimal degrees.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="name" type="String">
  Name of the space.
</ResponseField>

<ResponseField name="space_id" type="String (UUID)">
  ID of the space.
</ResponseField>

<ResponseField name="space_key" type="String">
  Unique key for the space within the workspace.
</ResponseField>

<ResponseField name="workspace_id" type="String (UUID)">
  ID of the workspace associated with the space.
</ResponseField>


# Remove Entrances from a Space
Source: https://docs.seam.co/api/spaces/remove_acs_entrances

/openapi.json post /spaces/remove_acs_entrances
Removes [entrances](/low-level-apis/access-systems/retrieving-entrance-details) from a specific space.



# Remove a Connected Account from a Space
Source: https://docs.seam.co/api/spaces/remove_connected_account

/openapi.json post /spaces/remove_connected_account
Removes a [connected account](/core-concepts/connected-accounts) from a specific space.



# Remove Devices from a Space
Source: https://docs.seam.co/api/spaces/remove_devices

/openapi.json post /spaces/remove_devices
Removes devices from a specific space.



# Update a Space
Source: https://docs.seam.co/api/spaces/update

/openapi.json post /spaces/update
Updates an existing space.



# Activate a Climate Preset
Source: https://docs.seam.co/api/thermostats/activate_climate_preset

/openapi.json post /thermostats/activate_climate_preset
Activates a specified [climate preset](/capability-guides/thermostats/creating-and-managing-climate-presets) for a specified [thermostat](/capability-guides/thermostats).



# Set to Cool Mode
Source: https://docs.seam.co/api/thermostats/cool

/openapi.json post /thermostats/cool
Sets a specified [thermostat](/capability-guides/thermostats) to [cool mode](/capability-guides/thermostats/configure-current-climate-settings).



# Create a Climate Preset
Source: https://docs.seam.co/api/thermostats/create_climate_preset

/openapi.json post /thermostats/create_climate_preset
Creates a [climate preset](/capability-guides/thermostats/creating-and-managing-climate-presets) for a specified [thermostat](/capability-guides/thermostats).



# Create a Thermostat Daily Program
Source: https://docs.seam.co/api/thermostats/daily_programs/create

/openapi.json post /thermostats/daily_programs/create
Creates a new thermostat daily program. A daily program consists of a set of periods, where each period includes a start time and the key of a configured climate preset. Once you have defined a daily program, you can assign it to one or more days within a weekly program.



# Delete a Thermostat Daily Program
Source: https://docs.seam.co/api/thermostats/daily_programs/delete

/openapi.json post /thermostats/daily_programs/delete
Deletes a thermostat daily program.



# Daily Programs
Source: https://docs.seam.co/api/thermostats/daily_programs/object

Learn how the thermostat_daily_program object defines periods that each apply a climate preset at a starting time to automate a thermostat day.

## The thermostat\_daily\_program Object

Represents a thermostat daily program, consisting of a set of periods, each of which has a starting time and the key that identifies the climate preset to apply at the starting time.

<ResponseExample>
  ```json Thermostat Daily Program theme={null}
  {
    "created_at": "2025-06-14T16:54:17.946642Z",
    "device_id": "58437d45-47ac-4ee6-ab27-7b2d1f2947d1",
    "name": "Weekday Program",
    "periods": [
      {
        "starts_at_time": "07:00:00",
        "climate_preset_key": "Home"
      },
      {
        "starts_at_time": "09:00:00",
        "climate_preset_key": "Away"
      },
      {
        "starts_at_time": "16:00:00",
        "climate_preset_key": "Home"
      },
      {
        "starts_at_time": "22:30:00",
        "climate_preset_key": "Sleep"
      }
    ],
    "thermostat_daily_program_id": "ab8ef74c-c7cd-4100-aa32-0ef960c0080d",
    "workspace_id": "8da8d923-e55b-45cd-84a3-6c96b3d3d454"
  }
  ```
</ResponseExample>

***

## Properties

<ResponseField name="created_at" type="String (ISO 8601)">
  Date and time at which the thermostat daily program was created.
</ResponseField>

<ResponseField name="device_id" type="String (UUID)">
  ID of the thermostat device on which the thermostat daily program is configured.
</ResponseField>

<ResponseField name="name" type="String">
  User-friendly name to identify the thermostat daily program.
</ResponseField>

<ResponseField name="periods" type="Array">
  Array of thermostat daily program periods.

  <Expandable title="properties">
    <ResponseField name="climate_preset_key" type="String">
      Key of the [climate preset](/capability-guides/thermostats/creating-and-managing-climate-presets) to activate at the `starts_at_time`.
    </ResponseField>

    <ResponseField name="starts_at_time" type="String">
      Time at which the thermostat daily program period starts, in [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) format.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="thermostat_daily_program_id" type="String (UUID)">
  ID of the thermostat daily program.
</ResponseField>

<ResponseField name="workspace_id" type="String (UUID)">
  ID of the workspace that contains the thermostat daily program.
</ResponseField>


# Update a Thermostat Daily Program
Source: https://docs.seam.co/api/thermostats/daily_programs/update

/openapi.json post /thermostats/daily_programs/update
Updates a specified thermostat daily program. The periods that you specify overwrite any existing periods for the daily program.



# Delete a Climate Preset
Source: https://docs.seam.co/api/thermostats/delete_climate_preset

/openapi.json post /thermostats/delete_climate_preset
Deletes a specified [climate preset](/capability-guides/thermostats/creating-and-managing-climate-presets) for a specified [thermostat](/capability-guides/thermostats).



# Thermostat Errors and Warnings
Source: https://docs.seam.co/api/thermostats/errors

Errors and warnings that Seam reports on the Thermostat resource, each with its code and meaning.

<Note>
  These are Thermostat-specific errors and warnings. For errors and warnings common to all devices, see [Device Errors and Warnings](/api/devices/errors).
</Note>

## Errors

Each error is an object with the following shape:

```json Example error theme={null}
{
  "error_code": "auxiliary_heat_running",
  "message": "Indicates that the auxiliary heat is running.",
  "created_at": "2025-01-01T00:00:00.000Z",
  "is_device_error": true
}
```

<Accordion title="Error object properties">
  <ResponseField name="error_code" type="Enum (String)">
    Unique identifier of the type of error. Enables quick recognition and categorization of the issue.

    One of the error codes listed below.
  </ResponseField>

  <ResponseField name="message" type="String">
    Detailed description of the error. Provides insights into the issue and potentially how to rectify it.
  </ResponseField>

  <ResponseField name="created_at" type="String (ISO 8601)">
    Date and time at which Seam created the error.
  </ResponseField>

  <ResponseField name="is_device_error" type="Boolean">
    Indicates that the error is a device error.
  </ResponseField>
</Accordion>

### `auxiliary_heat_running`

Indicates that the auxiliary heat is running.

***

## Warnings

Each warning is an object with the following shape:

```json Example warning theme={null}
{
  "warning_code": "temperature_threshold_exceeded",
  "message": "Indicates that the temperature threshold has been exceeded.",
  "created_at": "2025-01-01T00:00:00.000Z"
}
```

<Accordion title="Warning object properties">
  <ResponseField name="warning_code" type="Enum (String)">
    Unique identifier of the type of warning. Enables quick recognition and categorization of the issue.

    One of the warning codes listed below.
  </ResponseField>

  <ResponseField name="message" type="String">
    Detailed description of the warning. Provides insights into the issue and potentially how to rectify it.
  </ResponseField>

  <ResponseField name="created_at" type="String (ISO 8601)">
    Date and time at which Seam created the warning.
  </ResponseField>
</Accordion>

### `temperature_threshold_exceeded`

Indicates that the temperature threshold has been exceeded.

***


# Thermostat Events
Source: https://docs.seam.co/api/thermostats/events

Webhook events that Seam emits for the Thermostat resource, with example payloads and properties.

## `thermostat.climate_preset_activated`

A thermostat [climate preset](/capability-guides/thermostats/creating-and-managing-climate-presets) was activated.

<ResponseExample>
  ```json Example webhook payload theme={null}
  {
    "climate_preset_key": "",
    "connected_account_custom_metadata": {},
    "connected_account_id": "00000000-0000-0000-0000-000000000000",
    "created_at": "2025-01-01T00:00:00.000Z",
    "customer_key": "",
    "device_custom_metadata": {},
    "device_id": "00000000-0000-0000-0000-000000000000",
    "event_description": "A thermostat [climate preset](/capability-guides/thermostats/creating-and-managing-climate-presets) was activated.",
    "event_id": "00000000-0000-0000-0000-000000000000",
    "event_type": "thermostat.climate_preset_activated",
    "is_fallback_climate_preset": true,
    "occurred_at": "2025-01-01T00:00:00.000Z",
    "thermostat_schedule_id": "00000000-0000-0000-0000-000000000000",
    "workspace_id": "00000000-0000-0000-0000-000000000000"
  }
  ```
</ResponseExample>

<Accordion title="Properties">
  <ResponseField name="climate_preset_key" type="String">
    Key of the climate preset that was activated.
  </ResponseField>

  <ResponseField name="connected_account_custom_metadata" type="Object">
    Custom metadata of the connected account, present when connected\_account\_id is provided.
  </ResponseField>

  <ResponseField name="connected_account_id" type="String (UUID)">
    ID of the connected account associated with the event.
  </ResponseField>

  <ResponseField name="created_at" type="String (ISO 8601)">
    Date and time at which the event was created.
  </ResponseField>

  <ResponseField name="customer_key" type="String">
    The customer key associated with the device, if any.
  </ResponseField>

  <ResponseField name="device_custom_metadata" type="Object">
    Custom metadata of the device, present when device\_id is provided.
  </ResponseField>

  <ResponseField name="device_id" type="String (UUID)">
    ID of the affected device.
  </ResponseField>

  <ResponseField name="event_description" type="String">
    Human-readable description of the event. Persisted when the event is created (so the creating code, including a provider, can supply a tailored description) and otherwise derived from the event.
  </ResponseField>

  <ResponseField name="event_id" type="String (UUID)">
    ID of the event.
  </ResponseField>

  <ResponseField name="event_type" type="Enum (String)">
    Value: `thermostat.climate_preset_activated`
  </ResponseField>

  <ResponseField name="is_fallback_climate_preset" type="Boolean">
    Indicates whether the climate preset that was activated is the fallback climate preset for the thermostat.
  </ResponseField>

  <ResponseField name="occurred_at" type="String (ISO 8601)">
    Date and time at which the event occurred.
  </ResponseField>

  <ResponseField name="thermostat_schedule_id" type="String (UUID)">
    ID of the thermostat schedule that prompted the affected climate preset to be activated.
  </ResponseField>

  <ResponseField name="workspace_id" type="String (UUID)">
    ID of the workspace associated with the event.
  </ResponseField>
</Accordion>

## `thermostat.manually_adjusted`

A [thermostat](/capability-guides/thermostats) was adjusted manually.

<ResponseExample>
  ```json Example webhook payload theme={null}
  {
    "connected_account_custom_metadata": {},
    "connected_account_id": "00000000-0000-0000-0000-000000000000",
    "cooling_set_point_celsius": 0,
    "cooling_set_point_fahrenheit": 0,
    "created_at": "2025-01-01T00:00:00.000Z",
    "customer_key": "",
    "device_custom_metadata": {},
    "device_id": "00000000-0000-0000-0000-000000000000",
    "event_description": "A [thermostat](/capability-guides/thermostats) was adjusted manually.",
    "event_id": "00000000-0000-0000-0000-000000000000",
    "event_type": "thermostat.manually_adjusted",
    "fan_mode_setting": "auto",
    "heating_set_point_celsius": 0,
    "heating_set_point_fahrenheit": 0,
    "hvac_mode_setting": "off",
    "method": "seam",
    "occurred_at": "2025-01-01T00:00:00.000Z",
    "workspace_id": "00000000-0000-0000-0000-000000000000"
  }
  ```
</ResponseExample>

<Accordion title="Properties">
  <ResponseField name="connected_account_custom_metadata" type="Object">
    Custom metadata of the connected account, present when connected\_account\_id is provided.
  </ResponseField>

  <ResponseField name="connected_account_id" type="String (UUID)">
    ID of the connected account associated with the event.
  </ResponseField>

  <ResponseField name="cooling_set_point_celsius" type="number">
    Temperature to which the thermostat should cool (in °C). See also [Set Points](/capability-guides/thermostats/understanding-thermostat-concepts/set-points).
  </ResponseField>

  <ResponseField name="cooling_set_point_fahrenheit" type="number">
    Temperature to which the thermostat should cool (in °F). See also [Set Points](/capability-guides/thermostats/understanding-thermostat-concepts/set-points).
  </ResponseField>

  <ResponseField name="created_at" type="String (ISO 8601)">
    Date and time at which the event was created.
  </ResponseField>

  <ResponseField name="customer_key" type="String">
    The customer key associated with the device, if any.
  </ResponseField>

  <ResponseField name="device_custom_metadata" type="Object">
    Custom metadata of the device, present when device\_id is provided.
  </ResponseField>

  <ResponseField name="device_id" type="String (UUID)">
    ID of the affected device.
  </ResponseField>

  <ResponseField name="event_description" type="String">
    Human-readable description of the event. Persisted when the event is created (so the creating code, including a provider, can supply a tailored description) and otherwise derived from the event.
  </ResponseField>

  <ResponseField name="event_id" type="String (UUID)">
    ID of the event.
  </ResponseField>

  <ResponseField name="event_type" type="Enum (String)">
    Value: `thermostat.manually_adjusted`
  </ResponseField>

  <ResponseField name="fan_mode_setting" type="Enum (String)">
    Desired [fan mode setting](/capability-guides/thermostats/configure-current-climate-settings#fan-mode-settings), such as `on`, `auto`, or `circulate`.

    Possible values: `auto`, `on`, `circulate`
  </ResponseField>

  <ResponseField name="heating_set_point_celsius" type="number">
    Temperature to which the thermostat should heat (in °C). See also [Set Points](/capability-guides/thermostats/understanding-thermostat-concepts/set-points).
  </ResponseField>

  <ResponseField name="heating_set_point_fahrenheit" type="number">
    Temperature to which the thermostat should heat (in °F). See also [Set Points](/capability-guides/thermostats/understanding-thermostat-concepts/set-points).
  </ResponseField>

  <ResponseField name="hvac_mode_setting" type="Enum (String)">
    Desired [HVAC mode](/capability-guides/thermostats/understanding-thermostat-concepts/hvac-mode) setting, such as `heat`, `cool`, `heat_cool`, or `off`.

    Possible values: `off`, `heat`, `cool`, `heat_cool`, `eco`
  </ResponseField>

  <ResponseField name="method" type="Enum (String)">
    Method used to adjust the affected thermostat manually. `seam` indicates that the Seam API, Seam CLI, or Seam Console was used to adjust the thermostat.

    Possible values: `seam`, `external`
  </ResponseField>

  <ResponseField name="occurred_at" type="String (ISO 8601)">
    Date and time at which the event occurred.
  </ResponseField>

  <ResponseField name="workspace_id" type="String (UUID)">
    ID of the workspace associated with the event.
  </ResponseField>
</Accordion>

## `thermostat.temperature_threshold_exceeded`

A [thermostat's](/capability-guides/thermostats) temperature reading exceeded the set [threshold](/capability-guides/thermostats/setting-and-monitoring-temperature-thresholds).

<ResponseExample>
  ```json Example webhook payload theme={null}
  {
    "connected_account_custom_metadata": {},
    "connected_account_id": "00000000-0000-0000-0000-000000000000",
    "created_at": "2025-01-01T00:00:00.000Z",
    "customer_key": "",
    "device_custom_metadata": {},
    "device_id": "00000000-0000-0000-0000-000000000000",
    "event_description": "A [thermostat's](/capability-guides/thermostats) temperature reading exceeded the set [threshold](/capability-guides/thermostats/setting-and-monitoring-temperature-thresholds).",
    "event_id": "00000000-0000-0000-0000-000000000000",
    "event_type": "thermostat.temperature_threshold_exceeded",
    "lower_limit_celsius": 0,
    "lower_limit_fahrenheit": 0,
    "occurred_at": "2025-01-01T00:00:00.000Z",
    "temperature_celsius": 0,
    "temperature_fahrenheit": 0,
    "upper_limit_celsius": 0,
    "upper_limit_fahrenheit": 0,
    "workspace_id": "00000000-0000-0000-0000-000000000000"
  }
  ```
</ResponseExample>

<Accordion title="Properties">
  <ResponseField name="connected_account_custom_metadata" type="Object">
    Custom metadata of the connected account, present when connected\_account\_id is provided.
  </ResponseField>

  <ResponseField name="connected_account_id" type="String (UUID)">
    ID of the connected account associated with the event.
  </ResponseField>

  <ResponseField name="created_at" type="String (ISO 8601)">
    Date and time at which the event was created.
  </ResponseField>

  <ResponseField name="customer_key" type="String">
    The customer key associated with the device, if any.
  </ResponseField>

  <ResponseField name="device_custom_metadata" type="Object">
    Custom metadata of the device, present when device\_id is provided.
  </ResponseField>

  <ResponseField name="device_id" type="String (UUID)">
    ID of the affected device.
  </ResponseField>

  <ResponseField name="event_description" type="String">
    Human-readable description of the event. Persisted when the event is created (so the creating code, including a provider, can supply a tailored description) and otherwise derived from the event.
  </ResponseField>

  <ResponseField name="event_id" type="String (UUID)">
    ID of the event.
  </ResponseField>

  <ResponseField name="event_type" type="Enum (String)">
    Value: `thermostat.temperature_threshold_exceeded`
  </ResponseField>

  <ResponseField name="lower_limit_celsius" type="number">
    Lower temperature limit, in °C, defined by the set threshold.
  </ResponseField>

  <ResponseField name="lower_limit_fahrenheit" type="number">
    Lower temperature limit, in °F, defined by the set threshold.
  </ResponseField>

  <ResponseField name="occurred_at" type="String (ISO 8601)">
    Date and time at which the event occurred.
  </ResponseField>

  <ResponseField name="temperature_celsius" type="number">
    Temperature, in °C, reported by the affected thermostat.
  </ResponseField>

  <ResponseField name="temperature_fahrenheit" type="number">
    Temperature, in °F, reported by the affected thermostat.
  </ResponseField>

  <ResponseField name="upper_limit_celsius" type="number">
    Upper temperature limit, in °C, defined by the set threshold.
  </ResponseField>

  <ResponseField name="upper_limit_fahrenheit" type="number">
    Upper temperature limit, in °F, defined by the set threshold.
  </ResponseField>

  <ResponseField name="workspace_id" type="String (UUID)">
    ID of the workspace associated with the event.
  </ResponseField>
</Accordion>

## `thermostat.temperature_threshold_no_longer_exceeded`

A [thermostat's](/capability-guides/thermostats) temperature reading no longer exceeds the set [threshold](/capability-guides/thermostats/setting-and-monitoring-temperature-thresholds).

<ResponseExample>
  ```json Example webhook payload theme={null}
  {
    "connected_account_custom_metadata": {},
    "connected_account_id": "00000000-0000-0000-0000-000000000000",
    "created_at": "2025-01-01T00:00:00.000Z",
    "customer_key": "",
    "device_custom_metadata": {},
    "device_id": "00000000-0000-0000-0000-000000000000",
    "event_description": "A [thermostat's](/capability-guides/thermostats) temperature reading no longer exceeds the set [threshold](/capability-guides/thermostats/setting-and-monitoring-temperature-thresholds).",
    "event_id": "00000000-0000-0000-0000-000000000000",
    "event_type": "thermostat.temperature_threshold_no_longer_exceeded",
    "lower_limit_celsius": 0,
    "lower_limit_fahrenheit": 0,
    "occurred_at": "2025-01-01T00:00:00.000Z",
    "temperature_celsius": 0,
    "temperature_fahrenheit": 0,
    "upper_limit_celsius": 0,
    "upper_limit_fahrenheit": 0,
    "workspace_id": "00000000-0000-0000-0000-000000000000"
  }
  ```
</ResponseExample>

<Accordion title="Properties">
  <ResponseField name="connected_account_custom_metadata" type="Object">
    Custom metadata of the connected account, present when connected\_account\_id is provided.
  </ResponseField>

  <ResponseField name="connected_account_id" type="String (UUID)">
    ID of the connected account associated with the event.
  </ResponseField>

  <ResponseField name="created_at" type="String (ISO 8601)">
    Date and time at which the event was created.
  </ResponseField>

  <ResponseField name="customer_key" type="String">
    The customer key associated with the device, if any.
  </ResponseField>

  <ResponseField name="device_custom_metadata" type="Object">
    Custom metadata of the device, present when device\_id is provided.
  </ResponseField>

  <ResponseField name="device_id" type="String (UUID)">
    ID of the affected device.
  </ResponseField>

  <ResponseField name="event_description" type="String">
    Human-readable description of the event. Persisted when the event is created (so the creating code, including a provider, can supply a tailored description) and otherwise derived from the event.
  </ResponseField>

  <ResponseField name="event_id" type="String (UUID)">
    ID of the event.
  </ResponseField>

  <ResponseField name="event_type" type="Enum (String)">
    Value: `thermostat.temperature_threshold_no_longer_exceeded`
  </ResponseField>

  <ResponseField name="lower_limit_celsius" type="number">
    Lower temperature limit, in °C, defined by the set threshold.
  </ResponseField>

  <ResponseField name="lower_limit_fahrenheit" type="number">
    Lower temperature limit, in °F, defined by the set threshold.
  </ResponseField>

  <ResponseField name="occurred_at" type="String (ISO 8601)">
    Date and time at which the event occurred.
  </ResponseField>

  <ResponseField name="temperature_celsius" type="number">
    Temperature, in °C, reported by the affected thermostat.
  </ResponseField>

  <ResponseField name="temperature_fahrenheit" type="number">
    Temperature, in °F, reported by the affected thermostat.
  </ResponseField>

  <ResponseField name="upper_limit_celsius" type="number">
    Upper temperature limit, in °C, defined by the set threshold.
  </ResponseField>

  <ResponseField name="upper_limit_fahrenheit" type="number">
    Upper temperature limit, in °F, defined by the set threshold.
  </ResponseField>

  <ResponseField name="workspace_id" type="String (UUID)">
    ID of the workspace associated with the event.
  </ResponseField>
</Accordion>

## `thermostat.temperature_reached_set_point`

A [thermostat's](/capability-guides/thermostats) temperature reading is within 1 °C of the configured cooling or heating [set point](/capability-guides/thermostats/understanding-thermostat-concepts/set-points).

<ResponseExample>
  ```json Example webhook payload theme={null}
  {
    "connected_account_custom_metadata": {},
    "connected_account_id": "00000000-0000-0000-0000-000000000000",
    "created_at": "2025-01-01T00:00:00.000Z",
    "customer_key": "",
    "desired_temperature_celsius": 0,
    "desired_temperature_fahrenheit": 0,
    "device_custom_metadata": {},
    "device_id": "00000000-0000-0000-0000-000000000000",
    "event_description": "A [thermostat's](/capability-guides/thermostats) temperature reading is within 1 °C of the configured cooling or heating [set point](/capability-guides/thermostats/understanding-thermostat-concepts/set-points).",
    "event_id": "00000000-0000-0000-0000-000000000000",
    "event_type": "thermostat.temperature_reached_set_point",
    "occurred_at": "2025-01-01T00:00:00.000Z",
    "temperature_celsius": 0,
    "temperature_fahrenheit": 0,
    "workspace_id": "00000000-0000-0000-0000-000000000000"
  }
  ```
</ResponseExample>

<Accordion title="Properties">
  <ResponseField name="connected_account_custom_metadata" type="Object">
    Custom metadata of the connected account, present when connected\_account\_id is provided.
  </ResponseField>

  <ResponseField name="connected_account_id" type="String (UUID)">
    ID of the connected account associated with the event.
  </ResponseField>

  <ResponseField name="created_at" type="String (ISO 8601)">
    Date and time at which the event was created.
  </ResponseField>

  <ResponseField name="customer_key" type="String">
    The customer key associated with the device, if any.
  </ResponseField>

  <ResponseField name="desired_temperature_celsius" type="number">
    Desired temperature, in °C, defined by the affected thermostat's cooling or heating set point.
  </ResponseField>

  <ResponseField name="desired_temperature_fahrenheit" type="number">
    Desired temperature, in °F, defined by the affected thermostat's cooling or heating set point.
  </ResponseField>

  <ResponseField name="device_custom_metadata" type="Object">
    Custom metadata of the device, present when device\_id is provided.
  </ResponseField>

  <ResponseField name="device_id" type="String (UUID)">
    ID of the affected device.
  </ResponseField>

  <ResponseField name="event_description" type="String">
    Human-readable description of the event. Persisted when the event is created (so the creating code, including a provider, can supply a tailored description) and otherwise derived from the event.
  </ResponseField>

  <ResponseField name="event_id" type="String (UUID)">
    ID of the event.
  </ResponseField>

  <ResponseField name="event_type" type="Enum (String)">
    Value: `thermostat.temperature_reached_set_point`
  </ResponseField>

  <ResponseField name="occurred_at" type="String (ISO 8601)">
    Date and time at which the event occurred.
  </ResponseField>

  <ResponseField name="temperature_celsius" type="number">
    Temperature, in °C, reported by the affected thermostat.
  </ResponseField>

  <ResponseField name="temperature_fahrenheit" type="number">
    Temperature, in °F, reported by the affected thermostat.
  </ResponseField>

  <ResponseField name="workspace_id" type="String (UUID)">
    ID of the workspace associated with the event.
  </ResponseField>
</Accordion>

## `thermostat.temperature_changed`

A [thermostat's](/capability-guides/thermostats) reported temperature changed by at least 1 °C.

<ResponseExample>
  ```json Example webhook payload theme={null}
  {
    "connected_account_custom_metadata": {},
    "connected_account_id": "00000000-0000-0000-0000-000000000000",
    "created_at": "2025-01-01T00:00:00.000Z",
    "customer_key": "",
    "device_custom_metadata": {},
    "device_id": "00000000-0000-0000-0000-000000000000",
    "event_description": "A [thermostat's](/capability-guides/thermostats) reported temperature changed by at least 1 °C.",
    "event_id": "00000000-0000-0000-0000-000000000000",
    "event_type": "thermostat.temperature_changed",
    "occurred_at": "2025-01-01T00:00:00.000Z",
    "temperature_celsius": 0,
    "temperature_fahrenheit": 0,
    "workspace_id": "00000000-0000-0000-0000-000000000000"
  }
  ```
</ResponseExample>

<Accordion title="Properties">
  <ResponseField name="connected_account_custom_metadata" type="Object">
    Custom metadata of the connected account, present when connected\_account\_id is provided.
  </ResponseField>

  <ResponseField name="connected_account_id" type="String (UUID)">
    ID of the connected account associated with the event.
  </ResponseField>

  <ResponseField name="created_at" type="String (ISO 8601)">
    Date and time at which the event was created.
  </ResponseField>

  <ResponseField name="customer_key" type="String">
    The customer key associated with the device, if any.
  </ResponseField>

  <ResponseField name="device_custom_metadata" type="Object">
    Custom metadata of the device, present when device\_id is provided.
  </ResponseField>

  <ResponseField name="device_id" type="String (UUID)">
    ID of the affected device.
  </ResponseField>

  <ResponseField name="event_description" type="String">
    Human-readable description of the event. Persisted when the event is created (so the creating code, including a provider, can supply a tailored description) and otherwise derived from the event.
  </ResponseField>

  <ResponseField name="event_id" type="String (UUID)">
    ID of the event.
  </ResponseField>

  <ResponseField name="event_type" type="Enum (String)">
    Value: `thermostat.temperature_changed`
  </ResponseField>

  <ResponseField name="occurred_at" type="String (ISO 8601)">
    Date and time at which the event occurred.
  </ResponseField>

  <ResponseField name="temperature_celsius" type="number">
    Temperature, in °C, reported by the affected thermostat.
  </ResponseField>

  <ResponseField name="temperature_fahrenheit" type="number">
    Temperature, in °F, reported by the affected thermostat.
  </ResponseField>

  <ResponseField name="workspace_id" type="String (UUID)">
    ID of the workspace associated with the event.
  </ResponseField>
</Accordion>


# Set to Heat Mode
Source: https://docs.seam.co/api/thermostats/heat

/openapi.json post /thermostats/heat
Sets a specified [thermostat](/capability-guides/thermostats) to [heat mode](/capability-guides/thermostats/configure-current-climate-settings).



# Set to Heat-Cool (Auto) Mode
Source: https://docs.seam.co/api/thermostats/heat_cool

/openapi.json post /thermostats/heat_cool
Sets a specified [thermostat](/capability-guides/thermostats) to [heat-cool ("auto") mode](/capability-guides/thermostats/configure-current-climate-settings).



# List Thermostats
Source: https://docs.seam.co/api/thermostats/list

/openapi.json post /thermostats/list
Returns a list of all [thermostats](/capability-guides/thermostats).



# The Thermostat Object
Source: https://docs.seam.co/api/thermostats/object

Learn how the device object represents a thermostat connected to Seam, including its climate properties, capabilities, errors, warnings, and events.

## The device Object for Thermostats

Represents a [thermostat](/capability-guides/thermostats).

You can use the Seam API to perform the following management and monitoring actions for thermostats:

* Monitor current thermostat settings and readings.
* Configure [temperature thresholds](/capability-guides/thermostats/setting-and-monitoring-temperature-thresholds). If the thermostat reports a temperature outside these thresholds, Seam automatically alerts you.
* Make immediate changes to [thermostat climate settings](/capability-guides/thermostats/configure-current-climate-settings), such as the HVAC mode and fan mode.
* [Create](/capability-guides/thermostats/creating-and-managing-climate-presets) and [schedule](/capability-guides/thermostats/creating-and-managing-thermostat-schedules) climate presets, including a fallback climate preset.
* Create daily and weekly [thermostat programs](/capability-guides/thermostats/creating-and-managing-thermostat-programs).

The Seam API represents a thermostat as a `device` resource that includes both basic device properties and thermostat-specific properties.

***

<ResponseExample>
  ```json Thermostat Device theme={null}
  {
    "can_hvac_cool": true,
    "can_hvac_heat": true,
    "can_hvac_heat_cool": true,
    "can_turn_off_hvac": true,
    "capabilities_supported": [
      "thermostat"
    ],
    "connected_account_id": "a0b1c2d3-e4f5-6a7b-8c9d-0e1f2a3b4c5d",
    "created_at": "2024-10-03T22:12:15.666Z",
    "custom_metadata": {
      "id": "internalId1"
    },
    "device_id": "a1b2c3d4-e5f6-7890-1234-56789abcdef0",
    "device_type": "ecobee_thermostat",
    "display_name": "Living Room",
    "errors": [],
    "is_managed": true,
    "space_ids": [],
    "location": {
      "location_name": "2948 20th St, San Francisco, CA, 94110, US",
      "timezone": "America/Los_Angeles"
    },
    "nickname": "Living Room",
    "properties": {
      "active_climate_preset": {
        "can_delete": true,
        "can_edit": true,
        "climate_preset_key": "sleep",
        "cooling_set_point_celsius": 23.88888888888889,
        "display_name": "Sleep",
        "fan_mode_setting": "auto",
        "heating_set_point_celsius": 17.77777777777778,
        "hvac_mode_setting": "heat_cool",
        "manual_override_allowed": true
      },
      "appearance": {
        "name": "Living Room"
      },
      "available_climate_presets": [
        {
          "climate_preset_key": "sleep",
          "can_edit": true,
          "can_delete": true,
          "can_use_with_thermostat_daily_programs": false,
          "name": "Sleep",
          "display_name": "Sleep",
          "fan_mode_setting": "auto",
          "hvac_mode_setting": "heat_cool",
          "manual_override_allowed": true,
          "cooling_set_point_celsius": 23.88888888888889,
          "heating_set_point_celsius": 17.77777777777778,
          "cooling_set_point_fahrenheit": 75,
          "heating_set_point_fahrenheit": 64
        },
        {
          "climate_preset_key": "home",
          "can_edit": true,
          "can_delete": true,
          "can_use_with_thermostat_daily_programs": false,
          "name": "Home",
          "display_name": "Home",
          "fan_mode_setting": "auto",
          "hvac_mode_setting": "heat_cool",
          "manual_override_allowed": false,
          "cooling_set_point_celsius": 23.88888888888889,
          "heating_set_point_celsius": 17.77777777777778,
          "cooling_set_point_fahrenheit": 75,
          "heating_set_point_fahrenheit": 64
        },
        {
          "climate_preset_key": "work",
          "can_edit": true,
          "can_delete": true,
          "can_use_with_thermostat_daily_programs": false,
          "name": "Work",
          "display_name": "Work",
          "fan_mode_setting": "auto",
          "hvac_mode_setting": "heat_cool",
          "manual_override_allowed": false,
          "cooling_set_point_celsius": 23.88888888888889,
          "heating_set_point_celsius": 17.77777777777778,
          "cooling_set_point_fahrenheit": 75,
          "heating_set_point_fahrenheit": 64
        }
      ],
      "available_fan_mode_settings": [
        "auto",
        "on"
      ],
      "available_hvac_mode_settings": [
        "cool",
        "heat",
        "heat_cool",
        "off"
      ],
      "current_climate_setting": {
        "display_name": "Manual Setting",
        "fan_mode_setting": "auto",
        "heating_set_point_celsius": 25,
        "heating_set_point_fahrenheit": 77,
        "hvac_mode_setting": "heat",
        "manual_override_allowed": true
      },
      "ecobee_metadata": {
        "device_name": "Living Room",
        "ecobee_device_id": "a1b2c3d4-e5f6-7890-1234-56789abcdef0"
      },
      "fallback_climate_preset_key": "eco",
      "fan_mode_setting": "auto",
      "has_direct_power": true,
      "image_alt_text": "Ecobee 3 Lite Thermostat",
      "image_url": "https://connect.getseam.com/_next/image?url=https://connect.getseam.com/assets/images/devices/ecobee_3-lite_front.png&q=75&w=128",
      "is_cooling": false,
      "is_fan_running": false,
      "is_heating": false,
      "is_temporary_manual_override_active": false,
      "manufacturer": "ecobee",
      "max_cooling_set_point_celsius": 33.333333333333336,
      "max_cooling_set_point_fahrenheit": 92,
      "max_heating_set_point_celsius": 26.11111111111111,
      "max_heating_set_point_fahrenheit": 79,
      "min_cooling_set_point_celsius": 18.333333333333336,
      "min_cooling_set_point_fahrenheit": 65,
      "min_heating_cooling_delta_celsius": 2.7777777777777777,
      "min_heating_cooling_delta_fahrenheit": 5,
      "min_heating_set_point_celsius": 7.222222222222222,
      "min_heating_set_point_fahrenheit": 45,
      "model": {
        "display_name": "Thermostat",
        "manufacturer_display_name": "Ecobee"
      },
      "name": "Living Room",
      "online": true,
      "relative_humidity": 0.36,
      "temperature_celsius": 21.11111111111111,
      "temperature_fahrenheit": 70,
      "temperature_threshold": {
        "lower_limit_celsius": 16.66666666666667,
        "lower_limit_fahrenheit": 62,
        "upper_limit_celsius": 26.66666666666667,
        "upper_limit_fahrenheit": 80
      },
      "thermostat_daily_programs": [
        {
          "thermostat_daily_program_id": "1a2b3c4d-5e6f-7890-1234-56789abcdef1",
          "device_id": "a1b2c3d4-e5f6-7890-1234-56789abcdef0",
          "name": "Weekday Program",
          "periods": [
            {
              "starts_at_time": "00:00:00",
              "climate_preset_key": "sleep"
            },
            {
              "starts_at_time": "07:00:00",
              "climate_preset_key": "home"
            },
            {
              "starts_at_time": "09:00:00",
              "climate_preset_key": "work"
            },
            {
              "starts_at_time": "18:00:00",
              "climate_preset_key": "home"
            },
            {
              "starts_at_time": "22:00:00",
              "climate_preset_key": "sleep"
            }
          ],
          "workspace_id": "9f8e7d6c-5b4a-3c2d-1e0f-9876543210ab",
          "created_at": "2025-05-30T04:01:25.455Z"
        },
        {
          "thermostat_daily_program_id": "d4e5f6a7-8b9c-0d1e-2f3a-4b5c6d7e8f90",
          "device_id": "a1b2c3d4-e5f6-7890-1234-56789abcdef0",
          "name": "Weekend Program",
          "periods": [
            {
              "starts_at_time": "00:00:00",
              "climate_preset_key": "sleep"
            },
            {
              "starts_at_time": "08:00:00",
              "climate_preset_key": "home"
            },
            {
              "starts_at_time": "23:00:00",
              "climate_preset_key": "sleep"
            }
          ],
          "workspace_id": "9f8e7d6c-5b4a-3c2d-1e0f-9876543210ab",
          "created_at": "2025-05-30T04:02:19.952Z"
        }
      ],
      "thermostat_weekly_program": null
    },
    "warnings": [],
    "workspace_id": "9f8e7d6c-5b4a-3c2d-1e0f-9876543210ab"
  }
  ```
</ResponseExample>

***

## Properties

<ResponseField name="can_configure_auto_lock" type="Boolean">
  Indicates whether the lock supports configuring automatic locking.
</ResponseField>

<ResponseField name="can_hvac_cool" type="Boolean">
  Indicates whether the thermostat supports cooling.
</ResponseField>

<ResponseField name="can_hvac_heat" type="Boolean">
  Indicates whether the thermostat supports heating.
</ResponseField>

<ResponseField name="can_hvac_heat_cool" type="Boolean">
  Indicates whether the thermostat supports simultaneous heating and cooling.
</ResponseField>

<ResponseField name="can_program_offline_access_codes" type="Boolean">
  Indicates whether the device supports programming offline access codes.
</ResponseField>

<ResponseField name="can_program_online_access_codes" type="Boolean">
  Indicates whether the device supports programming online access codes.
</ResponseField>

<ResponseField name="can_program_thermostat_programs_as_different_each_day" type="Boolean">
  Indicates whether the thermostat supports different climate programs for each day of the week.
</ResponseField>

<ResponseField name="can_program_thermostat_programs_as_same_each_day" type="Boolean">
  Indicates whether the thermostat supports a single climate program applied to every day.
</ResponseField>

<ResponseField name="can_program_thermostat_programs_as_weekday_weekend" type="Boolean">
  Indicates whether the thermostat supports weekday/weekend climate programs.
</ResponseField>

<ResponseField name="can_remotely_lock" type="Boolean">
  Indicates whether the device supports remote locking.
</ResponseField>

<ResponseField name="can_remotely_unlock" type="Boolean">
  Indicates whether the device supports remote unlocking.
</ResponseField>

<ResponseField name="can_run_thermostat_programs" type="Boolean">
  Indicates whether the thermostat supports running climate programs.
</ResponseField>

<ResponseField name="can_simulate_connection" type="Boolean">
  Indicates whether the device supports simulating connection in a sandbox.
</ResponseField>

<ResponseField name="can_simulate_disconnection" type="Boolean">
  Indicates whether the device supports simulating disconnection in a sandbox.
</ResponseField>

<ResponseField name="can_simulate_hub_connection" type="Boolean">
  Indicates whether the hub supports simulating connection in a sandbox.
</ResponseField>

<ResponseField name="can_simulate_hub_disconnection" type="Boolean">
  Indicates whether the hub supports simulating disconnection in a sandbox.
</ResponseField>

<ResponseField name="can_simulate_paid_subscription" type="Boolean">
  Indicates whether the device supports simulating a paid subscription in a sandbox.
</ResponseField>

<ResponseField name="can_simulate_removal" type="Boolean">
  Indicates whether the device supports simulating removal in a sandbox.
</ResponseField>

<ResponseField name="can_turn_off_hvac" type="Boolean">
  Indicates whether the thermostat can be turned off.
</ResponseField>

<ResponseField name="can_unlock_with_code" type="Boolean">
  Indicates whether the lock supports unlocking with an access code.
</ResponseField>

<ResponseField name="capabilities_supported" type="Array">
  Collection of capabilities that the device supports when connected to Seam. Values are `access_code`, which indicates that the device can manage and utilize digital PIN codes for secure access; `lock`, which indicates that the device controls a door locking mechanism, enabling the remote opening and closing of doors and other entry points; `noise_detection`, which indicates that the device supports monitoring and responding to ambient noise levels; `thermostat`, which indicates that the device can regulate and adjust indoor temperatures; `battery`, which indicates that the device can manage battery life and health; and `phone`, which indicates that the device is a mobile device, such as a smartphone. **Important:** Superseded by [capability flags](/capability-guides/device-and-system-capabilities#capability-flags).
</ResponseField>

<ResponseField name="connected_account_id" type="String (UUID)">
  Unique identifier for the account associated with the device.
</ResponseField>

<ResponseField name="created_at" type="String (ISO 8601)">
  Date and time at which the device object was created.
</ResponseField>

<ResponseField name="custom_metadata" type="Object">
  Set of key:value pairs. Adding custom metadata to a resource, such as a [Connect Webview](/core-concepts/connect-webviews/attaching-custom-data-to-the-connect-webview), [connected account](/core-concepts/connected-accounts/adding-custom-metadata-to-a-connected-account), or [device](/core-concepts/devices/adding-custom-metadata-to-a-device), enables you to store custom information, like customer details or internal IDs from your application.
</ResponseField>

<ResponseField name="device_id" type="String (UUID)">
  ID of the device.
</ResponseField>

<ResponseField name="device_type" type="Enum (String)">
  Type of the device.
</ResponseField>

<ResponseField name="display_name" type="String">
  Display name of the device, defaults to nickname (if it is set) or `properties.appearance.name`, otherwise. Enables administrators and users to identify the device easily, especially when there are numerous devices.
</ResponseField>

<ResponseField name="errors" type="Array">
  Array of errors associated with the device. Each error object within the array contains two fields: `error_code` and `message`. `error_code` is a string that uniquely identifies the type of error, enabling quick recognition and categorization of the issue. `message` provides a more detailed description of the error, offering insights into the issue and potentially how to rectify it.
</ResponseField>

<ResponseField name="is_managed" type="Boolean">
  Indicates whether Seam manages the device. See also [Managed and Unmanaged Devices](/core-concepts/devices/managed-and-unmanaged-devices).
</ResponseField>

<ResponseField name="nickname" type="String">
  Optional nickname to describe the device, settable through Seam.
</ResponseField>

<ResponseField name="properties" type="Object">
  Properties of the device.

  <Expandable title="properties">
    <ResponseField name="accessory_keypad" type="Object">
      Accessory keypad properties and state.

      <Expandable title="properties">
        <ResponseField name="battery" type="Object">
          Keypad battery properties.

          <Expandable title="properties">
            <ResponseField name="level" type="number">
              The level.
            </ResponseField>
          </Expandable>
        </ResponseField>

        <ResponseField name="is_connected" type="Boolean">
          Indicates if an accessory keypad is connected to the device.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="appearance" type="Object">
      Appearance-related properties, as reported by the device.

      <Expandable title="properties">
        <ResponseField name="name" type="String">
          Name of the device as seen from the provider API and application, not settable through Seam.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="battery" type="Object">
      Represents the current status of the battery charge level.

      <Expandable title="properties">
        <ResponseField name="level" type="number">
          Battery charge level as a value between 0 and 1, inclusive.
        </ResponseField>

        <ResponseField name="status" type="Enum (String)">
          Represents the current status of the battery charge level. Values are `critical`, which indicates an extremely low level, suggesting imminent shutdown or an urgent need for charging; `low`, which signifies that the battery is under the preferred threshold and should be charged soon; `good`, which denotes a satisfactory charge level, adequate for normal use without the immediate need for recharging; and `full`, which represents a battery that is fully charged, providing the maximum duration of usage.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="battery_level" type="number">
      Indicates the battery level of the device as a decimal value between 0 and 1, inclusive.
    </ResponseField>

    <ResponseField name="currently_triggering_noise_threshold_ids" type="Array">
      Array of noise threshold IDs that are currently triggering.
    </ResponseField>

    <ResponseField name="has_direct_power" type="Boolean">
      Indicates whether the device has direct power.
    </ResponseField>

    <ResponseField name="image_alt_text" type="String">
      Alt text for the device image.
    </ResponseField>

    <ResponseField name="image_url" type="String">
      Image URL for the device.
    </ResponseField>

    <ResponseField name="manufacturer" type="String">
      Manufacturer of the device. When a device, such as a smart lock, is connected through a smart hub, the manufacturer of the device might be different from that of the smart hub.
    </ResponseField>

    <ResponseField name="model" type="Object">
      Device model-related properties.

      <Expandable title="properties">
        <ResponseField name="accessory_keypad_supported" type="Boolean">
          **Deprecated**. use device.properties.model.can\_connect\_accessory\_keypad

          The accessory keypad supported.
        </ResponseField>

        <ResponseField name="can_connect_accessory_keypad" type="Boolean">
          Indicates whether the device can connect a accessory keypad.
        </ResponseField>

        <ResponseField name="display_name" type="String">
          Display name of the device model.
        </ResponseField>

        <ResponseField name="has_built_in_keypad" type="Boolean">
          Indicates whether the device has a built in accessory keypad.
        </ResponseField>

        <ResponseField name="manufacturer_display_name" type="String">
          Display name that corresponds to the manufacturer-specific terminology for the device.
        </ResponseField>

        <ResponseField name="offline_access_codes_supported" type="Boolean">
          **Deprecated**. use device.can\_program\_offline\_access\_codes.

          The offline access codes supported.
        </ResponseField>

        <ResponseField name="online_access_codes_supported" type="Boolean">
          **Deprecated**. use device.can\_program\_online\_access\_codes.

          The online access codes supported.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="name" type="String">
      **Deprecated**. use device.display\_name instead

      Name of the device.
    </ResponseField>

    <ResponseField name="noise_level_decibels" type="number">
      Indicates current noise level in decibels, if the device supports noise detection.
    </ResponseField>

    <ResponseField name="offline_access_codes_enabled" type="Boolean">
      **Deprecated**. use device.can\_program\_offline\_access\_codes

      Indicates whether it is currently possible to use offline access codes for the device.
    </ResponseField>

    <ResponseField name="online" type="Boolean">
      Indicates whether the device is online.
    </ResponseField>

    <ResponseField name="online_access_codes_enabled" type="Boolean">
      **Deprecated**. use device.can\_program\_online\_access\_codes

      Indicates whether it is currently possible to use online access codes for the device.
    </ResponseField>

    <ResponseField name="serial_number" type="String">
      Serial number of the device.
    </ResponseField>

    <ResponseField name="supports_accessory_keypad" type="Boolean">
      **Deprecated**. use device.properties.model.can\_connect\_accessory\_keypad

      The supports accessory keypad.
    </ResponseField>

    <ResponseField name="supports_offline_access_codes" type="Boolean">
      **Deprecated**. use offline\_access\_codes\_enabled

      The supports offline access codes.
    </ResponseField>

    <ResponseField name="assa_abloy_credential_service_metadata" type="Object">
      ASSA ABLOY Credential Service metadata for the phone.

      <Expandable title="properties">
        <ResponseField name="endpoints" type="Array">
          Endpoints associated with the phone.

          <Expandable title="properties">
            <ResponseField name="endpoint_id" type="String">
              ID of the associated endpoint.
            </ResponseField>

            <ResponseField name="is_active" type="Boolean">
              Indicated whether the endpoint is active.
            </ResponseField>
          </Expandable>
        </ResponseField>

        <ResponseField name="has_active_endpoint" type="Boolean">
          Indicates whether the credential service has active endpoints associated with the phone.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="salto_space_credential_service_metadata" type="Object">
      Salto Space credential service metadata for the phone.

      <Expandable title="properties">
        <ResponseField name="has_active_phone" type="Boolean">
          Indicates whether the credential service has an active associated phone.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="akiles_metadata" type="Object">
      Metadata for an Akiles device.

      <Expandable title="properties">
        <ResponseField name="_member_group_id" type="String">
          Group ID to which to add users for an Akiles device.
        </ResponseField>

        <ResponseField name="gadget_id" type="String">
          Gadget ID for an Akiles device.
        </ResponseField>

        <ResponseField name="gadget_name" type="String">
          Gadget name for an Akiles device.
        </ResponseField>

        <ResponseField name="product_name" type="String">
          Product name for an Akiles device.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="aqara_metadata" type="Object">
      Metadata for an Aqara device.

      <Expandable title="properties">
        <ResponseField name="device_name" type="String">
          Device name for an Aqara device.
        </ResponseField>

        <ResponseField name="did" type="String">
          Device ID (did) for an Aqara device.
        </ResponseField>

        <ResponseField name="firmware_version" type="String">
          Firmware version for an Aqara device.
        </ResponseField>

        <ResponseField name="model" type="String">
          Model identifier for an Aqara device.
        </ResponseField>

        <ResponseField name="model_type" type="number">
          Model type for an Aqara device.
        </ResponseField>

        <ResponseField name="parent_did" type="String">
          Parent gateway device ID for an Aqara device.
        </ResponseField>

        <ResponseField name="position_id" type="String">
          Position (room) ID for an Aqara device.
        </ResponseField>

        <ResponseField name="time_zone" type="String">
          Time zone reported for an Aqara device (e.g. GMT-07:00).
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="assa_abloy_vostio_metadata" type="Object">
      Metadata for an ASSA ABLOY Vostio system.

      <Expandable title="properties">
        <ResponseField name="encoder_name" type="String">
          Encoder name for an ASSA ABLOY Vostio system.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="august_metadata" type="Object">
      Metadata for an August device.

      <Expandable title="properties">
        <ResponseField name="has_keypad" type="Boolean">
          Indicates whether an August device has a keypad.
        </ResponseField>

        <ResponseField name="house_id" type="String">
          House ID for an August device.
        </ResponseField>

        <ResponseField name="house_name" type="String">
          House name for an August device.
        </ResponseField>

        <ResponseField name="keypad_battery_level" type="String">
          Keypad battery level for an August device.
        </ResponseField>

        <ResponseField name="lock_id" type="String">
          Lock ID for an August device.
        </ResponseField>

        <ResponseField name="lock_name" type="String">
          Lock name for an August device.
        </ResponseField>

        <ResponseField name="model" type="String">
          Model for an August device.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="avigilon_alta_metadata" type="Object">
      Metadata for an Avigilon Alta system.

      <Expandable title="properties">
        <ResponseField name="entry_name" type="String">
          Entry name for an Avigilon Alta system.
        </ResponseField>

        <ResponseField name="entry_relays_total_count" type="number">
          Total count of entry relays for an Avigilon Alta system.
        </ResponseField>

        <ResponseField name="org_name" type="String">
          Organization name for an Avigilon Alta system.
        </ResponseField>

        <ResponseField name="site_id" type="number">
          Site ID for an Avigilon Alta system.
        </ResponseField>

        <ResponseField name="site_name" type="String">
          Site name for an Avigilon Alta system.
        </ResponseField>

        <ResponseField name="zone_id" type="number">
          Zone ID for an Avigilon Alta system.
        </ResponseField>

        <ResponseField name="zone_name" type="String">
          Zone name for an Avigilon Alta system.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="brivo_metadata" type="Object">
      Metadata for a Brivo device.

      <Expandable title="properties">
        <ResponseField name="activation_enabled" type="Boolean">
          Indicates whether the Brivo access point has activation (remote unlock) enabled.
        </ResponseField>

        <ResponseField name="device_name" type="String">
          Device name for a Brivo device.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="controlbyweb_metadata" type="Object">
      Metadata for a ControlByWeb device.

      <Expandable title="properties">
        <ResponseField name="device_id" type="String">
          Device ID for a ControlByWeb device.
        </ResponseField>

        <ResponseField name="device_name" type="String">
          Device name for a ControlByWeb device.
        </ResponseField>

        <ResponseField name="relay_name" type="String">
          Relay name for a ControlByWeb device.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="dormakaba_oracode_metadata" type="Object">
      Metadata for a dormakaba Oracode device.

      <Expandable title="properties">
        <ResponseField name="device_id" type="String">
          Device ID for a dormakaba Oracode device.
        </ResponseField>

        <ResponseField name="door_id" type="number">
          Door ID for a dormakaba Oracode device.
        </ResponseField>

        <ResponseField name="door_is_wireless" type="Boolean">
          Indicates whether a door is wireless for a dormakaba Oracode device.
        </ResponseField>

        <ResponseField name="door_name" type="String">
          Door name for a dormakaba Oracode device.
        </ResponseField>

        <ResponseField name="iana_timezone" type="String">
          IANA time zone for a dormakaba Oracode device.
        </ResponseField>

        <ResponseField name="predefined_time_slots" type="Array">
          Predefined time slots for a dormakaba Oracode device.

          <Expandable title="properties">
            <ResponseField name="check_in_time" type="String">
              Check in time for a time slot for a dormakaba Oracode device.
            </ResponseField>

            <ResponseField name="check_out_time" type="String">
              Checkout time for a time slot for a dormakaba Oracode device.
            </ResponseField>

            <ResponseField name="dormakaba_oracode_user_level_id" type="String (UUID)">
              ID of a user level for a dormakaba Oracode device.
            </ResponseField>

            <ResponseField name="dormakaba_oracode_user_level_prefix" type="number">
              Prefix for a user level for a dormakaba Oracode device.
            </ResponseField>

            <ResponseField name="is_24_hour" type="Boolean">
              Indicates whether a time slot for a dormakaba Oracode device is a 24-hour time slot.
            </ResponseField>

            <ResponseField name="is_biweekly_mode" type="Boolean">
              Indicates whether a time slot for a dormakaba Oracode device is in biweekly mode.
            </ResponseField>

            <ResponseField name="is_master" type="Boolean">
              Indicates whether a time slot for a dormakaba Oracode device is a master time slot.
            </ResponseField>

            <ResponseField name="is_one_shot" type="Boolean">
              Indicates whether a time slot for a dormakaba Oracode device is a one-shot time slot.
            </ResponseField>

            <ResponseField name="name" type="String">
              Name of a time slot for a dormakaba Oracode device.
            </ResponseField>

            <ResponseField name="prefix" type="number">
              Prefix for a time slot for a dormakaba Oracode device.
            </ResponseField>
          </Expandable>
        </ResponseField>

        <ResponseField name="site_id" type="number">
          **Deprecated**. Previously marked as "@DEPRECATED."

          Site ID for a dormakaba Oracode device.
        </ResponseField>

        <ResponseField name="site_name" type="String">
          Site name for a dormakaba Oracode device.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="ecobee_metadata" type="Object">
      Metadata for an ecobee device.

      <Expandable title="properties">
        <ResponseField name="device_name" type="String">
          Device name for an ecobee device.
        </ResponseField>

        <ResponseField name="ecobee_device_id" type="String">
          Device ID for an ecobee device.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="four_suites_metadata" type="Object">
      Metadata for a 4SUITES device.

      <Expandable title="properties">
        <ResponseField name="device_id" type="number">
          Device ID for a 4SUITES device.
        </ResponseField>

        <ResponseField name="device_name" type="String">
          Device name for a 4SUITES device.
        </ResponseField>

        <ResponseField name="reclose_delay_in_seconds" type="number">
          Reclose delay, in seconds, for a 4SUITES device.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="genie_metadata" type="Object">
      Metadata for a Genie device.

      <Expandable title="properties">
        <ResponseField name="device_name" type="String">
          Lock name for a Genie device.
        </ResponseField>

        <ResponseField name="door_name" type="String">
          Door name for a Genie device.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="honeywell_resideo_metadata" type="Object">
      Metadata for a Honeywell Resideo device.

      <Expandable title="properties">
        <ResponseField name="device_name" type="String">
          Device name for a Honeywell Resideo device.
        </ResponseField>

        <ResponseField name="honeywell_resideo_device_id" type="String">
          Device ID for a Honeywell Resideo device.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="igloo_metadata" type="Object">
      Metadata for an igloo device.

      <Expandable title="properties">
        <ResponseField name="bridge_id" type="String">
          Bridge ID for an igloo device.
        </ResponseField>

        <ResponseField name="device_id" type="String">
          Device ID for an igloo device.
        </ResponseField>

        <ResponseField name="model" type="String">
          Model for an igloo device.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="igloohome_metadata" type="Object">
      Metadata for an igloohome device.

      <Expandable title="properties">
        <ResponseField name="bridge_id" type="String">
          Bridge ID for an igloohome device.
        </ResponseField>

        <ResponseField name="bridge_name" type="String">
          Bridge name for an igloohome device.
        </ResponseField>

        <ResponseField name="device_id" type="String">
          Device ID for an igloohome device.
        </ResponseField>

        <ResponseField name="device_name" type="String">
          Device name for an igloohome device.
        </ResponseField>

        <ResponseField name="is_accessory_keypad_linked_to_bridge" type="Boolean">
          Indicates whether a keypad is linked to a bridge for an igloohome device.
        </ResponseField>

        <ResponseField name="keypad_id" type="String">
          Keypad ID for an igloohome device.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="keynest_metadata" type="Object">
      Metadata for a KeyNest device.

      <Expandable title="properties">
        <ResponseField name="address" type="String">
          Address for a KeyNest device.
        </ResponseField>

        <ResponseField name="current_or_last_store_id" type="number">
          Current or last store ID for a KeyNest device.
        </ResponseField>

        <ResponseField name="current_status" type="String">
          Current status for a KeyNest device.
        </ResponseField>

        <ResponseField name="current_user_company" type="String">
          Current user company for a KeyNest device.
        </ResponseField>

        <ResponseField name="current_user_email" type="String">
          Current user email for a KeyNest device.
        </ResponseField>

        <ResponseField name="current_user_name" type="String">
          Current user name for a KeyNest device.
        </ResponseField>

        <ResponseField name="current_user_phone_number" type="String">
          Current user phone number for a KeyNest device.
        </ResponseField>

        <ResponseField name="default_office_id" type="number">
          Default office ID for a KeyNest device.
        </ResponseField>

        <ResponseField name="device_name" type="String">
          Device name for a KeyNest device.
        </ResponseField>

        <ResponseField name="fob_id" type="number">
          Fob ID for a KeyNest device.
        </ResponseField>

        <ResponseField name="handover_method" type="String">
          Handover method for a KeyNest device.
        </ResponseField>

        <ResponseField name="has_photo" type="Boolean">
          Whether the KeyNest device has a photo.
        </ResponseField>

        <ResponseField name="is_quadient_locker" type="Boolean">
          Whether the key is in a locker that does not support the access codes API.
        </ResponseField>

        <ResponseField name="key_id" type="String">
          Key ID for a KeyNest device.
        </ResponseField>

        <ResponseField name="key_notes" type="String">
          Key notes for a KeyNest device.
        </ResponseField>

        <ResponseField name="keynest_app_user" type="String">
          KeyNest app user for a KeyNest device.
        </ResponseField>

        <ResponseField name="last_movement" type="String">
          Last movement timestamp for a KeyNest device.
        </ResponseField>

        <ResponseField name="property_id" type="String">
          Property ID for a KeyNest device.
        </ResponseField>

        <ResponseField name="property_postcode" type="String">
          Property postcode for a KeyNest device.
        </ResponseField>

        <ResponseField name="status_type" type="String">
          Status type for a KeyNest device.
        </ResponseField>

        <ResponseField name="subscription_plan" type="String">
          Subscription plan for a KeyNest device.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="kisi_metadata" type="Object">
      Metadata for a Kisi device.

      <Expandable title="properties">
        <ResponseField name="description" type="String">
          Description for a Kisi device.
        </ResponseField>

        <ResponseField name="lock_id" type="number">
          Lock ID for a Kisi device.
        </ResponseField>

        <ResponseField name="lock_name" type="String">
          Lock name for a Kisi device.
        </ResponseField>

        <ResponseField name="place_name" type="String">
          Place name for a Kisi device.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="korelock_metadata" type="Object">
      Metadata for a Korelock device.

      <Expandable title="properties">
        <ResponseField name="device_id" type="String">
          Device ID for a Korelock device.
        </ResponseField>

        <ResponseField name="device_name" type="String">
          Device name for a Korelock device.
        </ResponseField>

        <ResponseField name="firmware_version" type="String">
          Firmware version for a Korelock device.
        </ResponseField>

        <ResponseField name="location_id" type="String">
          Location ID for a Korelock device. Required for timebound access codes.
        </ResponseField>

        <ResponseField name="model_code" type="String">
          Model code for a Korelock device.
        </ResponseField>

        <ResponseField name="serial_number" type="String">
          Serial number for a Korelock device.
        </ResponseField>

        <ResponseField name="wifi_signal_strength" type="number">
          WiFi signal strength (0-1) for a Korelock device.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="kwikset_metadata" type="Object">
      Metadata for a Kwikset device.

      <Expandable title="properties">
        <ResponseField name="device_id" type="String">
          Device ID for a Kwikset device.
        </ResponseField>

        <ResponseField name="device_name" type="String">
          Device name for a Kwikset device.
        </ResponseField>

        <ResponseField name="model_number" type="String">
          Model number for a Kwikset device.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="lockly_metadata" type="Object">
      Metadata for a Lockly device.

      <Expandable title="properties">
        <ResponseField name="device_id" type="String">
          Device ID for a Lockly device.
        </ResponseField>

        <ResponseField name="device_name" type="String">
          Device name for a Lockly device.
        </ResponseField>

        <ResponseField name="model" type="String">
          Model for a Lockly device.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="minut_metadata" type="Object">
      Metadata for a Minut device.

      <Expandable title="properties">
        <ResponseField name="device_id" type="String">
          Device ID for a Minut device.
        </ResponseField>

        <ResponseField name="device_name" type="String">
          Device name for a Minut device.
        </ResponseField>

        <ResponseField name="latest_sensor_values" type="Object">
          Latest sensor values for a Minut device.

          <Expandable title="properties">
            <ResponseField name="accelerometer_z" type="Object">
              Latest accelerometer Z-axis reading for a Minut device.

              <Expandable title="properties">
                <ResponseField name="time" type="String">
                  Time of latest accelerometer Z-axis reading for a Minut device.
                </ResponseField>

                <ResponseField name="value" type="number">
                  Value of latest accelerometer Z-axis reading for a Minut device.
                </ResponseField>
              </Expandable>
            </ResponseField>

            <ResponseField name="humidity" type="Object">
              Latest humidity reading for a Minut device.

              <Expandable title="properties">
                <ResponseField name="time" type="String">
                  Time of latest humidity reading for a Minut device.
                </ResponseField>

                <ResponseField name="value" type="number">
                  Value of latest humidity reading for a Minut device.
                </ResponseField>
              </Expandable>
            </ResponseField>

            <ResponseField name="pressure" type="Object">
              Latest pressure reading for a Minut device.

              <Expandable title="properties">
                <ResponseField name="time" type="String">
                  Time of latest pressure reading for a Minut device.
                </ResponseField>

                <ResponseField name="value" type="number">
                  Value of latest pressure reading for a Minut device.
                </ResponseField>
              </Expandable>
            </ResponseField>

            <ResponseField name="sound" type="Object">
              Latest sound reading for a Minut device.

              <Expandable title="properties">
                <ResponseField name="time" type="String">
                  Time of latest sound reading for a Minut device.
                </ResponseField>

                <ResponseField name="value" type="number">
                  Value of latest sound reading for a Minut device.
                </ResponseField>
              </Expandable>
            </ResponseField>

            <ResponseField name="temperature" type="Object">
              Latest temperature reading for a Minut device.

              <Expandable title="properties">
                <ResponseField name="time" type="String">
                  Time of latest temperature reading for a Minut device.
                </ResponseField>

                <ResponseField name="value" type="number">
                  Value of latest temperature reading for a Minut device.
                </ResponseField>
              </Expandable>
            </ResponseField>
          </Expandable>
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="nest_metadata" type="Object">
      Metadata for a Google Nest device.

      <Expandable title="properties">
        <ResponseField name="device_custom_name" type="String">
          Custom device name for a Google Nest device. The device owner sets this value.
        </ResponseField>

        <ResponseField name="device_name" type="String">
          Device name for a Google Nest device. Google sets this value.
        </ResponseField>

        <ResponseField name="display_name" type="String">
          Display name for a Google Nest device.
        </ResponseField>

        <ResponseField name="nest_device_id" type="String">
          Device ID for a Google Nest device.
        </ResponseField>

        <ResponseField name="nest_structure_id" type="String">
          ID of the Google Nest structure containing the device.
        </ResponseField>

        <ResponseField name="structure_name" type="String">
          Name of the Google Nest structure containing the device. The device owner sets this value.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="noiseaware_metadata" type="Object">
      Metadata for a NoiseAware device.

      <Expandable title="properties">
        <ResponseField name="device_id" type="String">
          Device ID for a NoiseAware device.
        </ResponseField>

        <ResponseField name="device_model" type="Enum (String)">
          Device model for a NoiseAware device.
        </ResponseField>

        <ResponseField name="device_name" type="String">
          Device name for a NoiseAware device.
        </ResponseField>

        <ResponseField name="noise_level_decibel" type="number">
          Noise level, in decibels, for a NoiseAware device.
        </ResponseField>

        <ResponseField name="noise_level_nrs" type="number">
          Noise level, expressed as a Noise Risk Score (NRS), for a NoiseAware device.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="nuki_metadata" type="Object">
      Metadata for a Nuki device.

      <Expandable title="properties">
        <ResponseField name="device_id" type="String">
          Device ID for a Nuki device.
        </ResponseField>

        <ResponseField name="device_name" type="String">
          Device name for a Nuki device.
        </ResponseField>

        <ResponseField name="keypad_2_paired" type="Boolean">
          Indicates whether keypad 2 is paired for a Nuki device.
        </ResponseField>

        <ResponseField name="keypad_battery_critical" type="Boolean">
          Indicates whether the keypad battery is in a critical state for a Nuki device.
        </ResponseField>

        <ResponseField name="keypad_paired" type="Boolean">
          Indicates whether the keypad is paired for a Nuki device.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="omnitec_metadata" type="Object">
      Metadata for an Omnitec device.

      <Expandable title="properties">
        <ResponseField name="has_gateway" type="Boolean">
          Whether the Omnitec lock has a connected gateway for remote operations.
        </ResponseField>

        <ResponseField name="lock_alias" type="String">
          Operator-assigned alias for an Omnitec device.
        </ResponseField>

        <ResponseField name="lock_id" type="number">
          Lock ID for an Omnitec device.
        </ResponseField>

        <ResponseField name="lock_mac" type="String">
          Bluetooth MAC address for an Omnitec device.
        </ResponseField>

        <ResponseField name="lock_name" type="String">
          Lock name for an Omnitec device.
        </ResponseField>

        <ResponseField name="time_zone" type="String">
          IANA time zone for the Omnitec device, used to schedule time-bound access codes at the correct local time (accounting for DST).
        </ResponseField>

        <ResponseField name="timezone_raw_offset_ms" type="number">
          Static UTC offset of the Omnitec lock in milliseconds. Does not account for DST.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="ring_metadata" type="Object">
      Metadata for a Ring device.

      <Expandable title="properties">
        <ResponseField name="device_id" type="String">
          Device ID for a Ring device.
        </ResponseField>

        <ResponseField name="device_name" type="String">
          Device name for a Ring device.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="salto_ks_metadata" type="Object">
      Metadata for a Salto KS device.

      <Expandable title="properties">
        <ResponseField name="battery_level" type="String">
          Battery level for a Salto KS device.
        </ResponseField>

        <ResponseField name="customer_reference" type="String">
          Customer reference for a Salto KS device.
        </ResponseField>

        <ResponseField name="has_custom_pin_subscription" type="Boolean">
          Indicates whether the site has a Salto KS subscription that supports custom PINs.
        </ResponseField>

        <ResponseField name="lock_id" type="String">
          Lock ID for a Salto KS device.
        </ResponseField>

        <ResponseField name="lock_type" type="String">
          Lock type for a Salto KS device.
        </ResponseField>

        <ResponseField name="locked_state" type="String">
          Locked state for a Salto KS device.
        </ResponseField>

        <ResponseField name="model" type="String">
          Model for a Salto KS device.
        </ResponseField>

        <ResponseField name="site_id" type="String">
          Site ID for the Salto KS site to which the device belongs.
        </ResponseField>

        <ResponseField name="site_name" type="String">
          Site name for the Salto KS site to which the device belongs.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="salto_metadata" type="Object">
      **Deprecated**. Use `salto_ks_metadata` instead.

      Metada for a Salto device.

      <Expandable title="properties">
        <ResponseField name="battery_level" type="String">
          Battery level for a Salto device.
        </ResponseField>

        <ResponseField name="customer_reference" type="String">
          Customer reference for a Salto device.
        </ResponseField>

        <ResponseField name="lock_id" type="String">
          Lock ID for a Salto device.
        </ResponseField>

        <ResponseField name="lock_type" type="String">
          Lock type for a Salto device.
        </ResponseField>

        <ResponseField name="locked_state" type="String">
          Locked state for a Salto device.
        </ResponseField>

        <ResponseField name="model" type="String">
          Model for a Salto device.
        </ResponseField>

        <ResponseField name="site_id" type="String">
          Site ID for the Salto KS site to which the device belongs.
        </ResponseField>

        <ResponseField name="site_name" type="String">
          Site name for the Salto KS site to which the device belongs.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="schlage_metadata" type="Object">
      Metadata for a Schlage device.

      <Expandable title="properties">
        <ResponseField name="device_id" type="String">
          Device ID for a Schlage device.
        </ResponseField>

        <ResponseField name="device_name" type="String">
          Device name for a Schlage device.
        </ResponseField>

        <ResponseField name="model" type="String">
          Model for a Schlage device.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="seam_bridge_metadata" type="Object">
      Metadata for Seam Bridge.

      <Expandable title="properties">
        <ResponseField name="device_num" type="number">
          Device number for Seam Bridge.
        </ResponseField>

        <ResponseField name="name" type="String">
          Name for Seam Bridge.
        </ResponseField>

        <ResponseField name="unlock_method" type="Enum (String)">
          Unlock method for Seam Bridge.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="sensi_metadata" type="Object">
      Metadata for a Sensi device.

      <Expandable title="properties">
        <ResponseField name="device_id" type="String">
          Device ID for a Sensi device.
        </ResponseField>

        <ResponseField name="device_name" type="String">
          Device name for a Sensi device.
        </ResponseField>

        <ResponseField name="dual_setpoints_not_supported" type="Boolean">
          Set to true when the device does not support the /dual-setpoints API endpoint.
        </ResponseField>

        <ResponseField name="enforced_setpoint_range_celsius" type="Array">
          Enforced setpoint range in Celsius for a Sensi device, derived from an OutOfRange API error.
        </ResponseField>

        <ResponseField name="product_type" type="String">
          Product type for a Sensi device.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="smartthings_metadata" type="Object">
      Metadata for a SmartThings device.

      <Expandable title="properties">
        <ResponseField name="device_id" type="String">
          Device ID for a SmartThings device.
        </ResponseField>

        <ResponseField name="device_name" type="String">
          Device name for a SmartThings device.
        </ResponseField>

        <ResponseField name="location_id" type="String">
          Location ID for a SmartThings device.
        </ResponseField>

        <ResponseField name="model" type="String">
          Model for a SmartThings device.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="tado_metadata" type="Object">
      Metadata for a tado° device.

      <Expandable title="properties">
        <ResponseField name="device_type" type="String">
          Device type for a tado° device.
        </ResponseField>

        <ResponseField name="serial_no" type="String">
          Serial number for a tado° device.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="tedee_metadata" type="Object">
      Metadata for a Tedee device.

      <Expandable title="properties">
        <ResponseField name="bridge_id" type="number">
          Bridge ID for a Tedee device.
        </ResponseField>

        <ResponseField name="bridge_name" type="String">
          Bridge name for a Tedee device.
        </ResponseField>

        <ResponseField name="device_id" type="number">
          Device ID for a Tedee device.
        </ResponseField>

        <ResponseField name="device_model" type="String">
          Device model for a Tedee device.
        </ResponseField>

        <ResponseField name="device_name" type="String">
          Device name for a Tedee device.
        </ResponseField>

        <ResponseField name="keypad_id" type="number">
          Keypad ID for a Tedee device.
        </ResponseField>

        <ResponseField name="serial_number" type="String">
          Serial number for a Tedee device.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="ttlock_metadata" type="Object">
      Metadata for a TTLock device.

      <Expandable title="properties">
        <ResponseField name="feature_value" type="String">
          Feature value for a TTLock device.
        </ResponseField>

        <ResponseField name="features" type="Object">
          Features for a TTLock device.

          <Expandable title="properties">
            <ResponseField name="auto_lock_time_config" type="Boolean">
              Indicates whether a TTLock device supports auto-lock time configuration.
            </ResponseField>

            <ResponseField name="incomplete_keyboard_passcode" type="Boolean">
              Indicates whether a TTLock device supports an incomplete keyboard passcode.
            </ResponseField>

            <ResponseField name="lock_command" type="Boolean">
              Indicates whether a TTLock device supports the lock command.
            </ResponseField>

            <ResponseField name="passcode" type="Boolean">
              Indicates whether a TTLock device supports a passcode.
            </ResponseField>

            <ResponseField name="passcode_management" type="Boolean">
              Indicates whether a TTLock device supports passcode management.
            </ResponseField>

            <ResponseField name="unlock_via_gateway" type="Boolean">
              Indicates whether a TTLock device supports unlock via gateway.
            </ResponseField>

            <ResponseField name="wifi" type="Boolean">
              Indicates whether a TTLock device supports Wi-Fi.
            </ResponseField>
          </Expandable>
        </ResponseField>

        <ResponseField name="has_gateway" type="Boolean">
          Indicates whether a TTLock device has a gateway.
        </ResponseField>

        <ResponseField name="lock_alias" type="String">
          Lock alias for a TTLock device.
        </ResponseField>

        <ResponseField name="lock_id" type="number">
          Lock ID for a TTLock device.
        </ResponseField>

        <ResponseField name="timezone_raw_offset_ms" type="number">
          Lock-side timezone offset in milliseconds east of UTC, as configured in the TTLock app. Source of truth for the lock's wall-clock interpretation of access code start/end times — a misconfigured value here is the typical cause of customer "codes offset by N hours" reports. Diagnostic only; Seam does not convert times based on this value.
        </ResponseField>

        <ResponseField name="wireless_keypads" type="Array">
          Wireless keypads for a TTLock device.

          <Expandable title="properties">
            <ResponseField name="wireless_keypad_id" type="number">
              ID for a wireless keypad for a TTLock device.
            </ResponseField>

            <ResponseField name="wireless_keypad_name" type="String">
              Name for a wireless keypad for a TTLock device.
            </ResponseField>
          </Expandable>
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="two_n_metadata" type="Object">
      Metadata for a 2N device.

      <Expandable title="properties">
        <ResponseField name="device_id" type="number">
          Device ID for a 2N device.
        </ResponseField>

        <ResponseField name="device_name" type="String">
          Device name for a 2N device.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="ultraloq_metadata" type="Object">
      Metadata for an Ultraloq device.

      <Expandable title="properties">
        <ResponseField name="device_id" type="String">
          Device ID for an Ultraloq device.
        </ResponseField>

        <ResponseField name="device_name" type="String">
          Device name for an Ultraloq device.
        </ResponseField>

        <ResponseField name="device_type" type="String">
          Device type for an Ultraloq device.
        </ResponseField>

        <ResponseField name="time_zone" type="String">
          IANA timezone for the Ultraloq device.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="visionline_metadata" type="Object">
      Metadata for an ASSA ABLOY Visionline system.

      <Expandable title="properties">
        <ResponseField name="encoder_id" type="String">
          Encoder ID for an ASSA ABLOY Visionline system.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="wyze_metadata" type="Object">
      Metadata for a Wyze device.

      <Expandable title="properties">
        <ResponseField name="device_id" type="String">
          Device ID for a Wyze device.
        </ResponseField>

        <ResponseField name="device_info_model" type="String">
          Device information model for a Wyze device.
        </ResponseField>

        <ResponseField name="device_name" type="String">
          Device name for a Wyze device.
        </ResponseField>

        <ResponseField name="keypad_uuid" type="String">
          Keypad UUID for a Wyze device.
        </ResponseField>

        <ResponseField name="locker_status_hardlock" type="number">
          Locker status (hardlock) for a Wyze device.
        </ResponseField>

        <ResponseField name="product_model" type="String">
          Product model for a Wyze device.
        </ResponseField>

        <ResponseField name="product_name" type="String">
          Product name for a Wyze device.
        </ResponseField>

        <ResponseField name="product_type" type="String">
          Product type for a Wyze device.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="auto_lock_delay_seconds" type="number">
      The delay in seconds before the lock automatically locks after being unlocked.
    </ResponseField>

    <ResponseField name="auto_lock_enabled" type="Boolean">
      Indicates whether automatic locking is enabled.
    </ResponseField>

    <ResponseField name="backup_access_code_pool_enabled" type="Boolean">
      Indicates whether the [backup access code pool](/low-level-apis/smart-locks/access-codes/backup-access-codes) is currently enabled for the device. To disable it, set this to `false` using [/devices/update](/api/devices/update).
    </ResponseField>

    <ResponseField name="code_constraints" type="Array">
      Constraints on access codes for the device. Seam represents each constraint as an object with a `constraint_type` property. Depending on the constraint type, there may also be additional properties. Note that some constraints are manufacturer- or device-specific.

      <Expandable title="properties">
        <ResponseField name="constraint_type" type="Enum (String)">
          The constraint type.
        </ResponseField>

        <ResponseField name="max_length" type="number">
          Maximum name length constraint for access codes.
        </ResponseField>

        <ResponseField name="min_length" type="number">
          Minimum name length constraint for access codes.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="door_open" type="Boolean">
      Indicates whether the door is open.
    </ResponseField>

    <ResponseField name="has_native_entry_events" type="Boolean">
      Indicates whether the device supports native entry events.
    </ResponseField>

    <ResponseField name="keypad_battery" type="Object">
      Keypad battery status.

      <Expandable title="properties">
        <ResponseField name="level" type="number">
          Keypad battery charge level.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="locked" type="Boolean">
      Indicates whether the lock is locked.
    </ResponseField>

    <ResponseField name="max_active_codes_supported" type="number">
      Maximum number of active access codes that the device supports.
    </ResponseField>

    <ResponseField name="offline_time_frame_options" type="Array">
      Time frames that may be requested when creating an offline access code, expressed as a list of options. The caller picks one option (by matching the requested duration when the options' duration ranges do not overlap, or by `display_name` when they do) and satisfies that one option's rules. When `undefined`, any time frame works.

      <Expandable title="properties">
        <ResponseField name="display_name" type="String">
          Label for this option. For a single-option device, the product name (for example, `algoPIN` or `SmartPIN`); for a multi-option device, a label that distinguishes it (for example, `Hourly` or `Fixed start times`).
        </ResponseField>

        <ResponseField name="end_date_recurrence_rule" type="String">
          iCalendar recurrence rule (RRULE) that the end date must fall on. Constrains which calendar dates are selectable, independent of the time-of-day rules.
        </ResponseField>

        <ResponseField name="matching_start_end_time" type="Boolean">
          When `true`, the start and end must fall at the same time of day (the caller picks which). Mutually exclusive with `time_pairs`.
        </ResponseField>

        <ResponseField name="max_duration" type="String">
          Maximum duration this option covers, as an ISO 8601 duration (for example, `PT672H` or `P367D`). Omitted when there is no maximum.
        </ResponseField>

        <ResponseField name="min_duration" type="String">
          Minimum duration this option covers, as an ISO 8601 duration (for example, `PT1H` or `P29D`). Omitted when there is no minimum.
        </ResponseField>

        <ResponseField name="start_date_recurrence_rule" type="String">
          iCalendar recurrence rule (RRULE) that the start date must fall on (for example, `FREQ=MONTHLY;BYDAY=1MO,3MO`). Constrains which calendar dates are selectable, independent of the time-of-day rules.
        </ResponseField>

        <ResponseField name="time_pairs" type="Array">
          Fixed start/end time pairings the caller chooses from. Mutually exclusive with `matching_start_end_time`.

          <Expandable title="properties">
            <ResponseField name="display_name" type="String">
              Label for the start/end time pairing.
            </ResponseField>

            <ResponseField name="end_time" type="String">
              End time of day as a 24-hour `HH:MM` value, interpreted in the option's `time_zone`. An `end_time` earlier on the clock than `start_time` means the end falls on a later date.
            </ResponseField>

            <ResponseField name="start_time" type="String">
              Start time of day as a 24-hour `HH:MM` value, interpreted in the option's `time_zone`.
            </ResponseField>
          </Expandable>
        </ResponseField>

        <ResponseField name="time_zone" type="String">
          IANA time zone for interpreting `time_pairs` and the date recurrence rules. Present only when the option fixes times or dates.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="online_time_frame_options" type="Array">
      Time frames that may be requested when creating an online access code, expressed as a list of options. The caller picks one option (by matching the requested duration when the options' duration ranges do not overlap, or by `display_name` when they do) and satisfies that one option's rules. When `undefined`, any time frame works.

      <Expandable title="properties">
        <ResponseField name="display_name" type="String">
          Label for this option. For a single-option device, the product name (for example, `algoPIN` or `SmartPIN`); for a multi-option device, a label that distinguishes it (for example, `Hourly` or `Fixed start times`).
        </ResponseField>

        <ResponseField name="end_date_recurrence_rule" type="String">
          iCalendar recurrence rule (RRULE) that the end date must fall on. Constrains which calendar dates are selectable, independent of the time-of-day rules.
        </ResponseField>

        <ResponseField name="matching_start_end_time" type="Boolean">
          When `true`, the start and end must fall at the same time of day (the caller picks which). Mutually exclusive with `time_pairs`.
        </ResponseField>

        <ResponseField name="max_duration" type="String">
          Maximum duration this option covers, as an ISO 8601 duration (for example, `PT672H` or `P367D`). Omitted when there is no maximum.
        </ResponseField>

        <ResponseField name="min_duration" type="String">
          Minimum duration this option covers, as an ISO 8601 duration (for example, `PT1H` or `P29D`). Omitted when there is no minimum.
        </ResponseField>

        <ResponseField name="start_date_recurrence_rule" type="String">
          iCalendar recurrence rule (RRULE) that the start date must fall on (for example, `FREQ=MONTHLY;BYDAY=1MO,3MO`). Constrains which calendar dates are selectable, independent of the time-of-day rules.
        </ResponseField>

        <ResponseField name="time_pairs" type="Array">
          Fixed start/end time pairings the caller chooses from. Mutually exclusive with `matching_start_end_time`.

          <Expandable title="properties">
            <ResponseField name="display_name" type="String">
              Label for the start/end time pairing.
            </ResponseField>

            <ResponseField name="end_time" type="String">
              End time of day as a 24-hour `HH:MM` value, interpreted in the option's `time_zone`. An `end_time` earlier on the clock than `start_time` means the end falls on a later date.
            </ResponseField>

            <ResponseField name="start_time" type="String">
              Start time of day as a 24-hour `HH:MM` value, interpreted in the option's `time_zone`.
            </ResponseField>
          </Expandable>
        </ResponseField>

        <ResponseField name="time_zone" type="String">
          IANA time zone for interpreting `time_pairs` and the date recurrence rules. Present only when the option fixes times or dates.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="supported_code_lengths" type="Array">
      Supported code lengths for access codes.
    </ResponseField>

    <ResponseField name="supports_backup_access_code_pool" type="Boolean">
      Indicates whether the device supports a [backup access code pool](/low-level-apis/smart-locks/access-codes/backup-access-codes).
    </ResponseField>

    <ResponseField name="active_thermostat_schedule" type="Object">
      **Deprecated**. Use `active_thermostat_schedule_id` with `/thermostats/schedules/get` instead.

      Active [thermostat schedule](/capability-guides/thermostats/creating-and-managing-thermostat-schedules).

      <Expandable title="properties">
        <ResponseField name="climate_preset_key" type="String">
          Key of the [climate preset](/capability-guides/thermostats/creating-and-managing-climate-presets) to use for the [thermostat schedule](/capability-guides/thermostats/creating-and-managing-thermostat-schedules).
        </ResponseField>

        <ResponseField name="created_at" type="String (ISO 8601)">
          Date and time at which the [thermostat schedule](/capability-guides/thermostats/creating-and-managing-thermostat-schedules) was created.
        </ResponseField>

        <ResponseField name="device_id" type="String (UUID)">
          ID of the desired [thermostat](/capability-guides/thermostats) device.
        </ResponseField>

        <ResponseField name="ends_at" type="String (ISO 8601)">
          Date and time at which the [thermostat schedule](/capability-guides/thermostats/creating-and-managing-thermostat-schedules) ends, in [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) format.
        </ResponseField>

        <ResponseField name="errors" type="Array">
          Errors associated with the [thermostat schedule](/capability-guides/thermostats/creating-and-managing-thermostat-schedules).

          <Expandable title="properties">
            <ResponseField name="created_at" type="String (ISO 8601)">
              Date and time at which Seam created the error.
            </ResponseField>

            <ResponseField name="error_code" type="String">
              Unique identifier of the type of error. Enables quick recognition and categorization of the issue.
            </ResponseField>

            <ResponseField name="message" type="String">
              Detailed description of the error. Provides insights into the issue and potentially how to rectify it.
            </ResponseField>
          </Expandable>
        </ResponseField>

        <ResponseField name="is_override_allowed" type="Boolean">
          Indicates whether a person at the thermostat can change the thermostat's settings after the [thermostat schedule](/capability-guides/thermostats/creating-and-managing-thermostat-schedules) starts.
        </ResponseField>

        <ResponseField name="max_override_period_minutes" type="number">
          Number of minutes for which a person at the thermostat can change the thermostat's settings after the activation of the scheduled [climate preset](/capability-guides/thermostats/creating-and-managing-climate-presets). See also [Specifying Manual Override Permissions](/capability-guides/thermostats/creating-and-managing-thermostat-schedules#specifying-manual-override-permissions).
        </ResponseField>

        <ResponseField name="name" type="String">
          User-friendly name to identify the [thermostat schedule](/capability-guides/thermostats/creating-and-managing-thermostat-schedules).
        </ResponseField>

        <ResponseField name="starts_at" type="String (ISO 8601)">
          Date and time at which the [thermostat schedule](/capability-guides/thermostats/creating-and-managing-thermostat-schedules) starts, in [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) format.
        </ResponseField>

        <ResponseField name="thermostat_schedule_id" type="String (UUID)">
          ID of the [thermostat schedule](/capability-guides/thermostats/creating-and-managing-thermostat-schedules).
        </ResponseField>

        <ResponseField name="workspace_id" type="String (UUID)">
          ID of the workspace that contains the thermostat schedule.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="active_thermostat_schedule_id" type="String (UUID)">
      ID of the active [thermostat schedule](/capability-guides/thermostats/creating-and-managing-thermostat-schedules).
    </ResponseField>

    <ResponseField name="available_climate_preset_modes" type="Array">
      Climate preset modes that the thermostat supports, such as "home", "away", "wake", "sleep", "occupied", and "unoccupied".
    </ResponseField>

    <ResponseField name="available_climate_presets" type="Array">
      Available [climate presets](/capability-guides/thermostats/creating-and-managing-climate-presets) for the thermostat.

      <Expandable title="properties">
        <ResponseField name="can_delete" type="Boolean">
          Indicates whether the [climate preset](/capability-guides/thermostats/creating-and-managing-climate-presets) key can be deleted.
        </ResponseField>

        <ResponseField name="can_edit" type="Boolean">
          Indicates whether the [climate preset](/capability-guides/thermostats/creating-and-managing-climate-presets) key can be edited.
        </ResponseField>

        <ResponseField name="can_use_with_thermostat_daily_programs" type="Boolean">
          Indicates whether the [climate preset](/capability-guides/thermostats/creating-and-managing-climate-presets) key can be programmed in a thermostat daily program.
        </ResponseField>

        <ResponseField name="climate_preset_key" type="String">
          Unique key to identify the [climate preset](/capability-guides/thermostats/creating-and-managing-climate-presets).
        </ResponseField>

        <ResponseField name="climate_preset_mode" type="Enum (String)">
          The climate preset mode for the thermostat, based on the available climate preset modes reported by the device.
        </ResponseField>

        <ResponseField name="cooling_set_point_celsius" type="number">
          Temperature to which the thermostat should cool (in °C). See also [Set Points](/capability-guides/thermostats/understanding-thermostat-concepts/set-points).
        </ResponseField>

        <ResponseField name="cooling_set_point_fahrenheit" type="number">
          Temperature to which the thermostat should cool (in °F). See also [Set Points](/capability-guides/thermostats/understanding-thermostat-concepts/set-points).
        </ResponseField>

        <ResponseField name="display_name" type="String">
          Display name for the [climate preset](/capability-guides/thermostats/creating-and-managing-climate-presets).
        </ResponseField>

        <ResponseField name="ecobee_metadata" type="Object">
          Metadata specific to the Ecobee climate, if applicable.

          <Expandable title="properties">
            <ResponseField name="climate_ref" type="String">
              Reference to the Ecobee climate, if applicable.
            </ResponseField>

            <ResponseField name="is_optimized" type="Boolean">
              Indicates if the climate preset is optimized by Ecobee.
            </ResponseField>

            <ResponseField name="owner" type="Enum (String)">
              Indicates whether the climate preset is owned by the user or the system.
            </ResponseField>
          </Expandable>
        </ResponseField>

        <ResponseField name="fan_mode_setting" type="Enum (String)">
          Desired [fan mode setting](/capability-guides/thermostats/configure-current-climate-settings#fan-mode-settings), such as `on`, `auto`, or `circulate`.
        </ResponseField>

        <ResponseField name="heating_set_point_celsius" type="number">
          Temperature to which the thermostat should heat (in °C). See also [Set Points](/capability-guides/thermostats/understanding-thermostat-concepts/set-points).
        </ResponseField>

        <ResponseField name="heating_set_point_fahrenheit" type="number">
          Temperature to which the thermostat should heat (in °F). See also [Set Points](/capability-guides/thermostats/understanding-thermostat-concepts/set-points).
        </ResponseField>

        <ResponseField name="hvac_mode_setting" type="Enum (String)">
          Desired [HVAC mode](/capability-guides/thermostats/understanding-thermostat-concepts/hvac-mode) setting, such as `heat`, `cool`, `heat_cool`, or `off`.
        </ResponseField>

        <ResponseField name="manual_override_allowed" type="Boolean">
          **Deprecated**. Use 'thermostat\_schedule.is\_override\_allowed'

          Indicates whether a person at the thermostat can change the thermostat's settings. See [Specifying Manual Override Permissions](/capability-guides/thermostats/creating-and-managing-thermostat-schedules#specifying-manual-override-permissions).
        </ResponseField>

        <ResponseField name="name" type="String">
          User-friendly name to identify the [climate preset](/capability-guides/thermostats/creating-and-managing-climate-presets).
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="available_fan_mode_settings" type="Array">
      Fan mode settings that the thermostat supports.
    </ResponseField>

    <ResponseField name="available_hvac_mode_settings" type="Array">
      HVAC mode settings that the thermostat supports.
    </ResponseField>

    <ResponseField name="current_climate_setting" type="Object">
      Current climate setting.

      <Expandable title="properties">
        <ResponseField name="can_delete" type="Boolean">
          Indicates whether the [climate preset](/capability-guides/thermostats/creating-and-managing-climate-presets) key can be deleted.
        </ResponseField>

        <ResponseField name="can_edit" type="Boolean">
          Indicates whether the [climate preset](/capability-guides/thermostats/creating-and-managing-climate-presets) key can be edited.
        </ResponseField>

        <ResponseField name="can_use_with_thermostat_daily_programs" type="Boolean">
          Indicates whether the [climate preset](/capability-guides/thermostats/creating-and-managing-climate-presets) key can be programmed in a thermostat daily program.
        </ResponseField>

        <ResponseField name="climate_preset_key" type="String">
          Unique key to identify the [climate preset](/capability-guides/thermostats/creating-and-managing-climate-presets).
        </ResponseField>

        <ResponseField name="climate_preset_mode" type="Enum (String)">
          The climate preset mode for the thermostat, based on the available climate preset modes reported by the device.
        </ResponseField>

        <ResponseField name="cooling_set_point_celsius" type="number">
          Temperature to which the thermostat should cool (in °C). See also [Set Points](/capability-guides/thermostats/understanding-thermostat-concepts/set-points).
        </ResponseField>

        <ResponseField name="cooling_set_point_fahrenheit" type="number">
          Temperature to which the thermostat should cool (in °F). See also [Set Points](/capability-guides/thermostats/understanding-thermostat-concepts/set-points).
        </ResponseField>

        <ResponseField name="display_name" type="String">
          Display name for the [climate preset](/capability-guides/thermostats/creating-and-managing-climate-presets).
        </ResponseField>

        <ResponseField name="ecobee_metadata" type="Object">
          Metadata specific to the Ecobee climate, if applicable.

          <Expandable title="properties">
            <ResponseField name="climate_ref" type="String">
              Reference to the Ecobee climate, if applicable.
            </ResponseField>

            <ResponseField name="is_optimized" type="Boolean">
              Indicates if the climate preset is optimized by Ecobee.
            </ResponseField>

            <ResponseField name="owner" type="Enum (String)">
              Indicates whether the climate preset is owned by the user or the system.
            </ResponseField>
          </Expandable>
        </ResponseField>

        <ResponseField name="fan_mode_setting" type="Enum (String)">
          Desired [fan mode setting](/capability-guides/thermostats/configure-current-climate-settings#fan-mode-settings), such as `on`, `auto`, or `circulate`.
        </ResponseField>

        <ResponseField name="heating_set_point_celsius" type="number">
          Temperature to which the thermostat should heat (in °C). See also [Set Points](/capability-guides/thermostats/understanding-thermostat-concepts/set-points).
        </ResponseField>

        <ResponseField name="heating_set_point_fahrenheit" type="number">
          Temperature to which the thermostat should heat (in °F). See also [Set Points](/capability-guides/thermostats/understanding-thermostat-concepts/set-points).
        </ResponseField>

        <ResponseField name="hvac_mode_setting" type="Enum (String)">
          Desired [HVAC mode](/capability-guides/thermostats/understanding-thermostat-concepts/hvac-mode) setting, such as `heat`, `cool`, `heat_cool`, or `off`.
        </ResponseField>

        <ResponseField name="manual_override_allowed" type="Boolean">
          **Deprecated**. Use 'thermostat\_schedule.is\_override\_allowed'

          Indicates whether a person at the thermostat can change the thermostat's settings. See [Specifying Manual Override Permissions](/capability-guides/thermostats/creating-and-managing-thermostat-schedules#specifying-manual-override-permissions).
        </ResponseField>

        <ResponseField name="name" type="String">
          User-friendly name to identify the [climate preset](/capability-guides/thermostats/creating-and-managing-climate-presets).
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="default_climate_setting" type="Object">
      **Deprecated**. use fallback\_climate\_preset\_key to specify a fallback climate preset instead.

      The default climate setting.

      <Expandable title="properties">
        <ResponseField name="can_delete" type="Boolean">
          Indicates whether the [climate preset](/capability-guides/thermostats/creating-and-managing-climate-presets) key can be deleted.
        </ResponseField>

        <ResponseField name="can_edit" type="Boolean">
          Indicates whether the [climate preset](/capability-guides/thermostats/creating-and-managing-climate-presets) key can be edited.
        </ResponseField>

        <ResponseField name="can_use_with_thermostat_daily_programs" type="Boolean">
          Indicates whether the [climate preset](/capability-guides/thermostats/creating-and-managing-climate-presets) key can be programmed in a thermostat daily program.
        </ResponseField>

        <ResponseField name="climate_preset_key" type="String">
          Unique key to identify the [climate preset](/capability-guides/thermostats/creating-and-managing-climate-presets).
        </ResponseField>

        <ResponseField name="climate_preset_mode" type="Enum (String)">
          The climate preset mode for the thermostat, based on the available climate preset modes reported by the device.
        </ResponseField>

        <ResponseField name="cooling_set_point_celsius" type="number">
          Temperature to which the thermostat should cool (in °C). See also [Set Points](/capability-guides/thermostats/understanding-thermostat-concepts/set-points).
        </ResponseField>

        <ResponseField name="cooling_set_point_fahrenheit" type="number">
          Temperature to which the thermostat should cool (in °F). See also [Set Points](/capability-guides/thermostats/understanding-thermostat-concepts/set-points).
        </ResponseField>

        <ResponseField name="display_name" type="String">
          Display name for the [climate preset](/capability-guides/thermostats/creating-and-managing-climate-presets).
        </ResponseField>

        <ResponseField name="ecobee_metadata" type="Object">
          Metadata specific to the Ecobee climate, if applicable.

          <Expandable title="properties">
            <ResponseField name="climate_ref" type="String">
              Reference to the Ecobee climate, if applicable.
            </ResponseField>

            <ResponseField name="is_optimized" type="Boolean">
              Indicates if the climate preset is optimized by Ecobee.
            </ResponseField>

            <ResponseField name="owner" type="Enum (String)">
              Indicates whether the climate preset is owned by the user or the system.
            </ResponseField>
          </Expandable>
        </ResponseField>

        <ResponseField name="fan_mode_setting" type="Enum (String)">
          Desired [fan mode setting](/capability-guides/thermostats/configure-current-climate-settings#fan-mode-settings), such as `on`, `auto`, or `circulate`.
        </ResponseField>

        <ResponseField name="heating_set_point_celsius" type="number">
          Temperature to which the thermostat should heat (in °C). See also [Set Points](/capability-guides/thermostats/understanding-thermostat-concepts/set-points).
        </ResponseField>

        <ResponseField name="heating_set_point_fahrenheit" type="number">
          Temperature to which the thermostat should heat (in °F). See also [Set Points](/capability-guides/thermostats/understanding-thermostat-concepts/set-points).
        </ResponseField>

        <ResponseField name="hvac_mode_setting" type="Enum (String)">
          Desired [HVAC mode](/capability-guides/thermostats/understanding-thermostat-concepts/hvac-mode) setting, such as `heat`, `cool`, `heat_cool`, or `off`.
        </ResponseField>

        <ResponseField name="manual_override_allowed" type="Boolean">
          **Deprecated**. Use 'thermostat\_schedule.is\_override\_allowed'

          Indicates whether a person at the thermostat can change the thermostat's settings. See [Specifying Manual Override Permissions](/capability-guides/thermostats/creating-and-managing-thermostat-schedules#specifying-manual-override-permissions).
        </ResponseField>

        <ResponseField name="name" type="String">
          User-friendly name to identify the [climate preset](/capability-guides/thermostats/creating-and-managing-climate-presets).
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="fallback_climate_preset_key" type="String">
      Key of the [fallback climate preset](/capability-guides/thermostats/creating-and-managing-climate-presets/setting-the-fallback-climate-preset) for the thermostat.
    </ResponseField>

    <ResponseField name="fan_mode_setting" type="Enum (String)">
      **Deprecated**. Use `current_climate_setting.fan_mode_setting` instead.

      The fan mode setting.
    </ResponseField>

    <ResponseField name="is_cooling" type="Boolean">
      Indicates whether the connected HVAC system is currently cooling, as reported by the thermostat.
    </ResponseField>

    <ResponseField name="is_fan_running" type="Boolean">
      Indicates whether the fan in the connected HVAC system is currently running, as reported by the thermostat.
    </ResponseField>

    <ResponseField name="is_heating" type="Boolean">
      Indicates whether the connected HVAC system is currently heating, as reported by the thermostat.
    </ResponseField>

    <ResponseField name="is_temporary_manual_override_active" type="Boolean">
      Indicates whether the current thermostat settings differ from the most recent active program or schedule that Seam activated. For this condition to occur, `current_climate_setting.manual_override_allowed` must also be `true`.
    </ResponseField>

    <ResponseField name="max_cooling_set_point_celsius" type="number">
      Maximum [cooling set point](/capability-guides/thermostats/understanding-thermostat-concepts/set-points#cooling-set-point) in °C.
    </ResponseField>

    <ResponseField name="max_cooling_set_point_fahrenheit" type="number">
      Maximum [cooling set point](/capability-guides/thermostats/understanding-thermostat-concepts/set-points#cooling-set-point) in °F.
    </ResponseField>

    <ResponseField name="max_heating_set_point_celsius" type="number">
      Maximum [heating set point](/capability-guides/thermostats/understanding-thermostat-concepts/set-points#heating-set-point) in °C.
    </ResponseField>

    <ResponseField name="max_heating_set_point_fahrenheit" type="number">
      Maximum [heating set point](/capability-guides/thermostats/understanding-thermostat-concepts/set-points#heating-set-point) in °F.
    </ResponseField>

    <ResponseField name="max_thermostat_daily_program_periods_per_day" type="number">
      Maximum number of periods that the thermostat can support per day. For example, if the thermostat supports 4 periods per day, this value is 4.
    </ResponseField>

    <ResponseField name="max_unique_climate_presets_per_thermostat_weekly_program" type="number">
      Maximum number of climate presets that the thermostat can support for weekly programming.
    </ResponseField>

    <ResponseField name="min_cooling_set_point_celsius" type="number">
      Minimum [cooling set point](/capability-guides/thermostats/understanding-thermostat-concepts/set-points#cooling-set-point) in °C.
    </ResponseField>

    <ResponseField name="min_cooling_set_point_fahrenheit" type="number">
      Minimum [cooling set point](/capability-guides/thermostats/understanding-thermostat-concepts/set-points#cooling-set-point) in °F.
    </ResponseField>

    <ResponseField name="min_heating_cooling_delta_celsius" type="number">
      Minimum [temperature difference](/capability-guides/thermostats/understanding-thermostat-concepts/set-points#minimum-heating-cooling-temperature-delta) in °C between the cooling and heating set points when in heat-cool (auto) mode.
    </ResponseField>

    <ResponseField name="min_heating_cooling_delta_fahrenheit" type="number">
      Minimum [temperature difference](/capability-guides/thermostats/understanding-thermostat-concepts/set-points#minimum-heating-cooling-temperature-delta) in °F between the cooling and heating set points when in heat-cool (auto) mode.
    </ResponseField>

    <ResponseField name="min_heating_set_point_celsius" type="number">
      Minimum [heating set point](/capability-guides/thermostats/understanding-thermostat-concepts/set-points#heating-set-point) in °C.
    </ResponseField>

    <ResponseField name="min_heating_set_point_fahrenheit" type="number">
      Minimum [heating set point](/capability-guides/thermostats/understanding-thermostat-concepts/set-points#heating-set-point) in °F.
    </ResponseField>

    <ResponseField name="relative_humidity" type="number">
      Reported relative humidity, as a value between 0 and 1, inclusive.
    </ResponseField>

    <ResponseField name="temperature_celsius" type="number">
      Reported temperature in °C.
    </ResponseField>

    <ResponseField name="temperature_fahrenheit" type="number">
      Reported temperature in °F.
    </ResponseField>

    <ResponseField name="temperature_threshold" type="Object">
      Current [temperature threshold](/capability-guides/thermostats/setting-and-monitoring-temperature-thresholds) set for the thermostat.

      <Expandable title="properties">
        <ResponseField name="lower_limit_celsius" type="number">
          Lower limit in °C within the current [temperature threshold](/capability-guides/thermostats/setting-and-monitoring-temperature-thresholds) set for the thermostat.
        </ResponseField>

        <ResponseField name="lower_limit_fahrenheit" type="number">
          Lower limit in °F within the current [temperature threshold](/capability-guides/thermostats/setting-and-monitoring-temperature-thresholds) set for the thermostat.
        </ResponseField>

        <ResponseField name="upper_limit_celsius" type="number">
          Upper limit in °C within the current [temperature threshold](/capability-guides/thermostats/setting-and-monitoring-temperature-thresholds) set for the thermostat.
        </ResponseField>

        <ResponseField name="upper_limit_fahrenheit" type="number">
          Upper limit in °F within the current [temperature threshold](/capability-guides/thermostats/setting-and-monitoring-temperature-thresholds) set for the thermostat.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="thermostat_daily_program_period_precision_minutes" type="number">
      Precision of the thermostat's period in minutes. For example, if the thermostat supports 15-minute periods, this value is 15. All values are relative to the top of the hour, so for 15 minutes, the periods would be 0, 15, 30, and 45 minutes past the hour.
    </ResponseField>

    <ResponseField name="thermostat_daily_programs" type="Array">
      Configured [daily programs](/capability-guides/thermostats/creating-and-managing-thermostat-programs) for the thermostat.

      <Expandable title="properties">
        <ResponseField name="created_at" type="String (ISO 8601)">
          Date and time at which the thermostat daily program was created.
        </ResponseField>

        <ResponseField name="device_id" type="String (UUID)">
          ID of the thermostat device on which the thermostat daily program is configured.
        </ResponseField>

        <ResponseField name="name" type="String">
          User-friendly name to identify the thermostat daily program.
        </ResponseField>

        <ResponseField name="periods" type="Array">
          Array of thermostat daily program periods.

          <Expandable title="properties">
            <ResponseField name="climate_preset_key" type="String">
              Key of the [climate preset](/capability-guides/thermostats/creating-and-managing-climate-presets) to activate at the `starts_at_time`.
            </ResponseField>

            <ResponseField name="starts_at_time" type="String">
              Time at which the thermostat daily program period starts, in [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) format.
            </ResponseField>
          </Expandable>
        </ResponseField>

        <ResponseField name="thermostat_daily_program_id" type="String (UUID)">
          ID of the thermostat daily program.
        </ResponseField>

        <ResponseField name="workspace_id" type="String (UUID)">
          ID of the workspace that contains the thermostat daily program.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="thermostat_weekly_program" type="Object">
      Current [weekly program](/capability-guides/thermostats/creating-and-managing-thermostat-programs) for the thermostat.

      <Expandable title="properties">
        <ResponseField name="created_at" type="String (ISO 8601)">
          Date and time at which the thermostat weekly program was created.
        </ResponseField>

        <ResponseField name="friday_program_id" type="String (UUID)">
          ID of the thermostat daily program to run on Fridays.
        </ResponseField>

        <ResponseField name="monday_program_id" type="String (UUID)">
          ID of the thermostat daily program to run on Mondays.
        </ResponseField>

        <ResponseField name="saturday_program_id" type="String (UUID)">
          ID of the thermostat daily program to run on Saturdays.
        </ResponseField>

        <ResponseField name="sunday_program_id" type="String (UUID)">
          ID of the thermostat daily program to run on Sundays.
        </ResponseField>

        <ResponseField name="thursday_program_id" type="String (UUID)">
          ID of the thermostat daily program to run on Thursdays.
        </ResponseField>

        <ResponseField name="tuesday_program_id" type="String (UUID)">
          ID of the thermostat daily program to run on Tuesdays.
        </ResponseField>

        <ResponseField name="wednesday_program_id" type="String (UUID)">
          ID of the thermostat daily program to run on Wednesdays.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="space_ids" type="Array">
  IDs of the spaces the device is in.
</ResponseField>

<ResponseField name="warnings" type="Array">
  Array of warnings associated with the device. Each warning object within the array contains two fields: `warning_code` and `message`. `warning_code` is a string that uniquely identifies the type of warning, enabling quick recognition and categorization of the issue. `message` provides a more detailed description of the warning, offering insights into the issue and potentially how to rectify it.
</ResponseField>

<ResponseField name="workspace_id" type="String (UUID)">
  Unique identifier for the Seam workspace associated with the device.
</ResponseField>

## Thermostats

<ResponseField name="active_thermostat_schedule" type="Object">
  **Deprecated**. Use `active_thermostat_schedule_id` with `/thermostats/schedules/get` instead.

  Active [thermostat schedule](/capability-guides/thermostats/creating-and-managing-thermostat-schedules).

  <Expandable title="properties">
    <ResponseField name="climate_preset_key" type="String">
      Key of the [climate preset](/capability-guides/thermostats/creating-and-managing-climate-presets) to use for the [thermostat schedule](/capability-guides/thermostats/creating-and-managing-thermostat-schedules).
    </ResponseField>

    <ResponseField name="created_at" type="String (ISO 8601)">
      Date and time at which the [thermostat schedule](/capability-guides/thermostats/creating-and-managing-thermostat-schedules) was created.
    </ResponseField>

    <ResponseField name="device_id" type="String (UUID)">
      ID of the desired [thermostat](/capability-guides/thermostats) device.
    </ResponseField>

    <ResponseField name="ends_at" type="String (ISO 8601)">
      Date and time at which the [thermostat schedule](/capability-guides/thermostats/creating-and-managing-thermostat-schedules) ends, in [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) format.
    </ResponseField>

    <ResponseField name="errors" type="Array">
      Errors associated with the [thermostat schedule](/capability-guides/thermostats/creating-and-managing-thermostat-schedules).

      <Expandable title="properties">
        <ResponseField name="created_at" type="String (ISO 8601)">
          Date and time at which Seam created the error.
        </ResponseField>

        <ResponseField name="error_code" type="String">
          Unique identifier of the type of error. Enables quick recognition and categorization of the issue.
        </ResponseField>

        <ResponseField name="message" type="String">
          Detailed description of the error. Provides insights into the issue and potentially how to rectify it.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="is_override_allowed" type="Boolean">
      Indicates whether a person at the thermostat can change the thermostat's settings after the [thermostat schedule](/capability-guides/thermostats/creating-and-managing-thermostat-schedules) starts.
    </ResponseField>

    <ResponseField name="max_override_period_minutes" type="number">
      Number of minutes for which a person at the thermostat can change the thermostat's settings after the activation of the scheduled [climate preset](/capability-guides/thermostats/creating-and-managing-climate-presets). See also [Specifying Manual Override Permissions](/capability-guides/thermostats/creating-and-managing-thermostat-schedules#specifying-manual-override-permissions).
    </ResponseField>

    <ResponseField name="name" type="String">
      User-friendly name to identify the [thermostat schedule](/capability-guides/thermostats/creating-and-managing-thermostat-schedules).
    </ResponseField>

    <ResponseField name="starts_at" type="String (ISO 8601)">
      Date and time at which the [thermostat schedule](/capability-guides/thermostats/creating-and-managing-thermostat-schedules) starts, in [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) format.
    </ResponseField>

    <ResponseField name="thermostat_schedule_id" type="String (UUID)">
      ID of the [thermostat schedule](/capability-guides/thermostats/creating-and-managing-thermostat-schedules).
    </ResponseField>

    <ResponseField name="workspace_id" type="String (UUID)">
      ID of the workspace that contains the thermostat schedule.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="active_thermostat_schedule_id" type="String (UUID)">
  ID of the active [thermostat schedule](/capability-guides/thermostats/creating-and-managing-thermostat-schedules).
</ResponseField>

<ResponseField name="available_climate_preset_modes" type="Array">
  Climate preset modes that the thermostat supports, such as "home", "away", "wake", "sleep", "occupied", and "unoccupied".
</ResponseField>

<ResponseField name="available_climate_presets" type="Array">
  Available [climate presets](/capability-guides/thermostats/creating-and-managing-climate-presets) for the thermostat.

  <Expandable title="properties">
    <ResponseField name="can_delete" type="Boolean">
      Indicates whether the [climate preset](/capability-guides/thermostats/creating-and-managing-climate-presets) key can be deleted.
    </ResponseField>

    <ResponseField name="can_edit" type="Boolean">
      Indicates whether the [climate preset](/capability-guides/thermostats/creating-and-managing-climate-presets) key can be edited.
    </ResponseField>

    <ResponseField name="can_use_with_thermostat_daily_programs" type="Boolean">
      Indicates whether the [climate preset](/capability-guides/thermostats/creating-and-managing-climate-presets) key can be programmed in a thermostat daily program.
    </ResponseField>

    <ResponseField name="climate_preset_key" type="String">
      Unique key to identify the [climate preset](/capability-guides/thermostats/creating-and-managing-climate-presets).
    </ResponseField>

    <ResponseField name="climate_preset_mode" type="Enum (String)">
      The climate preset mode for the thermostat, based on the available climate preset modes reported by the device.
    </ResponseField>

    <ResponseField name="cooling_set_point_celsius" type="number">
      Temperature to which the thermostat should cool (in °C). See also [Set Points](/capability-guides/thermostats/understanding-thermostat-concepts/set-points).
    </ResponseField>

    <ResponseField name="cooling_set_point_fahrenheit" type="number">
      Temperature to which the thermostat should cool (in °F). See also [Set Points](/capability-guides/thermostats/understanding-thermostat-concepts/set-points).
    </ResponseField>

    <ResponseField name="display_name" type="String">
      Display name for the [climate preset](/capability-guides/thermostats/creating-and-managing-climate-presets).
    </ResponseField>

    <ResponseField name="ecobee_metadata" type="Object">
      Metadata specific to the Ecobee climate, if applicable.

      <Expandable title="properties">
        <ResponseField name="climate_ref" type="String">
          Reference to the Ecobee climate, if applicable.
        </ResponseField>

        <ResponseField name="is_optimized" type="Boolean">
          Indicates if the climate preset is optimized by Ecobee.
        </ResponseField>

        <ResponseField name="owner" type="Enum (String)">
          Indicates whether the climate preset is owned by the user or the system.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="fan_mode_setting" type="Enum (String)">
      Desired [fan mode setting](/capability-guides/thermostats/configure-current-climate-settings#fan-mode-settings), such as `on`, `auto`, or `circulate`.
    </ResponseField>

    <ResponseField name="heating_set_point_celsius" type="number">
      Temperature to which the thermostat should heat (in °C). See also [Set Points](/capability-guides/thermostats/understanding-thermostat-concepts/set-points).
    </ResponseField>

    <ResponseField name="heating_set_point_fahrenheit" type="number">
      Temperature to which the thermostat should heat (in °F). See also [Set Points](/capability-guides/thermostats/understanding-thermostat-concepts/set-points).
    </ResponseField>

    <ResponseField name="hvac_mode_setting" type="Enum (String)">
      Desired [HVAC mode](/capability-guides/thermostats/understanding-thermostat-concepts/hvac-mode) setting, such as `heat`, `cool`, `heat_cool`, or `off`.
    </ResponseField>

    <ResponseField name="manual_override_allowed" type="Boolean">
      **Deprecated**. Use 'thermostat\_schedule.is\_override\_allowed'

      Indicates whether a person at the thermostat can change the thermostat's settings. See [Specifying Manual Override Permissions](/capability-guides/thermostats/creating-and-managing-thermostat-schedules#specifying-manual-override-permissions).
    </ResponseField>

    <ResponseField name="name" type="String">
      User-friendly name to identify the [climate preset](/capability-guides/thermostats/creating-and-managing-climate-presets).
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="available_fan_mode_settings" type="Array">
  Fan mode settings that the thermostat supports.
</ResponseField>

<ResponseField name="available_hvac_mode_settings" type="Array">
  HVAC mode settings that the thermostat supports.
</ResponseField>

<ResponseField name="current_climate_setting" type="Object">
  Current climate setting.

  <Expandable title="properties">
    <ResponseField name="can_delete" type="Boolean">
      Indicates whether the [climate preset](/capability-guides/thermostats/creating-and-managing-climate-presets) key can be deleted.
    </ResponseField>

    <ResponseField name="can_edit" type="Boolean">
      Indicates whether the [climate preset](/capability-guides/thermostats/creating-and-managing-climate-presets) key can be edited.
    </ResponseField>

    <ResponseField name="can_use_with_thermostat_daily_programs" type="Boolean">
      Indicates whether the [climate preset](/capability-guides/thermostats/creating-and-managing-climate-presets) key can be programmed in a thermostat daily program.
    </ResponseField>

    <ResponseField name="climate_preset_key" type="String">
      Unique key to identify the [climate preset](/capability-guides/thermostats/creating-and-managing-climate-presets).
    </ResponseField>

    <ResponseField name="climate_preset_mode" type="Enum (String)">
      The climate preset mode for the thermostat, based on the available climate preset modes reported by the device.
    </ResponseField>

    <ResponseField name="cooling_set_point_celsius" type="number">
      Temperature to which the thermostat should cool (in °C). See also [Set Points](/capability-guides/thermostats/understanding-thermostat-concepts/set-points).
    </ResponseField>

    <ResponseField name="cooling_set_point_fahrenheit" type="number">
      Temperature to which the thermostat should cool (in °F). See also [Set Points](/capability-guides/thermostats/understanding-thermostat-concepts/set-points).
    </ResponseField>

    <ResponseField name="display_name" type="String">
      Display name for the [climate preset](/capability-guides/thermostats/creating-and-managing-climate-presets).
    </ResponseField>

    <ResponseField name="ecobee_metadata" type="Object">
      Metadata specific to the Ecobee climate, if applicable.

      <Expandable title="properties">
        <ResponseField name="climate_ref" type="String">
          Reference to the Ecobee climate, if applicable.
        </ResponseField>

        <ResponseField name="is_optimized" type="Boolean">
          Indicates if the climate preset is optimized by Ecobee.
        </ResponseField>

        <ResponseField name="owner" type="Enum (String)">
          Indicates whether the climate preset is owned by the user or the system.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="fan_mode_setting" type="Enum (String)">
      Desired [fan mode setting](/capability-guides/thermostats/configure-current-climate-settings#fan-mode-settings), such as `on`, `auto`, or `circulate`.
    </ResponseField>

    <ResponseField name="heating_set_point_celsius" type="number">
      Temperature to which the thermostat should heat (in °C). See also [Set Points](/capability-guides/thermostats/understanding-thermostat-concepts/set-points).
    </ResponseField>

    <ResponseField name="heating_set_point_fahrenheit" type="number">
      Temperature to which the thermostat should heat (in °F). See also [Set Points](/capability-guides/thermostats/understanding-thermostat-concepts/set-points).
    </ResponseField>

    <ResponseField name="hvac_mode_setting" type="Enum (String)">
      Desired [HVAC mode](/capability-guides/thermostats/understanding-thermostat-concepts/hvac-mode) setting, such as `heat`, `cool`, `heat_cool`, or `off`.
    </ResponseField>

    <ResponseField name="manual_override_allowed" type="Boolean">
      **Deprecated**. Use 'thermostat\_schedule.is\_override\_allowed'

      Indicates whether a person at the thermostat can change the thermostat's settings. See [Specifying Manual Override Permissions](/capability-guides/thermostats/creating-and-managing-thermostat-schedules#specifying-manual-override-permissions).
    </ResponseField>

    <ResponseField name="name" type="String">
      User-friendly name to identify the [climate preset](/capability-guides/thermostats/creating-and-managing-climate-presets).
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="default_climate_setting" type="Object">
  **Deprecated**. use fallback\_climate\_preset\_key to specify a fallback climate preset instead.

  The default climate setting.

  <Expandable title="properties">
    <ResponseField name="can_delete" type="Boolean">
      Indicates whether the [climate preset](/capability-guides/thermostats/creating-and-managing-climate-presets) key can be deleted.
    </ResponseField>

    <ResponseField name="can_edit" type="Boolean">
      Indicates whether the [climate preset](/capability-guides/thermostats/creating-and-managing-climate-presets) key can be edited.
    </ResponseField>

    <ResponseField name="can_use_with_thermostat_daily_programs" type="Boolean">
      Indicates whether the [climate preset](/capability-guides/thermostats/creating-and-managing-climate-presets) key can be programmed in a thermostat daily program.
    </ResponseField>

    <ResponseField name="climate_preset_key" type="String">
      Unique key to identify the [climate preset](/capability-guides/thermostats/creating-and-managing-climate-presets).
    </ResponseField>

    <ResponseField name="climate_preset_mode" type="Enum (String)">
      The climate preset mode for the thermostat, based on the available climate preset modes reported by the device.
    </ResponseField>

    <ResponseField name="cooling_set_point_celsius" type="number">
      Temperature to which the thermostat should cool (in °C). See also [Set Points](/capability-guides/thermostats/understanding-thermostat-concepts/set-points).
    </ResponseField>

    <ResponseField name="cooling_set_point_fahrenheit" type="number">
      Temperature to which the thermostat should cool (in °F). See also [Set Points](/capability-guides/thermostats/understanding-thermostat-concepts/set-points).
    </ResponseField>

    <ResponseField name="display_name" type="String">
      Display name for the [climate preset](/capability-guides/thermostats/creating-and-managing-climate-presets).
    </ResponseField>

    <ResponseField name="ecobee_metadata" type="Object">
      Metadata specific to the Ecobee climate, if applicable.

      <Expandable title="properties">
        <ResponseField name="climate_ref" type="String">
          Reference to the Ecobee climate, if applicable.
        </ResponseField>

        <ResponseField name="is_optimized" type="Boolean">
          Indicates if the climate preset is optimized by Ecobee.
        </ResponseField>

        <ResponseField name="owner" type="Enum (String)">
          Indicates whether the climate preset is owned by the user or the system.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="fan_mode_setting" type="Enum (String)">
      Desired [fan mode setting](/capability-guides/thermostats/configure-current-climate-settings#fan-mode-settings), such as `on`, `auto`, or `circulate`.
    </ResponseField>

    <ResponseField name="heating_set_point_celsius" type="number">
      Temperature to which the thermostat should heat (in °C). See also [Set Points](/capability-guides/thermostats/understanding-thermostat-concepts/set-points).
    </ResponseField>

    <ResponseField name="heating_set_point_fahrenheit" type="number">
      Temperature to which the thermostat should heat (in °F). See also [Set Points](/capability-guides/thermostats/understanding-thermostat-concepts/set-points).
    </ResponseField>

    <ResponseField name="hvac_mode_setting" type="Enum (String)">
      Desired [HVAC mode](/capability-guides/thermostats/understanding-thermostat-concepts/hvac-mode) setting, such as `heat`, `cool`, `heat_cool`, or `off`.
    </ResponseField>

    <ResponseField name="manual_override_allowed" type="Boolean">
      **Deprecated**. Use 'thermostat\_schedule.is\_override\_allowed'

      Indicates whether a person at the thermostat can change the thermostat's settings. See [Specifying Manual Override Permissions](/capability-guides/thermostats/creating-and-managing-thermostat-schedules#specifying-manual-override-permissions).
    </ResponseField>

    <ResponseField name="name" type="String">
      User-friendly name to identify the [climate preset](/capability-guides/thermostats/creating-and-managing-climate-presets).
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="fallback_climate_preset_key" type="String">
  Key of the [fallback climate preset](/capability-guides/thermostats/creating-and-managing-climate-presets/setting-the-fallback-climate-preset) for the thermostat.
</ResponseField>

<ResponseField name="fan_mode_setting" type="Enum (String)">
  **Deprecated**. Use `current_climate_setting.fan_mode_setting` instead.

  The fan mode setting.
</ResponseField>

<ResponseField name="is_cooling" type="Boolean">
  Indicates whether the connected HVAC system is currently cooling, as reported by the thermostat.
</ResponseField>

<ResponseField name="is_fan_running" type="Boolean">
  Indicates whether the fan in the connected HVAC system is currently running, as reported by the thermostat.
</ResponseField>

<ResponseField name="is_heating" type="Boolean">
  Indicates whether the connected HVAC system is currently heating, as reported by the thermostat.
</ResponseField>

<ResponseField name="is_temporary_manual_override_active" type="Boolean">
  Indicates whether the current thermostat settings differ from the most recent active program or schedule that Seam activated. For this condition to occur, `current_climate_setting.manual_override_allowed` must also be `true`.
</ResponseField>

<ResponseField name="max_cooling_set_point_celsius" type="number">
  Maximum [cooling set point](/capability-guides/thermostats/understanding-thermostat-concepts/set-points#cooling-set-point) in °C.
</ResponseField>

<ResponseField name="max_cooling_set_point_fahrenheit" type="number">
  Maximum [cooling set point](/capability-guides/thermostats/understanding-thermostat-concepts/set-points#cooling-set-point) in °F.
</ResponseField>

<ResponseField name="max_heating_set_point_celsius" type="number">
  Maximum [heating set point](/capability-guides/thermostats/understanding-thermostat-concepts/set-points#heating-set-point) in °C.
</ResponseField>

<ResponseField name="max_heating_set_point_fahrenheit" type="number">
  Maximum [heating set point](/capability-guides/thermostats/understanding-thermostat-concepts/set-points#heating-set-point) in °F.
</ResponseField>

<ResponseField name="max_thermostat_daily_program_periods_per_day" type="number">
  Maximum number of periods that the thermostat can support per day. For example, if the thermostat supports 4 periods per day, this value is 4.
</ResponseField>

<ResponseField name="max_unique_climate_presets_per_thermostat_weekly_program" type="number">
  Maximum number of climate presets that the thermostat can support for weekly programming.
</ResponseField>

<ResponseField name="min_cooling_set_point_celsius" type="number">
  Minimum [cooling set point](/capability-guides/thermostats/understanding-thermostat-concepts/set-points#cooling-set-point) in °C.
</ResponseField>

<ResponseField name="min_cooling_set_point_fahrenheit" type="number">
  Minimum [cooling set point](/capability-guides/thermostats/understanding-thermostat-concepts/set-points#cooling-set-point) in °F.
</ResponseField>

<ResponseField name="min_heating_cooling_delta_celsius" type="number">
  Minimum [temperature difference](/capability-guides/thermostats/understanding-thermostat-concepts/set-points#minimum-heating-cooling-temperature-delta) in °C between the cooling and heating set points when in heat-cool (auto) mode.
</ResponseField>

<ResponseField name="min_heating_cooling_delta_fahrenheit" type="number">
  Minimum [temperature difference](/capability-guides/thermostats/understanding-thermostat-concepts/set-points#minimum-heating-cooling-temperature-delta) in °F between the cooling and heating set points when in heat-cool (auto) mode.
</ResponseField>

<ResponseField name="min_heating_set_point_celsius" type="number">
  Minimum [heating set point](/capability-guides/thermostats/understanding-thermostat-concepts/set-points#heating-set-point) in °C.
</ResponseField>

<ResponseField name="min_heating_set_point_fahrenheit" type="number">
  Minimum [heating set point](/capability-guides/thermostats/understanding-thermostat-concepts/set-points#heating-set-point) in °F.
</ResponseField>

<ResponseField name="relative_humidity" type="number">
  Reported relative humidity, as a value between 0 and 1, inclusive.
</ResponseField>

<ResponseField name="temperature_celsius" type="number">
  Reported temperature in °C.
</ResponseField>

<ResponseField name="temperature_fahrenheit" type="number">
  Reported temperature in °F.
</ResponseField>

<ResponseField name="temperature_threshold" type="Object">
  Current [temperature threshold](/capability-guides/thermostats/setting-and-monitoring-temperature-thresholds) set for the thermostat.

  <Expandable title="properties">
    <ResponseField name="lower_limit_celsius" type="number">
      Lower limit in °C within the current [temperature threshold](/capability-guides/thermostats/setting-and-monitoring-temperature-thresholds) set for the thermostat.
    </ResponseField>

    <ResponseField name="lower_limit_fahrenheit" type="number">
      Lower limit in °F within the current [temperature threshold](/capability-guides/thermostats/setting-and-monitoring-temperature-thresholds) set for the thermostat.
    </ResponseField>

    <ResponseField name="upper_limit_celsius" type="number">
      Upper limit in °C within the current [temperature threshold](/capability-guides/thermostats/setting-and-monitoring-temperature-thresholds) set for the thermostat.
    </ResponseField>

    <ResponseField name="upper_limit_fahrenheit" type="number">
      Upper limit in °F within the current [temperature threshold](/capability-guides/thermostats/setting-and-monitoring-temperature-thresholds) set for the thermostat.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="thermostat_daily_program_period_precision_minutes" type="number">
  Precision of the thermostat's period in minutes. For example, if the thermostat supports 15-minute periods, this value is 15. All values are relative to the top of the hour, so for 15 minutes, the periods would be 0, 15, 30, and 45 minutes past the hour.
</ResponseField>

<ResponseField name="thermostat_daily_programs" type="Array">
  Configured [daily programs](/capability-guides/thermostats/creating-and-managing-thermostat-programs) for the thermostat.

  <Expandable title="properties">
    <ResponseField name="created_at" type="String (ISO 8601)">
      Date and time at which the thermostat daily program was created.
    </ResponseField>

    <ResponseField name="device_id" type="String (UUID)">
      ID of the thermostat device on which the thermostat daily program is configured.
    </ResponseField>

    <ResponseField name="name" type="String">
      User-friendly name to identify the thermostat daily program.
    </ResponseField>

    <ResponseField name="periods" type="Array">
      Array of thermostat daily program periods.

      <Expandable title="properties">
        <ResponseField name="climate_preset_key" type="String">
          Key of the [climate preset](/capability-guides/thermostats/creating-and-managing-climate-presets) to activate at the `starts_at_time`.
        </ResponseField>

        <ResponseField name="starts_at_time" type="String">
          Time at which the thermostat daily program period starts, in [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) format.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="thermostat_daily_program_id" type="String (UUID)">
      ID of the thermostat daily program.
    </ResponseField>

    <ResponseField name="workspace_id" type="String (UUID)">
      ID of the workspace that contains the thermostat daily program.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="thermostat_weekly_program" type="Object">
  Current [weekly program](/capability-guides/thermostats/creating-and-managing-thermostat-programs) for the thermostat.

  <Expandable title="properties">
    <ResponseField name="created_at" type="String (ISO 8601)">
      Date and time at which the thermostat weekly program was created.
    </ResponseField>

    <ResponseField name="friday_program_id" type="String (UUID)">
      ID of the thermostat daily program to run on Fridays.
    </ResponseField>

    <ResponseField name="monday_program_id" type="String (UUID)">
      ID of the thermostat daily program to run on Mondays.
    </ResponseField>

    <ResponseField name="saturday_program_id" type="String (UUID)">
      ID of the thermostat daily program to run on Saturdays.
    </ResponseField>

    <ResponseField name="sunday_program_id" type="String (UUID)">
      ID of the thermostat daily program to run on Sundays.
    </ResponseField>

    <ResponseField name="thursday_program_id" type="String (UUID)">
      ID of the thermostat daily program to run on Thursdays.
    </ResponseField>

    <ResponseField name="tuesday_program_id" type="String (UUID)">
      ID of the thermostat daily program to run on Tuesdays.
    </ResponseField>

    <ResponseField name="wednesday_program_id" type="String (UUID)">
      ID of the thermostat daily program to run on Wednesdays.
    </ResponseField>
  </Expandable>
</ResponseField>


# Set to Off Mode
Source: https://docs.seam.co/api/thermostats/off

/openapi.json post /thermostats/off
Sets a specified [thermostat](/capability-guides/thermostats) to ["off" mode](/capability-guides/thermostats/configure-current-climate-settings).



# Create a Thermostat Schedule
Source: https://docs.seam.co/api/thermostats/schedules/create

/openapi.json post /thermostats/schedules/create
Creates a new [thermostat schedule](/capability-guides/thermostats/creating-and-managing-thermostat-schedules) for a specified [thermostat](/capability-guides/thermostats).



# Delete a Thermostat Schedule
Source: https://docs.seam.co/api/thermostats/schedules/delete

/openapi.json post /thermostats/schedules/delete
Deletes a [thermostat schedule](/capability-guides/thermostats/creating-and-managing-thermostat-schedules) for a specified [thermostat](/capability-guides/thermostats).



# Get a Thermostat Schedule
Source: https://docs.seam.co/api/thermostats/schedules/get

/openapi.json post /thermostats/schedules/get
Returns a specified [thermostat schedule](/capability-guides/thermostats/creating-and-managing-thermostat-schedules).



# List Thermostat Schedules
Source: https://docs.seam.co/api/thermostats/schedules/list

/openapi.json post /thermostats/schedules/list
Returns a list of all [thermostat schedules](/capability-guides/thermostats/creating-and-managing-thermostat-schedules) for a specified [thermostat](/capability-guides/thermostats).



# Thermostat Schedules
Source: https://docs.seam.co/api/thermostats/schedules/object

Learn how the thermostat_schedule object activates a climate preset on a thermostat at a starting time and deactivates it at a specified ending time.

## The thermostat\_schedule Object

Represents a [thermostat schedule](/capability-guides/thermostats/creating-and-managing-thermostat-schedules) that activates a configured [climate preset](/capability-guides/thermostats/creating-and-managing-climate-presets) on a [thermostat](/capability-guides/thermostats) at a specified starting time and deactivates the climate preset at a specified ending time.

<ResponseExample>
  ```json Thermostat Schedule theme={null}
  {
    "climate_preset_key": "eco",
    "created_at": "2025-06-14T16:54:17.946316Z",
    "device_id": "dc1dfc4b-8082-453f-a953-276941af8650",
    "ends_at": "2025-07-14T16:54:17.946313Z",
    "errors": [],
    "is_override_allowed": true,
    "max_override_period_minutes": 90,
    "name": "My Thermostat Schedule",
    "starts_at": "2025-07-12T16:54:17.946313Z",
    "thermostat_schedule_id": "af2cb7f7-9f28-40da-a0a0-e7a008ef7a35",
    "workspace_id": "58419b36-6103-44e5-aa83-2163e90cce01"
  }
  ```
</ResponseExample>

***

## Properties

<ResponseField name="climate_preset_key" type="String">
  Key of the [climate preset](/capability-guides/thermostats/creating-and-managing-climate-presets) to use for the [thermostat schedule](/capability-guides/thermostats/creating-and-managing-thermostat-schedules).
</ResponseField>

<ResponseField name="created_at" type="String (ISO 8601)">
  Date and time at which the [thermostat schedule](/capability-guides/thermostats/creating-and-managing-thermostat-schedules) was created.
</ResponseField>

<ResponseField name="device_id" type="String (UUID)">
  ID of the desired [thermostat](/capability-guides/thermostats) device.
</ResponseField>

<ResponseField name="ends_at" type="String (ISO 8601)">
  Date and time at which the [thermostat schedule](/capability-guides/thermostats/creating-and-managing-thermostat-schedules) ends, in [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) format.
</ResponseField>

<ResponseField name="errors" type="Array">
  Errors associated with the [thermostat schedule](/capability-guides/thermostats/creating-and-managing-thermostat-schedules).

  <Expandable title="properties">
    <ResponseField name="created_at" type="String (ISO 8601)">
      Date and time at which Seam created the error.
    </ResponseField>

    <ResponseField name="error_code" type="String">
      Unique identifier of the type of error. Enables quick recognition and categorization of the issue.
    </ResponseField>

    <ResponseField name="message" type="String">
      Detailed description of the error. Provides insights into the issue and potentially how to rectify it.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="is_override_allowed" type="Boolean">
  Indicates whether a person at the thermostat can change the thermostat's settings after the [thermostat schedule](/capability-guides/thermostats/creating-and-managing-thermostat-schedules) starts.
</ResponseField>

<ResponseField name="max_override_period_minutes" type="number">
  Number of minutes for which a person at the thermostat can change the thermostat's settings after the activation of the scheduled [climate preset](/capability-guides/thermostats/creating-and-managing-climate-presets). See also [Specifying Manual Override Permissions](/capability-guides/thermostats/creating-and-managing-thermostat-schedules#specifying-manual-override-permissions).
</ResponseField>

<ResponseField name="name" type="String">
  User-friendly name to identify the [thermostat schedule](/capability-guides/thermostats/creating-and-managing-thermostat-schedules).
</ResponseField>

<ResponseField name="starts_at" type="String (ISO 8601)">
  Date and time at which the [thermostat schedule](/capability-guides/thermostats/creating-and-managing-thermostat-schedules) starts, in [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) format.
</ResponseField>

<ResponseField name="thermostat_schedule_id" type="String (UUID)">
  ID of the [thermostat schedule](/capability-guides/thermostats/creating-and-managing-thermostat-schedules).
</ResponseField>

<ResponseField name="workspace_id" type="String (UUID)">
  ID of the workspace that contains the thermostat schedule.
</ResponseField>


# Update a Thermostat Schedule
Source: https://docs.seam.co/api/thermostats/schedules/update

/openapi.json post /thermostats/schedules/update
Updates a specified [thermostat schedule](/capability-guides/thermostats/creating-and-managing-thermostat-schedules).



# Set the Fallback Climate Preset
Source: https://docs.seam.co/api/thermostats/set_fallback_climate_preset

/openapi.json post /thermostats/set_fallback_climate_preset
Sets a specified [climate preset](/capability-guides/thermostats/creating-and-managing-climate-presets) as the ["fallback"](/capability-guides/thermostats/creating-and-managing-climate-presets/setting-the-fallback-climate-preset) preset for a specified [thermostat](/capability-guides/thermostats).



# Set the Fan Mode Setting
Source: https://docs.seam.co/api/thermostats/set_fan_mode

/openapi.json post /thermostats/set_fan_mode
Sets the [fan mode setting](/capability-guides/thermostats/configure-current-climate-settings#fan-mode-settings) for a specified [thermostat](/capability-guides/thermostats).



# Set the HVAC Mode
Source: https://docs.seam.co/api/thermostats/set_hvac_mode

/openapi.json post /thermostats/set_hvac_mode
Sets the [HVAC mode](/capability-guides/thermostats/configure-current-climate-settings) for a specified [thermostat](/capability-guides/thermostats).



# Set a Temperature Threshold
Source: https://docs.seam.co/api/thermostats/set_temperature_threshold

/openapi.json post /thermostats/set_temperature_threshold
Sets a [temperature threshold](/capability-guides/thermostats/setting-and-monitoring-temperature-thresholds) for a specified thermostat. Seam emits a `thermostat.temperature_threshold_exceeded` event and adds a warning on a thermostat if it reports a temperature outside the threshold range.



# HVAC Mode Adjusted
Source: https://docs.seam.co/api/thermostats/simulate/hvac_mode_adjusted

/openapi.json post /thermostats/simulate/hvac_mode_adjusted
Simulates having adjusted the [HVAC mode](/capability-guides/thermostats/understanding-thermostat-concepts/hvac-mode) for a [thermostat](/capability-guides/thermostats). Only applicable for [sandbox devices](/core-concepts/workspaces#sandbox-workspaces). See also [Testing Your Thermostat App with Simulate Endpoints](/capability-guides/thermostats/testing-your-thermostat-app-with-simulate-endpoints).



# Temperature Reached
Source: https://docs.seam.co/api/thermostats/simulate/temperature_reached

/openapi.json post /thermostats/simulate/temperature_reached
Simulates a [thermostat](/capability-guides/thermostats) reaching a specified temperature. Only applicable for [sandbox devices](/core-concepts/workspaces#sandbox-workspaces). See also [Testing Your Thermostat App with Simulate Endpoints](/capability-guides/thermostats/testing-your-thermostat-app-with-simulate-endpoints).



# Update a Climate Preset
Source: https://docs.seam.co/api/thermostats/update_climate_preset

/openapi.json post /thermostats/update_climate_preset
Updates a specified [climate preset](/capability-guides/thermostats/creating-and-managing-climate-presets) for a specified [thermostat](/capability-guides/thermostats).



# Update the Thermostat Weekly Program
Source: https://docs.seam.co/api/thermostats/update_weekly_program

/openapi.json post /thermostats/update_weekly_program
Updates the thermostat weekly program for a thermostat device. To configure a weekly program, specify the ID of the daily program that you want to use for each day of the week. When you update a weekly program, the set of programs that you specify overwrites any previous weekly program for the thermostat.



# Add an ACS User to a User Identity
Source: https://docs.seam.co/api/user_identities/add_acs_user

/openapi.json post /user_identities/add_acs_user
Adds a specified [access system user](/low-level-apis/access-systems/user-management) to a specified [user identity](/capability-guides/mobile-access/managing-mobile-app-user-accounts-with-user-identities#what-is-a-user-identity).

You must specify either `user_identity_id` or `user_identity_key` to identify the user identity.

If `user_identity_key` is provided, but the user identity doesn't exist, a new user identity will be created automatically using information from the ACS user.



# Create a User Identity
Source: https://docs.seam.co/api/user_identities/create

/openapi.json post /user_identities/create
Creates a new [user identity](/capability-guides/mobile-access/managing-mobile-app-user-accounts-with-user-identities#what-is-a-user-identity).



# Delete a User Identity
Source: https://docs.seam.co/api/user_identities/delete

/openapi.json post /user_identities/delete
Deletes a specified [user identity](/capability-guides/mobile-access/managing-mobile-app-user-accounts-with-user-identities#what-is-a-user-identity). This deletes the user identity and all associated resources, including any [credentials](/api/acs/credentials/object), [acs users](/api/acs/users/object) and [client sessions](/api/client_sessions/object).



# User Identity Errors and Warnings
Source: https://docs.seam.co/api/user_identities/errors

Errors and warnings that Seam reports on the User Identity resource, each with its code and meaning.

## Errors

Each error is an object with the following shape:

```json Example error theme={null}
{
  "error_code": "issue_with_acs_user",
  "message": "Indicates that there is an issue with an access system user associated with this user identity.",
  "created_at": "2025-01-01T00:00:00.000Z",
  "acs_system_id": "00000000-0000-0000-0000-000000000000",
  "acs_user_id": "00000000-0000-0000-0000-000000000000"
}
```

<Accordion title="Error object properties">
  <ResponseField name="error_code" type="Enum (String)">
    Unique identifier of the type of error. Enables quick recognition and categorization of the issue.

    One of the error codes listed below.
  </ResponseField>

  <ResponseField name="message" type="String">
    Detailed description of the error. Provides insights into the issue and potentially how to rectify it.
  </ResponseField>

  <ResponseField name="created_at" type="String (ISO 8601)">
    Date and time at which Seam created the error.
  </ResponseField>

  <ResponseField name="acs_system_id" type="String (UUID)">
    ID of the access system that the user identity is associated with.
  </ResponseField>

  <ResponseField name="acs_user_id" type="String (UUID)">
    ID of the access system user that has an issue.
  </ResponseField>
</Accordion>

### `issue_with_acs_user`

Indicates that there is an issue with an access system user associated with this user identity.

***

## Warnings

Each warning is an object with the following shape:

```json Example warning theme={null}
{
  "warning_code": "being_deleted",
  "message": "Indicates that the user identity is currently being deleted.",
  "created_at": "2025-01-01T00:00:00.000Z"
}
```

<Accordion title="Warning object properties">
  <ResponseField name="warning_code" type="Enum (String)">
    Unique identifier of the type of warning. Enables quick recognition and categorization of the issue.

    One of the warning codes listed below.
  </ResponseField>

  <ResponseField name="message" type="String">
    Detailed description of the warning. Provides insights into the issue and potentially how to rectify it.
  </ResponseField>

  <ResponseField name="created_at" type="String (ISO 8601)">
    Date and time at which Seam created the warning.
  </ResponseField>
</Accordion>

### `acs_user_profile_does_not_match_user_identity`

Indicates that the ACS user's profile does not match the user identity's profile

***

### `being_deleted`

Indicates that the user identity is currently being deleted.

***


# Generate an Instant Key
Source: https://docs.seam.co/api/user_identities/generate_instant_key

/openapi.json post /user_identities/generate_instant_key
Generates a new [instant key](/use-cases/granting-access/using-instant-keys) for a specified [user identity](/capability-guides/mobile-access/managing-mobile-app-user-accounts-with-user-identities#what-is-a-user-identity).



# Get a User Identity
Source: https://docs.seam.co/api/user_identities/get

/openapi.json post /user_identities/get
Returns a specified [user identity](/capability-guides/mobile-access/managing-mobile-app-user-accounts-with-user-identities#what-is-a-user-identity).

You must include at least one request parameter.



# Grant a User Identity Access to a Device
Source: https://docs.seam.co/api/user_identities/grant_access_to_device

/openapi.json post /user_identities/grant_access_to_device
Grants a specified [user identity](/capability-guides/mobile-access/managing-mobile-app-user-accounts-with-user-identities#what-is-a-user-identity) access to a specified [device](/core-concepts/devices).



# List User Identities
Source: https://docs.seam.co/api/user_identities/list

/openapi.json post /user_identities/list
Returns a list of all [user identities](/capability-guides/mobile-access/managing-mobile-app-user-accounts-with-user-identities#what-is-a-user-identity).



# List Accessible Devices for a User Identity
Source: https://docs.seam.co/api/user_identities/list_accessible_devices

/openapi.json post /user_identities/list_accessible_devices
Returns a list of all [devices](/core-concepts/devices) associated with a specified [user identity](/capability-guides/mobile-access/managing-mobile-app-user-accounts-with-user-identities#what-is-a-user-identity). This includes devices derived from the access grants assigned to the user identity and devices directly linked to the user identity.



# List Accessible Entrances for a User Identity
Source: https://docs.seam.co/api/user_identities/list_accessible_entrances

/openapi.json post /user_identities/list_accessible_entrances
Returns a list of all [ACS entrances](/api/acs/entrances/object) accessible to a specified [user identity](/capability-guides/mobile-access/managing-mobile-app-user-accounts-with-user-identities#what-is-a-user-identity). This includes entrances derived from the access grants assigned to the user identity and entrances accessible through ACS users linked to the user identity.



# List ACS Systems Associated with a User Identity
Source: https://docs.seam.co/api/user_identities/list_acs_systems

/openapi.json post /user_identities/list_acs_systems
Returns a list of all [access systems](/low-level-apis/access-systems) associated with a specified [user identity](/capability-guides/mobile-access/managing-mobile-app-user-accounts-with-user-identities#what-is-a-user-identity).



# List ACS Users Associated with a User Identity
Source: https://docs.seam.co/api/user_identities/list_acs_users

/openapi.json post /user_identities/list_acs_users
Returns a list of all [access system users](/low-level-apis/access-systems/user-management) assigned to a specified [user identity](/capability-guides/mobile-access/managing-mobile-app-user-accounts-with-user-identities#what-is-a-user-identity).



# The User Identity Object
Source: https://docs.seam.co/api/user_identities/object

Learn how the user_identity object links a person to their application user account so you can manage their mobile credentials and access in Seam.

## The user\_identity Object

Represents a [user identity](/capability-guides/mobile-access/managing-mobile-app-user-accounts-with-user-identities#what-is-a-user-identity) associated with an application user account.

<ResponseExample>
  ```json User Identity theme={null}
  {
    "created_at": "2025-06-16T16:54:17.946546Z",
    "display_name": "Jane Doe",
    "email_address": "jane@example.com",
    "errors": [],
    "full_name": "Jane Doe",
    "phone_number": "+1555551002",
    "user_identity_id": "43947360-cdc8-4db6-8b22-e079416d1d8b",
    "user_identity_key": "jane_doe",
    "acs_user_ids": [
      "0fc82df4-391b-4d00-a234-86378f1c3952"
    ],
    "warnings": [],
    "workspace_id": "b7e0a4e0-1044-4319-9a0b-42b642b68c7f"
  }
  ```
</ResponseExample>

***

## Properties

<ResponseField name="acs_user_ids" type="Array">
  Array of access system user IDs associated with the user identity.
</ResponseField>

<ResponseField name="created_at" type="String (ISO 8601)">
  Date and time at which the user identity was created.
</ResponseField>

<ResponseField name="display_name" type="String">
  Display name for the user identity.
</ResponseField>

<ResponseField name="email_address" type="String">
  Unique email address for the user identity.
</ResponseField>

<ResponseField name="errors" type="Array">
  Array of errors associated with the user identity. Each error object within the array contains fields like "error\_code" and "message." "error\_code" is a string that uniquely identifies the type of error, enabling quick recognition and categorization of the issue. "message" provides a more detailed description of the error, offering insights into the issue and potentially how to rectify it.
</ResponseField>

<ResponseField name="full_name" type="String">
  Full name of the user associated with the user identity.
</ResponseField>

<ResponseField name="phone_number" type="String">
  Unique phone number for the user identity in [E.164 format](https://www.itu.int/rec/T-REC-E.164/en) (for example, +15555550100).
</ResponseField>

<ResponseField name="user_identity_id" type="String (UUID)">
  ID of the user identity.
</ResponseField>

<ResponseField name="user_identity_key" type="String">
  Unique key for the user identity.
</ResponseField>

<ResponseField name="warnings" type="Array">
  Array of warnings associated with the user identity. Each warning object within the array contains two fields: "warning\_code" and "message." "warning\_code" is a string that uniquely identifies the type of warning, enabling quick recognition and categorization of the issue. "message" provides a more detailed description of the warning, offering insights into the issue and potentially how to rectify it.
</ResponseField>

<ResponseField name="workspace_id" type="String (UUID)">
  ID of the workspace that contains the user identity.
</ResponseField>


# Remove an ACS User from a User Identity
Source: https://docs.seam.co/api/user_identities/remove_acs_user

/openapi.json post /user_identities/remove_acs_user
Removes a specified [access system user](/low-level-apis/access-systems/user-management) from a specified [user identity](/capability-guides/mobile-access/managing-mobile-app-user-accounts-with-user-identities#what-is-a-user-identity).



# Revoke Access to a Device from a User Identity
Source: https://docs.seam.co/api/user_identities/revoke_access_to_device

/openapi.json post /user_identities/revoke_access_to_device
Revokes access to a specified [device](/core-concepts/devices) from a specified [user identity](/capability-guides/mobile-access/managing-mobile-app-user-accounts-with-user-identities#what-is-a-user-identity).



# Get an Unmanaged User Identity
Source: https://docs.seam.co/api/user_identities/unmanaged/get

/openapi.json post /user_identities/unmanaged/get
Returns a specified unmanaged [user identity](/capability-guides/mobile-access/managing-mobile-app-user-accounts-with-user-identities#what-is-a-user-identity) (where is_managed = false).



# List Unmanaged User Identities
Source: https://docs.seam.co/api/user_identities/unmanaged/list

/openapi.json post /user_identities/unmanaged/list
Returns a list of all unmanaged [user identities](/capability-guides/mobile-access/managing-mobile-app-user-accounts-with-user-identities#what-is-a-user-identity) (where is_managed = false).



# Update an Unmanaged User Identity
Source: https://docs.seam.co/api/user_identities/unmanaged/update

/openapi.json post /user_identities/unmanaged/update
Updates an unmanaged [user identity](/capability-guides/mobile-access/managing-mobile-app-user-accounts-with-user-identities#what-is-a-user-identity) to make it managed.

This endpoint can only be used to convert unmanaged user identities to managed ones by setting `is_managed` to `true`. It cannot be used to convert managed user identities back to unmanaged.



# Update a User Identity
Source: https://docs.seam.co/api/user_identities/update

/openapi.json post /user_identities/update
Updates a specified [user identity](/capability-guides/mobile-access/managing-mobile-app-user-accounts-with-user-identities#what-is-a-user-identity).



# Create a Webhook
Source: https://docs.seam.co/api/webhooks/create

/openapi.json post /webhooks/create
Creates a new [webhook](/developer-tools/webhooks).



# Delete a Webhook
Source: https://docs.seam.co/api/webhooks/delete

/openapi.json post /webhooks/delete
Deletes a specified [webhook](/developer-tools/webhooks).



# Get a Webhook
Source: https://docs.seam.co/api/webhooks/get

/openapi.json post /webhooks/get
Gets a specified [webhook](/developer-tools/webhooks).



# List Webhooks
Source: https://docs.seam.co/api/webhooks/list

/openapi.json post /webhooks/list
Returns a list of all [webhooks](/developer-tools/webhooks).



# The Webhook Object
Source: https://docs.seam.co/api/webhooks/object

Learn how the webhook object lets you receive event notifications at an endpoint URL you specify, for the set of event types you choose to subscribe to.

## The webhook Object

Represents a [webhook](/developer-tools/webhooks) that enables you to receive notifications of events. When you create a webhook, specify the endpoint URL at which you want to receive events and the set of event types that you want to receive.

<ResponseExample>
  ```json Webhook theme={null}
  {
    "event_types": [
      "device.connected",
      "device.disconnected"
    ],
    "secret": "mySecret",
    "url": "https://example.com/webhook",
    "webhook_id": "ffe5cc3c-f3f4-48e8-b377-6f76c05d09a1"
  }
  ```
</ResponseExample>

***

## Properties

<ResponseField name="event_types" type="Array">
  Types of events that the [webhook](/developer-tools/webhooks) should receive.
</ResponseField>

<ResponseField name="secret" type="String">
  Secret associated with the [webhook](/developer-tools/webhooks).
</ResponseField>

<ResponseField name="url" type="String">
  URL for the [webhook](/developer-tools/webhooks).
</ResponseField>

<ResponseField name="webhook_id" type="String">
  ID of the webhook.
</ResponseField>


# Update a Webhook
Source: https://docs.seam.co/api/webhooks/update

/openapi.json post /webhooks/update
Updates a specified [webhook](/developer-tools/webhooks).



# Create a Workspace
Source: https://docs.seam.co/api/workspaces/create

/openapi.json post /workspaces/create
Creates a new [workspace](/core-concepts/workspaces).



# Get a Workspace
Source: https://docs.seam.co/api/workspaces/get

/openapi.json post /workspaces/get
Returns the [workspace](/core-concepts/workspaces) associated with the authentication value.



# List Workspaces
Source: https://docs.seam.co/api/workspaces/list

/openapi.json post /workspaces/list
Returns a list of [workspaces](/core-concepts/workspaces) associated with the authentication value.



# The Workspace Object
Source: https://docs.seam.co/api/workspaces/object

Learn how the workspace object represents an isolated Seam environment that holds your devices, connected accounts, and resources, with sandbox support.

## The workspace Object

Represents a Seam [workspace](/core-concepts/workspaces). A workspace is a top-level entity that encompasses all other resources below it, such as devices, connected accounts, and Connect Webviews. Seam provides two types of workspaces. A [sandbox workspace](/core-concepts/workspaces#sandbox-workspaces) is a special type of workspace designed for testing code. Sandbox workspaces offer test device accounts and virtual devices that you can connect and control. This ability to work with virtual devices is quite handy because it removes the need to own physical devices from multiple brands. To connect real devices and systems to Seam, use a [production workspace](/core-concepts/workspaces#production-workspaces).

<ResponseExample>
  ```json Production Workspace theme={null}
  {
    "company_name": "Acme",
    "connect_partner_name": "Acme",
    "connect_webview_customization": {
      "inviter_logo_url": "https://connect.getseam.com/internal/images/view?image_id=1de135fa-f0c2-4e57-90d0-6b9a7d090a0c",
      "logo_shape": "circle",
      "primary_button_color": "#232426",
      "primary_button_text_color": "#FFFDE7",
      "success_message": "Your account has been successfully connected to Acme!"
    },
    "is_sandbox": false,
    "is_suspended": false,
    "is_publishable_key_auth_enabled": true,
    "publishable_key": "seam_pk1fGd41X_zKs0ZELRTEc8nWxiBsEXAMPLE",
    "name": "My Production Workspace",
    "organization_id": "8f9c4d2e-1a3b-4c5d-6e7f-8a9b0c1d2e3f",
    "workspace_id": "6a0b6282-6a98-4fef-811e-0904c485ac7a"
  }
  ```

  ```json Sandbox Workspace theme={null}
  {
    "company_name": "Acme",
    "connect_partner_name": "Acme",
    "connect_webview_customization": {
      "inviter_logo_url": "https://connect.getseam.com/internal/images/view?image_id=1de135fa-f0c2-4e57-90d0-6b9a7d090a0c",
      "logo_shape": "circle",
      "primary_button_color": "#232426",
      "primary_button_text_color": "#FFFDE7",
      "success_message": "Your account has been successfully connected to Acme!"
    },
    "is_sandbox": true,
    "is_suspended": false,
    "is_publishable_key_auth_enabled": true,
    "publishable_key": "seam_pk1fGd41X_zKs0ZELRTEc8nWxiBsEXAMPLE",
    "name": "My Sandbox Workspace",
    "organization_id": "8f9c4d2e-1a3b-4c5d-6e7f-8a9b0c1d2e3f",
    "workspace_id": "6a0b6282-6a98-4fef-811e-0904c485ac7a"
  }
  ```

  ```json Workspace theme={null}
  {
    "company_name": "Acme",
    "connect_partner_name": "Acme",
    "connect_webview_customization": {
      "inviter_logo_url": "https://connect.getseam.com/internal/images/view?image_id=1de135fa-f0c2-4e57-90d0-6b9a7d090a0c",
      "logo_shape": "circle",
      "primary_button_color": "#232426",
      "primary_button_text_color": "#FFFDE7",
      "success_message": "Your account has been successfully connected to Acme!"
    },
    "is_sandbox": true,
    "is_suspended": false,
    "is_publishable_key_auth_enabled": true,
    "publishable_key": "seam_pk1fGd41X_zKs0ZELRTEc8nWxiBsEXAMPLE",
    "name": "My Sandbox Workspace",
    "organization_id": null,
    "workspace_id": "6a0b6282-6a98-4fef-811e-0904c485ac7a"
  }
  ```
</ResponseExample>

***

## Properties

<ResponseField name="company_name" type="String">
  Company name associated with the [workspace](/core-concepts/workspaces).
</ResponseField>

<ResponseField name="connect_partner_name" type="String">
  **Deprecated**. Use `company_name` instead.

  The connect partner name.
</ResponseField>

<ResponseField name="connect_webview_customization" type="Object">
  The connect webview customization.

  <Expandable title="properties">
    <ResponseField name="inviter_logo_url" type="String">
      URL of the inviter logo for [Connect Webviews](/core-concepts/connect-webviews) in the workspace. See also [Customize the Look and Feel of Your Connect Webviews](/core-concepts/connect-webviews/customizing-connect-webviews#customize-the-look-and-feel-of-your-connect-webviews).
    </ResponseField>

    <ResponseField name="logo_shape" type="Enum (String)">
      Logo shape for [Connect Webviews](/core-concepts/connect-webviews) in the workspace. See also [Customize the Look and Feel of Your Connect Webviews](/core-concepts/connect-webviews/customizing-connect-webviews#customize-the-look-and-feel-of-your-connect-webviews).
    </ResponseField>

    <ResponseField name="primary_button_color" type="String">
      Primary button color for [Connect Webviews](/core-concepts/connect-webviews) in the workspace. See also [Customize the Look and Feel of Your Connect Webviews](/core-concepts/connect-webviews/customizing-connect-webviews#customize-the-look-and-feel-of-your-connect-webviews).
    </ResponseField>

    <ResponseField name="primary_button_text_color" type="String">
      Primary button text color for [Connect Webviews](/core-concepts/connect-webviews) in the workspace. See also [Customize the Look and Feel of Your Connect Webviews](/core-concepts/connect-webviews/customizing-connect-webviews#customize-the-look-and-feel-of-your-connect-webviews).
    </ResponseField>

    <ResponseField name="success_message" type="String">
      Success message for [Connect Webviews](/core-concepts/connect-webviews) in the workspace. See also [Customize the Look and Feel of Your Connect Webviews](/core-concepts/connect-webviews/customizing-connect-webviews#customize-the-look-and-feel-of-your-connect-webviews).
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="is_publishable_key_auth_enabled" type="Boolean">
  Indicates whether publishable key authentication is enabled for this workspace.
</ResponseField>

<ResponseField name="is_sandbox" type="Boolean">
  Indicates whether the workspace is a [sandbox workspace](/core-concepts/workspaces#sandbox-workspaces).
</ResponseField>

<ResponseField name="is_suspended" type="Boolean">
  Indicates whether the [sandbox workspace](/core-concepts/workspaces#sandbox-workspaces) is suspended. Seam suspends sandbox workspaces that have not been accessed in 14 days.
</ResponseField>

<ResponseField name="name" type="String">
  Name of the [workspace](/core-concepts/workspaces).
</ResponseField>

<ResponseField name="organization_id" type="String (UUID)">
  ID of the organization to which the workspace belongs, or `null` if the workspace is not assigned to an organization.
</ResponseField>

<ResponseField name="publishable_key" type="String">
  Publishable key for the [workspace](/core-concepts/workspaces). This key is used to identify the workspace in client-side applications.
</ResponseField>

<ResponseField name="workspace_id" type="String (UUID)">
  ID of the workspace.
</ResponseField>


# Reset a Sandbox Workspace
Source: https://docs.seam.co/api/workspaces/reset_sandbox

/openapi.json post /workspaces/reset_sandbox
Resets the [sandbox workspace](/core-concepts/workspaces#sandbox-workspaces) associated with the authentication value. Note that this endpoint is only available for sandbox workspaces.



# Update a Workspace
Source: https://docs.seam.co/api/workspaces/update

/openapi.json post /workspaces/update
Updates the [workspace](/core-concepts/workspaces) associated with the authentication value.



# Customers
Source: https://docs.seam.co/capability-guides/customer-portals/customers

Link your customers to Seam with customer_key.

A customer in Seam represents one of your end customers — for example, a hotel operator, property manager, gym owner, or office admin. Customers link the systems and devices they control (via Seam Connect) to your application.

Seam gives you a way to tag each customer with your own identifier through the `customer_key`. This makes it easy to keep Seam’s records aligned with your own database.

***

### What is `customer_key`?

`customer_key` is your unique identifier for a customer. You assign it when creating resources that belong to that customer. Seam then copies the same key to related resources, so you always have a reliable way to look them up.

***

#### Key uses:

* Connect Webviews: Tag a Webview with `customer_key`. When the customer connects their account, the resulting Connected Account inherits that key.
* Customer Portals: Initialize a portal with `customer_key` so the portal shows only the devices, spaces, and accounts for that customer.
* Lookups: Use `customer_key` to fetch all Connected Accounts, devices, or systems associated with a specific customer.

***

### Next step: set up a Customer Portal

Once you’ve defined a customer with `customer_key`, you can set up a Customer Portal to give them self-service access to their systems and devices. In the next section, we’ll walk through how to configure a Customer Portal in the Console and initialize it with your `customer_key`.


# Filtering Portal Resources by Custom Metadata
Source: https://docs.seam.co/capability-guides/customer-portals/filtering-portal-resources-by-custom-metadata

Use customer_resources_filters to control which resources are visible to customers in a portal, based on custom_metadata on property_listings and reservations.

When creating a customer portal, you can use the `customer_resources_filters` parameter to control which resources (property listings, reservations) are visible to the customer. Filters match against the `custom_metadata` you set on resources in `customer_data`.

***

### How It Works

1. **Tag resources with `custom_metadata`** — when passing `property_listings` or `reservations` in `customer_data`, include a `custom_metadata` object with key-value pairs on each resource.
2. **Set `customer_resources_filters` when creating the portal** — provide an array of filter objects that specify which `custom_metadata` values a resource must have to be visible.
3. **Filtering is enforced server-side** — the customer portal only returns resources whose `custom_metadata` matches all specified filters.

***

### Filter Structure Reference

Each filter in the `customer_resources_filters` array is an object with the following fields:

| Field       | Type              | Description                                                                                                                                     |
| ----------- | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `field`     | String            | The `custom_metadata` field name to filter on. Must start with a letter or underscore and contain only alphanumeric characters and underscores. |
| `operation` | String            | The comparison operation. Currently only `"="` (equals) is supported.                                                                           |
| `value`     | String or Boolean | The value to compare against.                                                                                                                   |

***

### Key Behaviors

* **AND logic** — when multiple filters are provided, a resource must match *all* of them to be visible.
* **Exact match** — the `=` operation performs an exact match against the `custom_metadata` value.
* **Server-side enforcement** — filtering happens on the server. The customer portal API only returns matching resources.
* **Field name rules** — field names must match the regex `^[a-zA-Z_]\w*$` (start with a letter or underscore, followed by alphanumeric characters or underscores).

***

### Examples

#### Example 1: Filtering Property Listings by Region

Create property listings with a `region` field in `custom_metadata`, then filter to show only European properties.

<CodeGroup>
  ```javascript JavaScript theme={null}
  const { customer_portal } = await seam.customers.createPortal({
    customer_data: {
      customer_key: 'customer_123',
      property_listings: [
        {
          name: 'Lisbon Apartment',
          property_listing_key: 'lisbon_apt',
          custom_metadata: { region: 'europe' },
        },
        {
          name: 'NYC Loft',
          property_listing_key: 'nyc_loft',
          custom_metadata: { region: 'north_america' },
        },
      ],
    },
    customer_resources_filters: [
      { field: 'region', operation: '=', value: 'europe' },
    ],
  })

  // The portal will only show "Lisbon Apartment"
  console.log(customer_portal.url)
  ```

  ```bash cURL theme={null}
  curl -X POST \
    'https://connect.getseam.com/customers/create_portal' \
    -H 'Authorization: Bearer ${SEAM_API_KEY}' \
    -H 'Content-Type: application/json' \
    -d '{
      "customer_data": {
        "customer_key": "customer_123",
        "property_listings": [
          {
            "name": "Lisbon Apartment",
            "property_listing_key": "lisbon_apt",
            "custom_metadata": { "region": "europe" }
          },
          {
            "name": "NYC Loft",
            "property_listing_key": "nyc_loft",
            "custom_metadata": { "region": "north_america" }
          }
        ]
      },
      "customer_resources_filters": [
        { "field": "region", "operation": "=", "value": "europe" }
      ]
    }'
  ```
</CodeGroup>

#### Example 2: Multiple Filters (AND Logic)

When you provide multiple filters, a resource must match all of them. Here, only property listings that are both premium and in Europe are shown.

<CodeGroup>
  ```javascript JavaScript theme={null}
  const { customer_portal } = await seam.customers.createPortal({
    customer_data: {
      customer_key: 'customer_123',
      property_listings: [
        {
          name: 'Premium Villa',
          property_listing_key: 'premium_villa',
          custom_metadata: { is_premium: true, region: 'europe' },
        },
        {
          name: 'Standard Apartment',
          property_listing_key: 'standard_apt',
          custom_metadata: { is_premium: false, region: 'europe' },
        },
        {
          name: 'Premium Condo',
          property_listing_key: 'premium_condo',
          custom_metadata: { is_premium: true, region: 'north_america' },
        },
      ],
    },
    customer_resources_filters: [
      { field: 'is_premium', operation: '=', value: true },
      { field: 'region', operation: '=', value: 'europe' },
    ],
  })

  // Only "Premium Villa" is visible in the portal
  console.log(customer_portal.url)
  ```

  ```bash cURL theme={null}
  curl -X POST \
    'https://connect.getseam.com/customers/create_portal' \
    -H 'Authorization: Bearer ${SEAM_API_KEY}' \
    -H 'Content-Type: application/json' \
    -d '{
      "customer_data": {
        "customer_key": "customer_123",
        "property_listings": [
          {
            "name": "Premium Villa",
            "property_listing_key": "premium_villa",
            "custom_metadata": { "is_premium": true, "region": "europe" }
          },
          {
            "name": "Standard Apartment",
            "property_listing_key": "standard_apt",
            "custom_metadata": { "is_premium": false, "region": "europe" }
          },
          {
            "name": "Premium Condo",
            "property_listing_key": "premium_condo",
            "custom_metadata": { "is_premium": true, "region": "north_america" }
          }
        ]
      },
      "customer_resources_filters": [
        { "field": "is_premium", "operation": "=", "value": true },
        { "field": "region", "operation": "=", "value": "europe" }
      ]
    }'
  ```
</CodeGroup>

#### Example 3: Boolean Filters

Filter by a boolean `custom_metadata` value, such as showing only premium listings.

<CodeGroup>
  ```javascript JavaScript theme={null}
  const { customer_portal } = await seam.customers.createPortal({
    customer_data: {
      customer_key: 'customer_123',
      property_listings: [
        {
          name: 'Premium Villa',
          property_listing_key: 'premium_villa',
          custom_metadata: { is_premium: true },
        },
        {
          name: 'Standard Apartment',
          property_listing_key: 'standard_apt',
          custom_metadata: { is_premium: false },
        },
      ],
    },
    customer_resources_filters: [
      { field: 'is_premium', operation: '=', value: true },
    ],
  })

  // Only "Premium Villa" is visible
  console.log(customer_portal.url)
  ```

  ```bash cURL theme={null}
  curl -X POST \
    'https://connect.getseam.com/customers/create_portal' \
    -H 'Authorization: Bearer ${SEAM_API_KEY}' \
    -H 'Content-Type: application/json' \
    -d '{
      "customer_data": {
        "customer_key": "customer_123",
        "property_listings": [
          {
            "name": "Premium Villa",
            "property_listing_key": "premium_villa",
            "custom_metadata": { "is_premium": true }
          },
          {
            "name": "Standard Apartment",
            "property_listing_key": "standard_apt",
            "custom_metadata": { "is_premium": false }
          }
        ]
      },
      "customer_resources_filters": [
        { "field": "is_premium", "operation": "=", "value": true }
      ]
    }'
  ```
</CodeGroup>

#### Example 4: Filtering Reservations

Filters also apply to reservations. Here, only reservations that are both premium and in Europe are shown.

<CodeGroup>
  ```javascript JavaScript theme={null}
  const { customer_portal } = await seam.customers.createPortal({
    customer_data: {
      customer_key: 'customer_123',
      property_listings: [
        {
          name: 'Premium Villa',
          property_listing_key: 'premium_villa',
        },
      ],
      reservations: [
        {
          name: 'Premium EU Reservation',
          reservation_key: 'premium_eu_res',
          space_keys: ['premium_villa'],
          custom_metadata: { is_premium: true, region: 'europe' },
        },
        {
          name: 'Standard EU Reservation',
          reservation_key: 'standard_eu_res',
          space_keys: ['premium_villa'],
          custom_metadata: { is_premium: false, region: 'europe' },
        },
        {
          name: 'Premium US Reservation',
          reservation_key: 'premium_us_res',
          space_keys: ['premium_villa'],
          custom_metadata: { is_premium: true, region: 'north_america' },
        },
      ],
    },
    customer_resources_filters: [
      { field: 'is_premium', operation: '=', value: true },
      { field: 'region', operation: '=', value: 'europe' },
    ],
  })

  // Only "Premium EU Reservation" is visible in the portal
  console.log(customer_portal.url)
  ```

  ```bash cURL theme={null}
  curl -X POST \
    'https://connect.getseam.com/customers/create_portal' \
    -H 'Authorization: Bearer ${SEAM_API_KEY}' \
    -H 'Content-Type: application/json' \
    -d '{
      "customer_data": {
        "customer_key": "customer_123",
        "property_listings": [
          {
            "name": "Premium Villa",
            "property_listing_key": "premium_villa"
          }
        ],
        "reservations": [
          {
            "name": "Premium EU Reservation",
            "reservation_key": "premium_eu_res",
            "space_keys": ["premium_villa"],
            "custom_metadata": { "is_premium": true, "region": "europe" }
          },
          {
            "name": "Standard EU Reservation",
            "reservation_key": "standard_eu_res",
            "space_keys": ["premium_villa"],
            "custom_metadata": { "is_premium": false, "region": "europe" }
          },
          {
            "name": "Premium US Reservation",
            "reservation_key": "premium_us_res",
            "space_keys": ["premium_villa"],
            "custom_metadata": { "is_premium": true, "region": "north_america" }
          }
        ]
      },
      "customer_resources_filters": [
        { "field": "is_premium", "operation": "=", "value": true },
        { "field": "region", "operation": "=", "value": "europe" }
      ]
    }'
  ```
</CodeGroup>

***

### Verifying Filters

After creating a portal, you can verify the configured filters by retrieving the portal via the customer API. The response includes `customer_resources_filters` in the portal configuration.

```bash theme={null}
curl -X GET \
  'https://connect.getseam.com/seam/customer/v1/portals/get?customer_portal_id=PORTAL_ID' \
  -H 'Authorization: Bearer ${API_KEY}' \
  -H 'Content-Type: application/json'
```

The response will include the filters you configured:

```json theme={null}
{
  "customer_portal": {
    "customer_resources_filters": [
      { "field": "is_premium", "operation": "=", "value": true }
    ]
  }
}
```


# Customer Portals
Source: https://docs.seam.co/capability-guides/customer-portals/index

Allow your customers to manage their own devices and systems.

<img alt="" />

Provide self-service functions to your customers by setting up a customer portal. You can configure it entirely in the Console, or use our API to automate generating the portal.

You can extend the portal experience with [Seam access and climate automations](../reservation-automations). When a customer books a stay, reserves a gym slot, or schedules a visit, automations automatically issue and revoke access or adjust climate settings. You create and manage them in the Console.

### Get started with the customer portal

<CardGroup>
  <Card title="Preview customer portal in ConsoleTry out Customer Portals in the Console. Links here expire after 7 days." href="/capability-guides/customer-portals/preview-the-customer-portal-in-console" />

  <Card title="Integrate customer portal into your applicationGenerate Customer Portals programmatically for production use." href="/capability-guides/customer-portals/integrate-customer-portal-into-your-application" />
</CardGroup>

***

### Customer portal features

A customer portal allows your customers to self-manage connecting devices, manage their devices, and handle day-to-day management in one place.

<table>
  <thead>
    <tr>
      <th>Feature</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Customer management</td>

      <td>
        <p>
          Offer your customers a self-serve method to:

          <br />

          <i>:hyphen:</i> Connect existing smart lock,
          thermostat, or access control accounts

          <br />

          <i>:hyphen:</i> Organize devices to match their
          property structure

          <br />

          <i>:hyphen:</i> Manage and troubleshoot their
          devices
        </p>

        <p>
          <i>:hyphen:</i> Control Access or Climate features
          that you’ve configured for them.
        </p>
      </td>
    </tr>

    <tr>
      <td>Interoperability</td>

      <td>
        Works seamlessly with other Seam products, including Access and Climate.
      </td>
    </tr>

    <tr>
      <td>Customized branding</td>

      <td>
        Configure the portal with your branding, including your logo, colors,
        and business information.
      </td>
    </tr>

    <tr>
      <td>Ephemeral sessions</td>

      <td>
        Portal sessions are temporary. New portal sessions expire after 7 days
        period. They should be regenerated every time a customer needs to access
        the portal, whether from a new browser, a new device, or after the
        previous session has expired.
      </td>
    </tr>
  </tbody>
</table>

***


# Integrate customer portal into your application
Source: https://docs.seam.co/capability-guides/customer-portals/integrate-customer-portal-into-your-application

Generate Customer Portals programmatically with the create_portal endpoint, or grab a ready-made code snippet from the Seam Console.

Use the `create_portal` endpoint to generate Customer Portals programmatically.

***

**Grab a ready-made snippet from Console**

1. Go to **Developer** → **Customer Portals**.

2. Configure the portal (features, embedded, landing page) and enter your `customer_key` (and Spaces, if using Organize).

3. In Generate Portal → **Create Portal Programmatically**, open the code panel.

   <img alt="" />

4. Copy the prefilled request (cURL). Replace placeholders like the Seam API key.

   ```bash theme={null}
   curl -X POST \
     https://connect.getseam.com/customers/create_portal \
     -H "Authorization: Bearer $SEAM_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
     "is_embedded": false,
     "features": {
       "connect": { "exclude": false },
       "organize": { "exclude": false },
       "manage_devices": { "exclude": false }
     },
     "customer_data": {
       "customer_key": "sample_customer_key",
       "property_listings": [
       {
         "name": "Property 1",
         "property_listing_key": "property_1_id"
       }
     ]
     }
   }'
   ```

5. Send the request from your app or API client.

***

**Notes**

* Customize features: All features are enabled by default; set `"exclude": true` to turn any off.
* Embedded or standalone: Set `"is_embedded": true` to embed in an iframe; otherwise it’s standalone.
* Scope by customer: `customer_key` ties the portal to a single customer in your system.
* Use your own IDs: Use `space_key` values that match your internal identifiers.
* Session lifetime: All portal links expire after 7 days. Generate a new portal programmatically each time a customer needs access.

***

## Embedding the Customer Portal as an iFrame

The Seam Customer Portal is a hosted, pre-authenticated interface for managing devices, access codes, reservations, and more. Instead of sharing a magic link with your end-users, you can embed the portal directly inside your own application using an iFrame. This gives your users a seamless experience without leaving your product.

### How it works

When you create a customer portal via the API, Seam returns a `customer_portal` URL. This URL can be loaded in a standard HTML `<iframe>`. The portal is fully authenticated through a token embedded in the URL — no additional login is required from the end-user.

Portal links expire after **7 days**. Your backend should generate a fresh link when rendering the page, or when the current link is close to expiring.

### Step 1: Create a portal with `is_embedded: true`

Call the `/customers/create_portal` endpoint from your backend with the `is_embedded` flag set to `true`. This tells the portal to render in a layout optimized for iFrame embedding (no unnecessary navigation that would conflict with your app's own UI).

```bash theme={null}
curl -X POST https://connect.getseam.com/customers/create_portal \
  -H "Authorization: Bearer ${SEAM_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_data": {
      "customer_key": "my-customer-123",
      "spaces": [
        {
          "name": "123 Main Street",
          "space_key": "property-123"
        }
      ]
    },
    "is_embedded": true,
    "features": {
      "connect": { "exclude": false },
      "manage": {
        "exclude": false,
        "exclude_reservation_management": false,
        "exclude_staff_management": true
      },
      "organize": { "exclude": true },
      "configure": { "exclude": true }
    }
  }'
```

The response includes a `customer_portal` object:

```json theme={null}
{
  "customer_portal": {
    "url": "https://partner-ui.seam.vc/portals/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee?token=seam_cst_...",
    "customer_key": "my-customer-123",
    "expires_at": "2026-03-25T12:00:00.000Z",
    "workspace_id": "...",
    "created_at": "2026-03-18T12:00:00.000Z"
  }
}
```

### Step 2: Embed the URL in an iFrame

Use the `customer_portal.url` as the `src` attribute of an iFrame in your frontend. The portal handles authentication automatically via the token in the URL.

```html theme={null}
<iframe
  src="https://partner-ui.seam.vc/portals/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee?token=seam_cst_..."
  width="100%"
  height="800"
  frameborder="0"
  allow="clipboard-write"
  style="border: none; border-radius: 8px;"
></iframe>
```

In practice, your backend generates the `customer_portal.url` and passes it to your frontend, which sets it as the iFrame `src`. Don't hardcode the URL — it contains a session token that expires.

### Step 3: Refresh the link before it expires

Portal links are valid for 7 days. If your user keeps a page open for a long time, the embedded portal will eventually expire. Handle this by:

1. **Generating a fresh link on each page load.** This is the simplest approach. Each time your user navigates to the page containing the portal, your backend calls `/customers/create_portal` and returns a new URL.
2. **Tracking expiration client-side.** Store the `expires_at` timestamp and proactively refresh the iFrame `src` before it expires.

You can also use the `/customers/open_portal` endpoint, which reuses an existing portal session if it hasn't expired yet, and creates a new one if it has.

### Configuring which features are visible

The `features` object in the request body controls which sections of the portal your customer sees. Each feature can be included or excluded:

| Feature          | What it controls                                                            |
| ---------------- | --------------------------------------------------------------------------- |
| `connect`        | Connecting new device accounts (e.g., linking an August or Schlage account) |
| `manage`         | Managing reservations and staff for properties                              |
| `organize`       | Organizing devices into spaces and groups                                   |
| `configure`      | Configuring automation rules for access, climate, and Instant Key           |
| `manage_devices` | Legacy device management (use `manage` instead)                             |

For example, if your product only needs reservation management, you can exclude everything else:

```json theme={null}
{
  "features": {
    "connect": { "exclude": true },
    "manage": {
      "exclude": false,
      "exclude_reservation_management": false,
      "exclude_staff_management": true
    },
    "organize": { "exclude": true },
    "configure": { "exclude": true }
  }
}
```

### Embedding a single reservation view (deep links)

If you want to embed a portal that shows a single reservation — for example, inside a reservation detail page in your PMS — use the `/customers/reservations/create_deep_link` endpoint instead.

```bash theme={null}
curl -X POST https://connect.getseam.com/customers/reservations/create_deep_link \
  -H "Authorization: Bearer ${SEAM_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_key": "my-customer-123",
    "reservation_key": "res-456"
  }'
```

This returns a `deep_link.url` that you embed the same way. The portal navigates directly to the reservation page with the navigation UI hidden, so it feels like a native part of your application. Deep links automatically set `is_embedded: true` and `navigation_mode: "restricted"`.

### Localization

Set the `locale` parameter when creating the portal to display it in a different language:

* `en-US` (default)
* `pt-PT` — Portuguese
* `fr-FR` — French
* `it-IT` — Italian
* `es-ES` — Spanish

```json theme={null}
{
  "is_embedded": true,
  "locale": "fr-FR",
  "customer_data": { "..." }
}
```

### Branding and customization

If you have a customization profile set up, pass the `customization_profile_id` when creating the portal to apply it.

```json theme={null}
{
  "is_embedded": true,
  "customization_profile_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
  "customer_data": { "..." }
}
```

A customization profile controls two things:

* **Visual branding** — colors, logos, and fonts.
* **Labels and terminology** — the wording the portal uses, so it matches what your own product calls things.

You configure profiles in [Seam Console](https://console.seam.co) under **Developer > Customization Profiles**.

### Customizing labels and terminology

Your users may not think of a rental unit as a "space" or a booking as a "reservation." A customization profile lets you override the portal's wording so the embedded portal reads like part of your product rather than like Seam.

For example, you might rename **Space** to **Studio**, or **Reservation** to **Booking**. Overrides are set per language, and any string you leave alone keeps Seam's default wording — so you can rename a handful of terms without translating the whole portal.

Strings are organized into namespaces, addressed as `Namespace.key`:

| Namespace           | Covers                                                                       |
| ------------------- | ---------------------------------------------------------------------------- |
| `Common`            | Shared UI text: buttons, states, and prompts such as **Save** and **Search** |
| `Navigation`        | Nav labels such as **Connect** and **Settings**                              |
| `ConnectedAccounts` | Account connection, disconnection, and reconnection copy                     |
| `Spaces`            | Spaces, properties, rooms, facilities, and their setup flows                 |
| `Devices`           | Device lists, details, capabilities, and status                              |
| `AccessCodes`       | Access code management                                                       |
| `AccessGrants`      | Access grants                                                                |
| `Reservations`      | Reservations                                                                 |
| `StaffMembers`      | Staff member management                                                      |
| `Settings`          | Portal settings                                                              |
| `Thermostat`        | Thermostat controls                                                          |
| `Events`            | Activity and event history                                                   |
| `Errors`            | Error messages                                                               |
| `DeviceIssues`      | Device issue descriptions                                                    |

<Info>
  Overrides fall back gracefully. Any key you do not override — and any override
  you leave blank — uses Seam's built-in wording for that language, so a partial
  set of overrides is perfectly valid and a blank field never blanks out portal
  copy.
</Info>

Labels can be customized in each language the portal supports: English, Português, Español, Italiano, Français, Deutsch, Nederlands, Ελληνικά, Polski, and Русский. Pair this with the [`locale`](#localization) parameter to control which language a given portal session renders in.

### Frequently asked questions

**Do I need to set any special headers or CSP rules on my side?** No. The portal is designed to be embedded and does not set `frame-ancestors` restrictions. As long as your own site doesn't block iFrames in its Content Security Policy, it will work out of the box.

**Can my user interact with the portal inside the iFrame?** Yes. The portal is fully interactive — users can connect accounts, view device status, manage reservations, copy access codes, and everything else the portal supports. Adding `allow="clipboard-write"` to your iFrame tag enables the copy-to-clipboard functionality for access codes.

**What happens when the portal link expires?** The portal will show an error state. Your application should detect this (either by tracking the `expires_at` timestamp or by listening for a page error in the iFrame) and generate a fresh link.

**Can I scope the portal to specific properties or devices?** Yes. Pass `customer_resources_filters` when creating the portal to filter which resources are visible based on their `custom_metadata`. For example, you could show only properties in a specific region or managed by a specific team.

```json theme={null}
{
  "customer_resources_filters": [
    { "field": "region", "operation": "=", "value": "us-west" }
  ]
}
```


# Preview the customer portal in Console
Source: https://docs.seam.co/capability-guides/customer-portals/preview-the-customer-portal-in-console

Preview how Customer Portals work and experiment with the API by setting up a temporary portal directly from the Seam Console.

You can set up a customer portal directly from the Seam Console. These Console-generated portals are intended as an **API exploration playground** — they let you preview how portals work and experiment with the API before building your integration.

<Warning>
  **Important:** Portal links created in Console are temporary. They expire
  after 7 days and should not be used in production. For real-world usage,
  always generate portals programmatically using the API.
</Warning>

***

### 1. Open the Customer Portals page

From the Console, navigate to **Developer** → **Customer Portals** from the top navigation bar.

<img alt="" />

***

### 2. Select your business verticals

Choose the vertical that best matches your product (for example, *Short Term Rental*). This setting does two things:

1. Preconfigures recommended defaults for your use case.
2. Updates the labels in the portal UI so they use industry-specific terms your customers expect.

For example:

* In the Hospitality vertical, the generic Seam concept of a *Space* appears in the portal as a *Room*.
* In Multi-family, *Spaces* appear as *Units*.
* In Gym Management, they appear as *Facilities*.

<img
  alt="Example: In the Hospitality vertical, Spaces are shown as “Rooms” in the
portal UI."
/>

Here's a complete reference of how Seam concepts map to industry-specific labels across verticals:

| Vertical              | User Identity | Spaces              | Bookings     |
| --------------------- | ------------- | ------------------- | ------------ |
| **Short Term Rental** | Guest         | Property listings   | Reservations |
| **Multi-family**      | Tenant        | Units, Common areas | Leases       |
| **Hospitality**       | Guest         | Rooms, Common areas | Bookings     |
| **Gym Management**    | Member        | Facilities          | Memberships  |
| **Property Tours**    | Visitor       | Tour spaces         | Bookings     |
| **Neutral**           | User Identity | Spaces              | Bookings     |

***

### 3. Configure portal features

Under **Portal Configuration**, select which features to enable:

* **Connect** – allow customers to connect their device accounts.
* **Organize** – let customers map devices to rental units, rooms, or spaces.
* **Manage Devices** – give customers tools to manage devices, troubleshoot, and view logs.
* **Configure** – allow customers to set automation rules and customize Instant Key branding.

<img alt="" />

***

### 4. Enter your `customer_key`

Add the customer\_key for the customer this portal belongs to. Seam uses this key to scope the portal to only that customer’s devices and accounts.

<img alt="" />

***

### 5. (Optional) Set up Spaces

This step is required only if you enable the Organize feature.

* Spaces represent the real-world units your customer manages—for example, *Room 101* in a hotel, *Unit A* in an apartment building, or *Studio 3* in a gym.
* Create a Space for each unit your customer manages.
* Use a `space_key` that matches your own system’s identifier (for example, `room-101-id`).

<Info>
  **Reminder:** Even if the portal shows “Rooms” or “Units,” these all map back
  to Spaces in Seam.
</Info>

<img alt="" />

***

### 6. Generate the portal

Click **Create Portal**. Seam generates a temporary portal URL you can use to preview the portal.

<Warning>
  **Note:** All portal links expire after 7 days. For production, always
  generate portals programmatically, each time a customer needs access.
</Warning>

<img alt="" />

***

### Next step: Generate portals programmatically with the API

In production, portals must be generated with the API so that they can be refreshed whenever a customer needs access. On the next page, we’ll cover how to create portals programmatically using the `create_portal` endpoint.


# Device and System Capabilities
Source: https://docs.seam.co/capability-guides/device-and-system-capabilities

Learn about device and system capabilities, as well as capability flags.

<img alt="In the Seam API, capability flags inform your application about what features and behaviors each device supports." />

Each device that you connect to Seam has a specific set of capabilities. These capabilities define the Seam API actions that you can use. For example, some devices support [remote unlock actions](../low-level-apis/smart-locks/lock-and-unlock), while others support [programming access codes](/low-level-apis/smart-locks/access-codes/index). Some devices support both of these capabilities. When developing your application, it is imperative to be able to identify the capabilities of each device.

For example, if a device supports programming online access codes, your app can present the [`CreateAccessCodeForm` Seam Component](../ui-components/overview/react-components/create-access-code-form) to your user. On the other hand, if a connected device does not support the remote unlock action, you'll likely want to disable or not display the unlock functionality for your app user.

## Capability Flags

Capability flags inform your application about what features and behaviors each device supports. That is, you can use capability flags to match devices to the requirements for operations within your app. These flags also compare the capabilities of a specific device instance with those of the device model in general.

<img
  alt="Capability flags help you to understand which actions a device can
perform."
/>

All capability flags share the following behavior:

* If `true`, the device has this capability, and this capability is functional on this device instance.

* If `false`, the device has this capability, but the capability is not currently functional.

  See the device [errors and warnings](/api/devices/errors) for more details about the cause of this issue. You can also examine the [properties](/api/devices/object) of the device and [events](/api/devices/events) related to the device to learn more about the cause of this issue.

* If not present, the device does not have this capability.

Reasons why a capability flag might be `false` could include that a required hardware accessory is not connected to the device. For example, if a lock needs a Wi-Fi bridge for connectivity and is currently not connected to a bridge, the lock cannot be remotely unlocked. If a lock is missing an accessory keypad, access codes cannot be programmed on the lock.

With respect to the ability to program online access codes, as long as a lock has the required hardware, Seam assumes that any offline status is temporary and will be resolved before [it's time to set the access code on the device](../low-level-apis/smart-locks/access-codes/lifecycle-of-access-codes). Consequently, in this case, Seam maintains `can_program_online_access_codes` as `true`.

<img
  alt="Capability flags help you to understand why a device cannot currently
perform an action."
/>

Seam recommends adding capability checks before performing specific actions in your app. For example, before performing a [remote unlock](../low-level-apis/smart-locks/lock-and-unlock#unlocking-a-door) operation, you can check to make sure that the target device supports remote unlocking. For details and code samples, see the corresponding capability guides.

<Info>
  In addition to viewing the capabilities for a specific device, you can also
  view the capabilities for a provider using [List Device
  Providers](/api/devices/list_device_providers). If
  at least one supported device from a provider has a specific capability, the
  corresponding capability flag is `true`.
</Info>

<table>
  <thead>
    <tr>
      <th>Property</th>
      <th>Type</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        <code>device.can\_remotely\_unlock</code>
      </td>

      <td>
        Boolean

        <br />

        <em>Optional</em>
      </td>

      <td>
        Indicates whether the device can perform a

        <a href="/low-level-apis/smart-locks/lock-and-unlock">
          remote unlock operation
        </a>

        .
      </td>
    </tr>

    <tr>
      <td>
        <code>device.can\_remotely\_lock</code>
      </td>

      <td>
        Boolean

        <br />

        <em>Optional</em>
      </td>

      <td>
        Indicates whether the device can perform a

        <a href="/low-level-apis/smart-locks/lock-and-unlock">
          remote lock operation
        </a>

        .
      </td>
    </tr>

    <tr>
      <td>
        <code>device.can\_program\_online\_access\_codes</code>
      </td>

      <td>
        Boolean

        <br />

        <em>Optional</em>
      </td>

      <td>
        Indicates whether the device can

        <a href="/low-level-apis/smart-locks/access-codes">
          program online access codes
        </a>

        .<br />
        If <code>true</code>, it is currently possible to create new online
        access codes for the device, and Seam programs the device the next time
        it's online.
      </td>
    </tr>

    <tr>
      <td>
        <code>device.can\_program\_offline\_access\_codes</code>
      </td>

      <td>
        Boolean

        <br />

        <em>Optional</em>
      </td>

      <td>
        Indicates whether the device can

        <a href="/low-level-apis/smart-locks/access-codes/offline-access-codes">
          program offline access codes
        </a>

        .<br />
        When this flag is <code>true</code>, Seam can generate an offline code
        for this device, regardless of the current online status of the device.
      </td>
    </tr>

    <tr>
      <td>
        <code>device.can\_hvac\_heat</code>
      </td>

      <td>
        Boolean

        <br />

        <em>Optional</em>
      </td>

      <td>
        Indicates whether the thermostat device (in conjunction with the
        associated HVAC system) supports

        <a href="/capability-guides/thermostats/understanding-thermostat-concepts/hvac-mode">
          heat mode
        </a>

        .<br />
        When this flag is <code>true</code>, you can

        <a href="../capability-guides/thermostats/configure-current-climate-settings#set-a-thermostat-to-heat-mode">
          set the thermostat to heat mode
        </a>

        .
      </td>
    </tr>

    <tr>
      <td>
        <code>device.can\_hvac\_cool</code>
      </td>

      <td>
        Boolean

        <br />

        <em>Optional</em>
      </td>

      <td>
        Indicates whether the thermostat device (in conjunction with the
        associated HVAC system) supports

        <a href="/capability-guides/thermostats/understanding-thermostat-concepts/hvac-mode">
          cool mode
        </a>

        .<br />
        When this flag is <code>true</code>, you can

        <a href="../capability-guides/thermostats/configure-current-climate-settings#set-a-thermostat-to-cool-mode">
          set the thermostat to cool mode
        </a>

        .
      </td>
    </tr>

    <tr>
      <td>
        <code>device.can\_hvac\_heat\_cool</code>
      </td>

      <td>
        Boolean

        <br />

        <em>Optional</em>
      </td>

      <td>
        Indicates whether the thermostat device (in conjunction with the
        associated HVAC system) supports

        <a href="/capability-guides/thermostats/understanding-thermostat-concepts/hvac-mode">
          heat-cool (auto) mode
        </a>

        .<br />
        When this flag is <code>true</code>, you can

        <a href="../capability-guides/thermostats/configure-current-climate-settings#set-a-thermostat-to-heat-cool-mode">
          set the thermostat to heat-cool mode
        </a>

        .
      </td>
    </tr>

    <tr>
      <td>
        <code>device.can\_turn\_off\_hvac</code>
      </td>

      <td>
        Boolean

        <br />

        <em>Optional</em>
      </td>

      <td>
        Indicates whether the thermostat device (in conjunction with the
        associated HVAC system) supports

        <a href="/capability-guides/thermostats/understanding-thermostat-concepts/hvac-mode">
          off mode
        </a>

        .<br />
        When this flag is <code>true</code>, you can

        <a href="../capability-guides/thermostats/configure-current-climate-settings#turn-off-heating-and-cooling">
          set the thermostat to "off" mode
        </a>

        , which turns off both the heating and cooling systems for the space.
      </td>
    </tr>
  </tbody>
</table>

<Info>
  Seam is actively developing additional capability flags to provide you with
  even more robust capability checking abilities for your app. If you would like
  us to add a specific capability flag, contact
  [support@seam.co](mailto:support@seam.co).
</Info>

***

## Next Steps

To learn about the actions that you can perform using the Seam API, see the Seam capability guides. These guides provide helpful tutorials and code samples, categorized by capability types.

* [Smart locks](/low-level-apis/smart-locks/index), including [locking/unlocking](../low-level-apis/smart-locks/lock-and-unlock) and [managing access codes](/low-level-apis/smart-locks/access-codes/index)
* [Access control systems](/low-level-apis/access-systems/index)
* [Thermostats](/capability-guides/thermostats/index)
* [Noise sensors](/capability-guides/noise-sensors/index)
* [Mobile access](/capability-guides/mobile-access/index)
* [Seam Bridge](/capability-guides/seam-bridge)


# Developing in a Sandbox Workspace
Source: https://docs.seam.co/capability-guides/mobile-access/developing-in-a-sandbox-workspace

Develop and test mobile key integrations without real hardware by using a Seam sandbox workspace and simulated phones for user identities.

Seam's sandbox workspaces enable you to develop integrations without access to a real system. Use your sandbox workspace to test out issuing mobile keys and other related aspects of your integration.

## Creating a Simulated Phone for a User Identity

When issuing mobile credentials, some systems require the user identity to have a provisioned phone. While you are developing and testing your integration, you can add a simulated phone in your sandbox workspace. Use the following flow to [add a simulated phone](/api/phones/simulate/create_sandbox_phone) for a user identity:

**Command:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  // Step 1: Create the user identity.
  const userIdentity = await seam.userIdentities.create({
    user_identity_key: 'jean_doe',
    full_name: 'Jean Doe',
  })

  // Step 2: Create a simulated, sandbox phone.
  await seam.phones.simulate.createSandboxPhone({
    user_identity_id: userIdentity.user_identity_id,
  })
  ```

  ```bash cURL theme={null}
  # Step 1: Create the user identity.
  user_identity=$(curl -X 'POST' \
    'https://connect.getseam.com/user_identities/create' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d '{
    "user_identity_key": "jean_doe",
    "full_name": "Jean Doe"
  }')

  # Step 2: Create a simulated, sandbox phone.
  curl -X 'POST' \
    'https://connect.getseam.com/phones/simulate/create_sandbox_phone' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d "{
    \"user_identity_id\": \"$(jq -r '.user_identity.user_identity_id' <<< ${user_identity})\"
  }"
  ```

  ```python Python theme={null}
  # Step 1: Create the user identity.
  user_identity = seam.user_identities.create(
    user_identity_key = "jean_doe",
    full_name = "Jean Doe"
  )

  # Step 2: Create a simulated, sandbox phone.
  seam.phones.simulate.create_sandbox_phone(
    user_identity_id = user_identity.user_identity_id
  )
  ```

  ```ruby Ruby theme={null}
  # Step 1: Create the user identity.
  user_identity = seam.user_identities.create(
    user_identity_key: "jean_doe",
    full_name: "Jean Doe",
  )

  # Step 2: Create a simulated, sandbox phone.
  seam.phones.simulate.create_sandbox_phone(
    user_identity_id: user_identity.user_identity_id,
  )
  ```

  ```php PHP theme={null}
  // Step 1: Create the user identity.
  $seam->user_identities->create(
    user_identity_key: "jean_doe",
    full_name: "Jean Doe"
  );

  // Step 2: Create a simulated, sandbox phone.
  $seam->phones->simulate->create_sandbox_phone(
    user_identity_id: $user_identity->user_identity_id
  );
  ```

  ```csharp C# theme={null}
  Coming soon!
  ```
</CodeGroup>

**Output:**

<CodeGroup>
  ```json JavaScript theme={null}
  {
    "user_identity_id": "22222222-2222-2222-2222-222222222222",
    "full_name": "Jean Doe",
    ...
  }

  {
    "device_id": "22222222-2222-2222-2222-444444444444",
    "device_type": "android_phone",
    "created_at": "2025-01-01T10:40:00+00:00",
    ...
  }
  ```

  ```json cURL theme={null}
  {
    "user_identity": {
      "user_identity_id": "22222222-2222-2222-2222-222222222222",
      "full_name": "Jean Doe",
      ...
    },
    "ok": true
  }

  {
    "phone": {
      "device_id": "22222222-2222-2222-2222-444444444444",
      "device_type": "android_phone",
      "created_at": "2025-01-01T10:40:00+00:00",
      ...
    },
    "ok": true
  }
  ```

  ```json Python theme={null}
  UserIdentity(
    user_identity_id='22222222-2222-2222-2222-222222222222',
    user_identity_key='jean_doe',
    full_name='Jean Doe',
    ...
  )

  Phone(
    device_id='22222222-2222-2222-2222-444444444444',
    device_type='android_phone',
    created_at='2025-01-01T10:40:00+00:00',
    ...
  )
  ```

  ```json Ruby theme={null}
  <Seam::Resources::UserIdentity:0x005f0
    user_identity_id="22222222-2222-2222-2222-222222222222"
    full_name="Jean Doe"
    ...
  >

  <Seam::Resources::Phone:0x005f0
    device_id="22222222-2222-2222-2222-444444444444"
    device_type="android_phone"
    created_at="2025-01-01T10:40:00+00:00"
    ...
  >
  ```

  ```json PHP theme={null}
  {
    "user_identity_id": "22222222-2222-2222-2222-222222222222",
    "full_name": "Jean Doe",
    ...
  }

  {
    "device_id": "22222222-2222-2222-2222-444444444444",
    "device_type": "android_phone",
    "created_at": "2025-01-01T10:40:00+00:00",
    ...
  }
  ```

  ```json C# theme={null}
  Coming soon!
  ```
</CodeGroup>


# Mobile Access
Source: https://docs.seam.co/capability-guides/mobile-access/index

Use Seam to issue mobile credentials across a wide variety of access platforms.

<img
  alt="Seam SDK lets you unlock doors using BLE and NFC credentials across a wide
variety of access platforms"
/>

## Managing Mobile Credentials

Mobile access is the use of a mobile device, such as a smartphone, tablet, or wearable, to gain access to secured doors, gates, services, and more. This functionality is incorporated in [access control systems](/low-level-apis/access-systems/index) (ACSs) of diverse types and levels of complexity.

The Seam mobile access solution makes it easy to issue and retrieve mobile credentials across a wide variety of access control systems. This guide provides an overview of these basic operations and introduces the basic terminology related to mobile access.&#x20;

***

## Applicable Lock and Access Platforms

The Seam mobile access solution is primarily focused on electronic locks and access hardware that support Bluetooth® or near-field communication (NFC) wireless technology. These groups of devices include a vast array of modern electronic door locks, turnstiles, and gate systems. Before implementation, it is important to verify that the existing hardware can communicate with smartphones through one of these wireless technologies.\
If you aim to enable mobile access with Wi-Fi or Z-Wave locks, see [Smart Locks](/low-level-apis/smart-locks/index). This section describes API endpoints that you can use directly in your mobile application.

***

## Mobile Credential Process

The following process describes how mobile credentials work:

1. **Installation of an app**\
   First, users download a specialized app onto their smartphones. Your team can develop this app, or you can use the Seam Passport app.

2. **Credential assignment**

   Credentials are then issued to the user's app account. This process also links their specific account to their unique user profile in the access control system.

3. **Bluetooth or NFC technology**

   The smartphone communicates with the access control system using either Bluetooth or NFC. These technologies enable the phone to communicate with a reader installed at the access point.

4. **Authentication**

   When a user approaches an access point, such as a door or gate, they use the app to signal their intent to enter. The app communicates with the reader to authenticate the user's credentials. This signaling can occur by the user tapping a button in the app, by the user using a gesture, or even automatically when the phone comes into range, depending on the configuration of the system.

5. **Access granted or denied**

   The access control system verifies the credentials and either grants access (by unlocking the door or gate) or denies it. The system can also record the access event, noting the time and the identity of the user.

***

## Use Cases

Use the Seam API and Mobile SDK for the following tasks:

* **Issue and distribute mobile credentials across many platforms.**

  The Seam API is compatible with many access control systems. The Mobile SDK also supports multiple mobile technologies, like Bluetooth low energy (BLE), NFC, and Apple Wallet.

* **Automatically provision new phones and issue credentials.**\
  When a user signs into their account on a new phone, Seam automatically provisions the device and issues the necessary credentials. It also ensures that the mobile credentials are synced to the access control system.


# Issuing Mobile Credentials from an Access Control System
Source: https://docs.seam.co/capability-guides/mobile-access/issuing-mobile-credentials-from-an-access-control-system

Learn how to create mobile credentials across a user's multiple phones.

## Overview

A credential manager, such as HID Origo Mobile Identities, is a cloud-based service responsible for issuing [mobile credentials](/capability-guides/mobile-access/issuing-mobile-credentials-from-an-access-control-system) and keeping track of which mobile credentials have been issued to which phones. Enrolling the phone with the credential manager is a prerequisite for issuing mobile credentials. Seam performs this registration automatically and detects when new phones come online for a [user identity](/capability-guides/mobile-access/managing-mobile-app-user-accounts-with-user-identities#what-is-a-user-identity).

Typically, without Seam, you would have to wait for a phone to complete enrollment before you could start sending credentials. Seam, however, simplifies this process by enabling you to preconfigure the mobile credential details. As soon as a new phone is enrolled successfully, Seam automatically issues the designated mobile credential to it.

Because a user might have multiple phones, when you create a mobile credential, you must use a [multi-phone sync credential](#what-are-multi-phone-sync-credentials) to guarantee that the user has access across all their phones.

***

## What Are Multi-Phone Sync Credentials?

When issuing mobile credentials for a mobile app user, it is necessary to issue a multi-phone sync credential. As [Managing Phones for a User Identity](/capability-guides/mobile-access/managing-phones-for-a-user-identity) describes, a user identity (that is, a mobile app user) may possess multiple phones. To guarantee access across all of the phones for the user identity, the multi-phone sync credential manages the distribution of credentials to each phone linked to the user identity. The multi-phone sync credential also imports the credentials into the ACS and allocates them to the corresponding ACS user.

<img alt="The multi-phone sync credential creates one credential per phone for the user identity." />

***

## Issuing Multi-Phone Sync Credentials

To issue mobile credentials, you must configure a multi-phone sync credential. This type of credential automatically replicates itself when the app user logs in on a new phone. To configure a multi-phone sync credential, include the ID of the ACS user, set `is_multi_phone_sync_credential` to `true`, and include the card details that should be shared across these credentials.

Seam configures the card details that you include in the request across all the credentials that it creates for each phone. Include only common card details, such as the [facility code](https://www.idwholesaler.com/learning-center/26-bit-proximity-card/), and omit any unique card details, such as the card number. For more information about specific card properties, see the user guide for the access control system or credential manager.

<Info>
  The code samples in this section contain manufacturer-specific metadata that
  may vary by ACS. For details, see the [system integration
  guide](/device-and-system-integration-guides#access-control-systems)
  for your ACS.
</Info>

**Command:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  await seam.acs.credentials.create({
    is_multi_phone_sync_credential: true,
    acs_user_id: "33333333-3333-3333-3333-333333333333",
    access_method: "mobile_key",
    credential_manager_acs_system_id: "88888888-8888-8888-8888-888888888888",
    // ACS manufacturer-specific properties
    visionline_metadata: {
      "cardFormat": "rfid48",
      "label": "%ROOMNUM% - %SITENAME%",
      "override": true
    },
    ...
  });
  ```

  ```bash cURL theme={null}
  # Note the manufacturer-specific visionline_metadata in this request.
  curl -X 'POST' \
    'https://connect.getseam.com/acs/credentials/create' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${API_KEY}" \
    -H 'Content-Type: application/json' \
    -d '{
    "is_multi_phone_sync_credential": true,
    "acs_user_id": "33333333-3333-3333-3333-333333333333",
    "access_method": "mobile_key",
    "credential_manager_acs_system_id": "88888888-8888-8888-8888-888888888888",
    "visionline_metadata": {
      "cardFormat": "rfid48",
      "label": "%ROOMNUM% - %SITENAME%",
      "override": true
    },
    ...
  }'
  ```

  ```python Python theme={null}
  seam.acs.credentials.create(
    is_multi_phone_sync_credential=True,
    acs_user_id="33333333-3333-3333-3333-333333333333",
    access_method="mobile_key",
    credential_manager_acs_system_id="88888888-8888-8888-8888-888888888888",
    # ACS manufacturer-specific properties
    visionline_metadata={
      "cardFormat": "rfid48",
      "label": "%ROOMNUM% - %SITENAME%",
      "override": True
    },
    ...
  )
  ```

  ```ruby Ruby theme={null}
  seam.acs.credentials.create(
    is_multi_phone_sync_credential: true,
    acs_user_id: "33333333-3333-3333-3333-333333333333",
    access_method: "mobile_key",
    credential_manager_acs_system_id: "88888888-8888-8888-8888-888888888888",
    # ACS manufacturer-specific properties
    visionline_metadata: {
      "cardFormat" => "rfid48",
      "label" => "%ROOMNUM% - %SITENAME%",
      "override" => true
    },
    ...
  )
  ```

  ```php PHP theme={null}
  $seam->acs->credentials->create(
    is_multi_phone_sync_credential: true,
    acs_user_id: "33333333-3333-3333-3333-333333333333",
    access_method: "mobile_key",
    credential_manager_acs_system_id: "88888888-8888-8888-8888-888888888888",
    // ACS manufacturer-specific properties
    visionline_metadata => [
      "cardFormat" => "rfid48",
      "label" => "%ROOMNUM% - %SITENAME%",
      "override" => true
    ],
    ...
  );
  ```

  ```csharp C# theme={null}
  Coming soon!
  ```
</CodeGroup>

**Output:**

<CodeGroup>
  ```json JavaScript theme={null}
  {
    acs_credential_id: '99999999-9999-9999-9999-999999999999',
    acs_user_id: '33333333-3333-3333-3333-333333333333',
    access_method: 'mobile_key',
    is_multi_phone_sync_credential: true,
    ...
  }
  ```

  ```json cURL theme={null}
  {
    "acs_credential": {
      "acs_credential_id": "99999999-9999-9999-9999-999999999999",
      "acs_user_id": "33333333-3333-3333-3333-333333333333",
      "access_method": "mobile_key",
      "is_multi_phone_sync_credential": true,
      ...
    },
    "ok": true
  }
  ```

  ```json Python theme={null}
  AcsCredential(
    acs_credential_id='99999999-9999-9999-9999-999999999999',
    acs_user_id='33333333-3333-3333-3333-333333333333',
    access_method='mobile_key',
    is_multi_phone_sync_credential=True,
    ...
  )
  ```

  ```json Ruby theme={null}
  <Seam::Resources::AcsCredential:0x005f0
    acs_credential_id="99999999-9999-9999-9999-999999999999"
    acs_user_id="33333333-3333-3333-3333-333333333333"
    access_method="mobile_key"
    is_multi_phone_sync_credential=true
    ...
  >
  ```

  ```json PHP theme={null}
  {
    "acs_credential_id": "99999999-9999-9999-9999-999999999999",
    "acs_user_id": "33333333-3333-3333-3333-333333333333",
    "access_method": "mobile_key",
    "is_multi_phone_sync_credential": true,
    ...
  }
  ```

  ```json C# theme={null}
  Coming soon!
  ```
</CodeGroup>


# Managing Mobile App User Accounts with User Identities
Source: https://docs.seam.co/capability-guides/mobile-access/managing-mobile-app-user-accounts-with-user-identities

Learn how to use Seam user identities to manage mobile app user accounts.

## What is a User Identity?

Seam user identities are a feature for tracking and managing user accounts in your application. This feature assigns unique identifiers to each of your users, enabling you to issue and manage their [mobile credentials](/capability-guides/mobile-access/issuing-mobile-credentials-from-an-access-control-system) and access permissions. Each user identity is mapped to a user account in your app.

<img alt="Each user identity is mapped to a user account in your app." />

### User Identities Can Be Connected to Users in Multiple Access Control Systems

User identities can be linked to one [ACS user](/low-level-apis/access-systems/user-management) in each access control system. Any mobile credentials issued to these ACS users are consolidated under the user identity. Consequently, a user's mobile app account has access to these credentials through the user identity.

<img alt="A user identity can be connected to an ACS user in each ACS." />

***

## Create a User Identity and Associate it with an ACS User

### 1. Create a User Identity

To [create a user identity](/api/user_identities/create), you can specify any of the following characteristics:

* Unique user identity key (`user_identity_key`)
* Unique email address (`email_address`)
* Unique phone number (`phone_number`)
* Full name (`full_name`)

Note that if you specify one or more of the `user_identity_key`, `email_address`, or `phone_number`, each of these values must be unique within your [workspace](/core-concepts/workspaces/index).

**Command:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  await seam.userIdentities.create({
    user_identity_key: 'jean_doe',
    email_address: 'jean@example.com',
    phone_number: '+15555550110',
    full_name: 'Jean Doe',
  })
  ```

  ```bash cURL theme={null}
  curl -X 'POST' \
    'https://connect.getseam.com/user_identities/create' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d '{
    "user_identity_key": "jean_doe",
    "email_address": "jean@example.com",
    "phone_number": "+15555550110",
    "full_name": "Jean Doe"
  }'
  ```

  ```python Python theme={null}
  seam.user_identities.create(
    user_identity_key = "jean_doe",
    email_address = "jean@example.com",
    phone_number = "+15555550110",
    full_name = "Jean Doe"
  )
  ```

  ```ruby Ruby theme={null}
  seam.user_identities.create(
    user_identity_key: "jean_doe",
    email_address: "jean@example.com",
    phone_number: "+15555550110",
    full_name: "Jean Doe",
  )
  ```

  ```php PHP theme={null}
  $seam->user_identities->create(
    user_identity_key: "jean_doe",
    email_address: "jean@example.com",
    phone_number: "+15555550110",
    full_name: "Jean Doe"
  );
  ```

  ```csharp C# theme={null}
  Coming soon!
  ```
</CodeGroup>

**Output:**

<CodeGroup>
  ```json JavaScript theme={null}
  {
    "user_identity_id": "22222222-2222-2222-2222-222222222222",
    "user_identity_key": "jean_doe",
    "email_address": "jean@example.com",
    "phone_number": "+15555550110",
    "display_name": "Jean Doe",
    "full_name": "Jean Doe",
    ...
  }
  ```

  ```json cURL theme={null}
  {
    "user_identity": {
      "user_identity_id": "22222222-2222-2222-2222-222222222222",
      "user_identity_key": "jean_doe",
      "email_address": "jean@example.com",
      "phone_number": "+15555550110",
      "display_name": "Jean Doe",
      "full_name": "Jean Doe",
      ...
    },
    "ok": true
  }
  ```

  ```json Python theme={null}
  UserIdentity(
    user_identity_id='22222222-2222-2222-2222-222222222222',
    user_identity_key='jean_doe',
    email_address='jean@example.com',
    phone_number='+15555550110',
    display_name='Jean Doe',
    full_name='Jean Doe',
    ...
  )
  ```

  ```json Ruby theme={null}
  <Seam::Resources::UserIdentity:0x005f0
    user_identity_id="22222222-2222-2222-2222-222222222222"
    user_identity_key="jean_doe"
    email_address="jean@example.com"
    phone_number="+15555550110"
    display_name="Jean Doe"
    full_name="Jean Doe"
    ...
  >
  ```

  ```json PHP theme={null}
  {
    "user_identity_id": "22222222-2222-2222-2222-222222222222",
    "user_identity_key": "jean_doe",
    "email_address": "jean@example.com",
    "phone_number": "+15555550110",
    "display_name": "Jean Doe",
    "full_name": "Jean Doe",
    ...
  }
  ```

  ```json C# theme={null}
  Coming soon!
  ```
</CodeGroup>

### 2. Assign an ACS User to the User Identity

To [link an ACS user with a user identity](/api/user_identities/add_acs_user), provide the ID of the user identity and the ID of the ACS user.

**Command:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  const userIdentity = await seam.userIdentities.get({
    email_address: 'jean@example.com',
  })

  const acsUser = await seam.acs.users.get({
    email_address: 'jean@example.com',
  })

  await seam.userIdentities.addAcsUser({
    user_identity_id: userIdentity.user_identity_id,
    acs_user_id: acsUser.acs_user_id,
  })
  ```

  ```bash cURL theme={null}
  # Use GET or POST.
  curl -X 'GET' \
    'https://connect.getseam.com/user_identities/get' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d "{
    \"email_address\": \"jane@example.com\"
  }")

  # Use GET or POST.
  curl -X 'GET' \
    'https://connect.getseam.com/acs/users/get' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d "{
    \"email_address\": \"jane@example.com\"
  }")


  curl -X 'POST' \
    'https://connect.getseam.com/user_identities/add_acs_user' \
    -H 'accept: application/json' \
    -H 'Authorization: Bearer ${API_KEY}' \
    -H 'Content-Type: application/json' \
    -d "{
    \"user_identity_id\": \"$(jq -r '.user_identity.user_identity_id' <<< ${user_identity})\",
    \"acs_user_id\": \"$(jq -r '.acs_user.acs_user_id' <<< ${acs_user})\",
  }"
  ```

  ```python Python theme={null}
  user_identity = seam.user_identities.get(
    email_address = "jean@example.com"
  )

  acs_user = seam.acs.users.get(
    email_address = "jean@example.com"
  )

  seam.user_identities.add_acs_user(
    user_identity_id = user_identity.user_identity_id,
    acs_user_id = acs_user.acs_user_id
  )
  ```

  ```ruby Ruby theme={null}
  user_identity = seam.user_identities.get(
    email_address: "jane@example.com"
  )

  acs_user = seam.acs.users.get(
    email_address: "jane@example.com"
  )

  seam.user_identities.add_acs_user(
    user_identity_id: user_identity.user_identity_id,
    acs_user_id: acs_user.acs_user_id,
  )
  ```

  ```php PHP theme={null}
  $user_identity = $seam->user_identities->get(
    email_address: "jean@example.com",
  );

  $acs_user = $seam->acs->users->get(
    email_address: "jean@example.com",
  );

  $seam->user_identities->add_acs_user(
      user_identity_id: $user_identity->user_identity_id,
      acs_user_id: $acs_user->acs_user_id
  );
  ```

  ```csharp C# theme={null}
  Coming soon!
  ```
</CodeGroup>

**Output:**

<CodeGroup>
  ```json JavaScript theme={null}
  // void
  ```

  ```json cURL theme={null}
  {
    "ok": true
  }
  ```

  ```json Python theme={null}
  None
  ```

  ```json Ruby theme={null}
  nil
  ```

  ```json PHP theme={null}
  null
  ```

  ```json C# theme={null}
  Coming soon!
  ```
</CodeGroup>

***

## Removing a User Identity

When you [delete a user identity](/api/user_identities/delete), Seam automatically cleans up all other associated resources.

**Command:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  await seam.userIdentities.delete({
    user_identity_id: '22222222-2222-2222-2222-222222222222',
  })
  ```

  ```bash cURL theme={null}
  curl -X 'POST' \
    'https://connect.getseam.com/user_identities/delete' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d '{
    "user_identity_id": "22222222-2222-2222-2222-222222222222"
  }'
  ```

  ```python Python theme={null}
  seam.user_identities.delete(
      user_identity_id = "22222222-2222-2222-2222-222222222222"
  )
  ```

  ```ruby Ruby theme={null}
  seam.user_identities.delete(
    user_identity_id: "22222222-2222-2222-2222-222222222222"
  )
  ```

  ```php PHP theme={null}
  $seam->user_identities->delete(
    user_identity_id: "22222222-2222-2222-2222-222222222222"
  );
  ```

  ```csharp C# theme={null}
  Coming soon!
  ```
</CodeGroup>

**Output:**

<CodeGroup>
  ```json JavaScript theme={null}
  // void
  ```

  ```json cURL theme={null}
  {
    "ok": true
  }
  ```

  ```json Python theme={null}
  None
  ```

  ```json Ruby theme={null}
  nil
  ```

  ```json PHP theme={null}
  null
  ```

  ```json C# theme={null}
  Coming soon!
  ```
</CodeGroup>


# Managing Phones for a User Identity
Source: https://docs.seam.co/capability-guides/mobile-access/managing-phones-for-a-user-identity

Learn how to manage the phones associated with a user identity.

An app user may have several phones. When they sign into their account on your mobile application, it is important that additional phones also provide access. Seam facilitates this access by registering each phone within the [user identity](/capability-guides/mobile-access/managing-mobile-app-user-accounts-with-user-identities#what-is-a-user-identity) and synchronizing [mobile credentials](/capability-guides/mobile-access/issuing-mobile-credentials-from-an-access-control-system) across these phones. Further, Seam provides a feature to deactivate a phone if an app user loses it.

***

## App User New Phone Process

When an app user signs in to a new phone, Seam can automatically set up the new phone, generate matching credentials, and issue these credentials. To facilitate this capability, you must [issue a multi-phone sync credential](/capability-guides/mobile-access/issuing-mobile-credentials-from-an-access-control-system) when creating a mobile credential.

<img alt="When a user sign in to a new phone, Seam also issues matching credentials to the new phone." />

***

## App User Lost Phone Process

If an app user loses their phone or wants to deactivate it, you can deactivate the phone. Seam then automatically invalidates the stored credentials on their deactivated phone.

<img alt="When a phone is revoked, Seam revokes all the credentials issued to this phone." />

To [deactivate](/api/phones/deactivate) a phone, provide the ID of the phone. When a phone is deactivated, Seam also revokes all the credentials issued to the deactivated phone. Seam also removes the associated ACS credentials from the ACS.

**Command:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  await seam.phones.deactivate({
    device_id: lostPhoneId,
  })
  ```

  ```bash cURL theme={null}
  curl -X 'POST' \
    'https://connect.getseam.com/phones/deactivate' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d "{
    \"device_id\": \"${lost_phone_id}\"
  }"
  ```

  ```python Python theme={null}
  seam.phones.deactivate(
    device_id = lost_phone_id
  )
  ```

  ```ruby Ruby theme={null}
  seam.phones.deactivate(
    device_id: lost_phone_id
  )
  ```

  ```php PHP theme={null}
  $seam->phones->deactivate(
    device_id: $lost_phone_id,
  );
  ```

  ```csharp C# theme={null}
  Coming soon!
  ```
</CodeGroup>

**Output:**

<CodeGroup>
  ```json JavaScript theme={null}
  // void
  ```

  ```json cURL theme={null}
  {
    "ok": true
  }
  ```

  ```json Python theme={null}
  None
  ```

  ```json Ruby theme={null}
  nil
  ```

  ```json PHP theme={null}
  null
  ```

  ```json C# theme={null}
  Coming soon!
  ```
</CodeGroup>

***

## Retrieving Phones for a User Identity

To retrieve the list of phones that the mobile app user has used to sign in to their account, use the [List Phones](/api/phones/list) endpoint and include the ID of the user identity.

**Command:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  await seam.phones.list({
    owner_user_identity_id: user_identity.id,
  })
  ```

  ```bash cURL theme={null}
  # Use GET or POST.
  curl -X 'GET' \
    'https://connect.getseam.com/phones/list' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d "{
    \"owner_user_identity_id\": \"${user_identity_id}\"
  }"
  ```

  ```python Python theme={null}
  seam.phones.list(
    owner_user_identity_id = user_identity.id
  )
  ```

  ```ruby Ruby theme={null}
  seam.phones.list(
    owner_user_identity_id: user_identity.id,
  )
  ```

  ```php PHP theme={null}
  $seam->phones->list(
    owner_user_identity_id: $user_identity->id
  );
  ```

  ```csharp C# theme={null}
  Coming soon!
  ```
</CodeGroup>

**Output:**

<CodeGroup>
  ```json JavaScript theme={null}
  [
    {
      "device_id": "22222222-2222-2222-2222-444444444444",
      "device_type": "android_phone",
      "created_at": "2025-01-01T10:40:00+00:00",
      ...
    },
    {
      "device_id": "22222222-2222-2222-2222-555555555555",
      "device_type": "ios_phone",
      "created_at": "2025-01-02T10:40:00+00:00",
      ...
    },
    ...
  ]
  ```

  ```json cURL theme={null}
  {
    "phones": [
      {
        "device_id": "22222222-2222-2222-2222-444444444444",
        "device_type": "android_phone",
        "created_at": "2025-01-01T10:40:00+00:00",
        ...
      },
      {
        "device_id": "22222222-2222-2222-2222-555555555555",
        "device_type": "ios_phone",
        "created_at": "2025-01-02T10:40:00+00:00",
        ...
      },
      ...
    ],
    "ok": true
  }
  ```

  ```json Python theme={null}
  [
    Phone(
      device_id='22222222-2222-2222-2222-444444444444',
      device_type='android_phone',
      created_at='2025-01-01T10:40:00+00:00',
      ...
    )
    Phone(
      device_id='22222222-2222-2222-2222-555555555555',
      device_type='ios_phone',
      created_at='2025-01-02T10:40:00+00:00',
      ...
    )
    ...
  ]
  ```

  ```json Ruby theme={null}
  [
    <Seam::Resources::Phone:0x005f0
      device_id="22222222-2222-2222-2222-444444444444"
      device_type="android_phone"
      created_at="2025-01-01T10:40:00+00:00"
      ...
    >,
    <Seam::Resources::Phone:0x005f0
      device_id="22222222-2222-2222-2222-555555555555"
      device_type="ios_phone"
      created_at="2025-01-02T10:40:00+00:00"
      ...
    >,
    ...
  ]
  ```

  ```json PHP theme={null}
  [
    {
      "device_id": "22222222-2222-2222-2222-444444444444",
      "device_type": "android_phone",
      "created_at": "2025-01-01T10:40:00+00:00",
      ...
    },
    {
      "device_id": "22222222-2222-2222-2222-555555555555",
      "device_type": "ios_phone",
      "created_at": "2025-01-02T10:40:00+00:00",
      ...
    },
    ...
  ]
  ```

  ```json C# theme={null}
  Coming soon!
  ```
</CodeGroup>

***

## Retrieving a Phone by ID

To retrieve a phone by its ID, use the [Get Phone](/api/phones/get) endpoint and include the `device_id` of the phone.

**Command:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  await seam.phones.list({
    owner_user_identity_id: user_identity.id,
  })
  ```

  ```bash cURL theme={null}
  # Use GET or POST.
  curl -X 'GET' \
    'https://connect.getseam.com/phones/get' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d '{
    "device_id": "22222222-2222-2222-2222-444444444444"
  }'
  ```

  ```python Python theme={null}
  seam.phones.get(
    device_id = "22222222-2222-2222-2222-444444444444"
  )
  ```

  ```ruby Ruby theme={null}
  seam.phones.list(
    owner_user_identity_id: user_identity.id,
  )
  ```

  ```php PHP theme={null}
  $seam->phones->list(
    owner_user_identity_id: $user_identity->id
  );
  ```

  ```csharp C# theme={null}
  Coming soon!
  ```
</CodeGroup>

**Output:**

<CodeGroup>
  ```json JavaScript theme={null}
  [
    {
      "device_id": "22222222-2222-2222-2222-444444444444",
      "device_type": "android_phone",
      "created_at": "2025-01-01T10:40:00+00:00",
      ...
    },
    {
      "device_id": "22222222-2222-2222-2222-555555555555",
      "device_type": "ios_phone",
      "created_at": "2025-01-02T10:40:00+00:00",
      ...
    },
    ...
  ]
  ```

  ```json cURL theme={null}
  {
    "phone": {
      "device_id": "22222222-2222-2222-2222-444444444444",
      "device_type": "android_phone",
      "created_at": "2025-01-01T10:40:00+00:00",
      ...
    },
    "ok": true
  }
  ```

  ```json Python theme={null}
  Phone(
    device_id='22222222-2222-2222-2222-444444444444',
    device_type='android_phone',
    created_at='2025-01-01T10:40:00+00:00',
    ...
  )
  ```

  ```json Ruby theme={null}
  [
    <Seam::Resources::Phone:0x005f0
      device_id="22222222-2222-2222-2222-444444444444"
      device_type="android_phone"
      created_at="2025-01-01T10:40:00+00:00"
      ...
    >,
    <Seam::Resources::Phone:0x005f0
      device_id="22222222-2222-2222-2222-555555555555"
      device_type="ios_phone"
      created_at="2025-01-02T10:40:00+00:00"
      ...
    >,
    ...
  ]
  ```

  ```json PHP theme={null}
  [
    {
      "device_id": "22222222-2222-2222-2222-444444444444",
      "device_type": "android_phone",
      "created_at": "2025-01-01T10:40:00+00:00",
      ...
    },
    {
      "device_id": "22222222-2222-2222-2222-555555555555",
      "device_type": "ios_phone",
      "created_at": "2025-01-02T10:40:00+00:00",
      ...
    },
    ...
  ]
  ```

  ```json C# theme={null}
  Coming soon!
  ```
</CodeGroup>


# Prepare your Workspace
Source: https://docs.seam.co/capability-guides/mobile-access/mobile-access-setup

Learn how to set up the prerequisite components for the Seam mobile access solution.

To use the [Seam mobile access](./) solution, you must first set up the following components:

* **An access control system that is compatible with your chosen mobile access solution**\
  Obtain the account login information for your access control system (ACS). See the [brand-specific ACS guide](/device-and-system-integration-guides#access-control-systems) for instructions on where to find this information. In addition, verify that your ACS is compatible with the mobile technology that you intend to implement, such as Apple Wallet. It may be necessary to upgrade your system to support these technologies. Further, you may need to register for developer access with the ACS that you have chosen to use.
* **A credential manager account that is appropriate for the installed access hardware**\
  Depending on the make and model of your lock or access hardware, you may need to set up a credential manager account for issuing mobile credentials for your brand of lock. The credential manager is responsible for issuing mobile credentials and keeping track of which mobile credentials have been issued to which mobile devices. Often, the mobile credentials that the credential manager generates need to be imported into the access control system, before they can be used to grant access.
* **Access hardware that is configured with the appropriate settings**\
  Certain makes and models of lock hardware may require you to configure specific encryption keys on the access hardware to enable mobile access. See the appropriate [device guides](/device-and-system-integration-guides#smart-locks) for detailed instructions related to these requirements.

***

## Set up Your Workspace

To set up your Seam workspace to use the Seam mobile access solution:

1. **Connect your ACS account to Seam using a** [**Connect Webview**](/core-concepts/connect-webviews/index)

   This step requires the account information for your ACS account. For more information, see the [guide](/device-and-system-integration-guides#access-control-systems) for your specific ACS brand.

2. **Connect your credential manager account to Seam using a Connect Webview**\
   This step requires the account information for your credential manager account. For more information, see the corresponding [guide](/device-and-system-integration-guides#access-control-systems) for your credential manager type.

3. **Configure any workspace settings required**\
   Some integrations require certain workspace-wide settings to be configured. For more information, see the [guide](/device-and-system-integration-guides#access-control-systems) for your specific ACS brand.


# Handling System Permissions
Source: https://docs.seam.co/capability-guides/mobile-access/mobile-device-sdks/handling-system-permissions

Detect and resolve missing system permissions like Bluetooth and connectivity in your mobile app by handling the Seam SDK's credential errors.

The mobile SDK surfaces missing or required system permissions (Bluetooth, internet connectivity, and so on) as `CredentialError.userInteractionRequired(action)` entries in each credential’s `errors` array. After activation, observe these errors and handle the specified actions. Errors update automatically as requirements change.

***

## Platform Setup Requirements

First, configure the required platform capabilities.

<Tabs>
  <Tab title="iOS Swift">
    1. **Suppress Apple Wallet while unlocking with BLE**\
       To prevent the Apple Wallet dialog from appearing when your app uses BLE to unlock a door, do the following:

       * Add the `requestAutomaticPassPresentationSuppression()` call to your app.\
         This method suppresses Apple Wallet while your mobile app is in the foreground and ensures a smoother `unlockWithTap` experience.
       * Request the  `com.apple.developer.passkit.pass-presentation-suppression` entitlement from Apple.&#x20;

       Apple Wallet suppression and Bluetooth scanning only apply while the app is in the foreground. Ensure unlock operations are initiated while the app is active.

    2. **Enable Bluetooth capability**

       Add the required Bluetooth key to your app’s entitlements file:

       ```xml theme={null}
       <dict>
         <key>com.apple.security.device.bluetooth</key>
         <true/>
       </dict>
       ```
  </Tab>

  <Tab title="Android Kotlin">
    1. **Request Bluetooth permissions**

       Define and call a helper function in your app to request the necessary Bluetooth permissions at runtime.

    2. **For Android 12 (API 31) and newer:**

       ```
       Manifest.permission.BLUETOOTH_SCAN
       Manifest.permission.BLUETOOTH_CONNECT
       Manifest.permission.BLUETOOTH_ADVERTISE
       ```

    3. **For Android 11 (API 30) and older:**

       ```
       Manifest.permission.BLUETOOTH
       Manifest.permission.BLUETOOTH_ADMIN
       Manifest.permission.ACCESS_COARSE_LOCATION
       Manifest.permission.ACCESS_FINE_LOCATION
       ```

    See [Android request permissions](https://developer.android.com/training/permissions/requesting) for more details.
  </Tab>
</Tabs>

## Monitoring Permission Errors

<Tabs>
  <Tab title="iOS Swift">
    Use Combine to watch the published credentials array and handle permission-related errors:

    ```swift theme={null}
    import SeamSDK
    import Combine

    func startMonitoringPermissionErrors() {
        permissionCancellable = Seam.shared.$credentials
            .map { credentials in
                credentials.flatMap { credential in
                    credential.errors.compactMap { error in
                        guard case .userInteractionRequired(let action) = error else { return nil }
                        return action
                    }
                }
            }
            .receive(on: RunLoop.main)
            .sink { actions in
                actions.forEach { handlePermissionAction($0) }
            }
    }
    ```

    The mobile SDK automatically clears resolved permission errors once the required permission is granted, reflecting the updated credential state.
  </Tab>

  <Tab title="Android Kotlin">
    ```kotlin theme={null}
    coroutineScope.launch {
        SeamSDK.getInstance().credentials.collect { credentialsList ->
            val errors = credentialsList.flatMap { it.errors }
            errors.forEach { error ->
                when (error) {
                    is SeamCredentialError.UserInteractionRequired -> {
                        handleUserInteractionRequired(error.interaction)
                    }
                    else -> { /* handle other errors */ }
                }
            }
        }

        fun handleUserInteractionRequired(interaction: SeamRequiredUserInteraction) {
            when (interaction) {
                is SeamRequiredUserInteraction.GrantPermissions -> {
                     /* handle permissions error */
                     // interaction.permissions contains the list of required permissions
                }
                else -> { /* handle other errors */ }
            }
        }

    }

    ```

    The mobile SDK automatically clears resolved permission errors once the required permission is granted, reflecting the updated credential state.
  </Tab>
</Tabs>

## Handling Permission Actions

Implement your handler for each action:

<CodeGroup>
  ```kotlin Android Kotlin theme={null}
  fun handleUserInteractionRequired(interaction: SeamRequiredUserInteraction) {
      when (interaction) {
          is SeamRequiredUserInteraction.CompleteOtpAuthorization -> { /* handle OTP authorization */ }
          is SeamRequiredUserInteraction.EnableBluetooth -> { /* handle Bluetooth error */ }
          is SeamRequiredUserInteraction.EnableInternet -> { /* handle Internet connection error*/ }
          is SeamRequiredUserInteraction.GrantPermissions -> { /* handle permissions error*/ }
      }
  }
  ```

  ```swift iOS Swift theme={null}
  func handlePermissionAction(_ action: CredentialUserAction) {
      switch action {
      case .enableInternet:
          // Prompt the user to enable network connectivity.
      case .enableBluetooth:
          // Prompt the user to turn on Bluetooth.
      case .grantBluetoothPermission:
          // Prompt the user to grant Bluetooth permission in Settings.
      }
  }
  ```
</CodeGroup>

***

## See also

For a complete SwiftUI-based implementation of credential error handling for iOS, see `SeamUnlockCardView` in the SeamComponents library, which demonstrates observing credential errors and updating the UI accordingly.


# Integrating into Your Mobile Application
Source: https://docs.seam.co/capability-guides/mobile-access/mobile-device-sdks/index

The Seam mobile SDKs help you to create native applications for Apple (iOS) and Android devices and platforms.

## Overview

We have designed the Seam mobile SDKs to provide the flexibility to support a range of workflows. This example describes a mobile key workflow, in which the smart door lock scans for and unlocks in the presence of a nearby mobile device acting as a passive key. Note that the mobile device in this example uses Bluetooth Low Energy (BLE) technology.

1. Once the mobile app is downloaded, it requests Bluetooth permissions from the user.
2. The user presses the **Unlock** button, prompting the phone to search for nearby locks.
3. When the user holds their phone close to the lock, a Bluetooth connection is established, and the phone transmits a key to the lock.
4. The lock verifies the mobile key, confirms that the key can access this lock, and sends a success response back to the app.
5. The lock successfully unlocks!

<img alt="Example of Unlock sequence in a Mobile App" />


# Initializing the Seam Mobile SDK
Source: https://docs.seam.co/capability-guides/mobile-access/mobile-device-sdks/initializing-the-seam-mobile-sdk

Install and initialize the Seam Mobile SDK in your Android or iOS app, configure Gradle for Seam GitHub Packages, and start issuing mobile keys.

## 1. Install the Seam SDK

The Seam SDK is [available for download on request](mailto:support@seam.co) and is fully documented. See the Seam [Android](/mobile-sdks/android/index) and [iOS](/mobile-sdks/ios/reference/seam) SDK reference documentation.

<Info>
  You must also use the Seam API to perform server-side actions. Consequently,
  [install a Seam server-side SDK](/api/installation)
  in the language of your choice if you have not done so already.
</Info>

<Tabs>
  <Tab title="Android Kotlin">
    #### Configure Gradle to use Seam GitHub Packages

    This project retrieves the Seam Mobile SDK artifacts from GitHub Packages.

    To build successfully, you need valid credentials and must configure Gradle to fetch dependencies from Seam’s private package repository.

    **Using Kotlin Script (settings.gradle.kts):**

    ```kotlin theme={null}
    // getPropertyOrNull is a helper function defined in settings.gradle.kts
    // to safely read properties from local.properties
    fun getPropertyOrNull(propertyName: String): String? {
        val propertiesFile = file("local.properties")
        if (!propertiesFile.exists()) return null

        val properties = Properties()
        properties.load(propertiesFile.inputStream())
        return properties.getProperty(propertyName, null)
    }

    // settings.gradle.kts
    repositories {
        // ... other repositories
        maven {
            name = "GitHubPackages"
            url = uri("https://maven.pkg.github.com/seampkg/seam-mobile-sdk")
            credentials {
                username = getPropertyOrNull("seamUsername")
                password = getPropertyOrNull("seamPat")
            }
        }
    }
    ```

    **Using Groovy (settings.gradle):**

    ```groovy theme={null}
    // getPropertyOrNull is a helper function defined in settings.gradle
    // to safely read properties from local.properties
    String getPropertyOrNull(String propertyName) {
        def propertiesFile = file("local.properties")
        if (!propertiesFile.exists()) return null

        def properties = new Properties()
        properties.load(propertiesFile.inputStream())
        return properties.getProperty(propertyName, null)
    }

    // settings.gradle
    repositories {
        // ... other repositories
        maven {
            name = "GitHubPackages"
            url = uri("https://maven.pkg.github.com/seampkg/seam-mobile-sdk")
            credentials {
                username = getPropertyOrNull("githubUsername")
                password = getPropertyOrNull("githubPat")
            }
        }
    }
    ```

    ***

    #### Add your GitHub credentials

    Gradle requires two credentials to download the Seam SDK packages from GitHub:

    <table>
      <thead>
        <tr>
          <th>Credential</th>
          <th>Description</th>
          <th>Where to get it</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>
            <code>githubUsername</code>
          </td>

          <td>Your GitHub username.</td>
          <td>Use the same username you use to log in to GitHub.</td>
        </tr>

        <tr>
          <td>
            <code>githubPat</code>
          </td>

          <td>
            Personal Access Token (PAT) with the <code>read:packages</code> scope
          </td>

          <td>Follow the steps below to generate it.</td>
        </tr>
      </tbody>
    </table>

    **To retrieve your credentials**

    1. Ask Seam to add your GitHub account as a collaborator to the private repository:\
       [https://github.com/seampkg/seam-mobile-sdk](https://github.com/seampkg/seam-mobile-sdk)

    2. Once you’ve been added, go to your GitHub account:

       **Settings** → **Developer settings** → **Personal access tokens** → **Tokens (classic)**

    3. Select **Generate new token (classic)** and choose:
       * Expiration: as needed (e.g., 90 days or “No expiration” if permitted)
       * Scopes: check only `read:packages`

    4. Copy the generated token. This is your `githubPat` value.

    Once you have both values, create a `local.properties` file in your project root:

    ```properties theme={null}
    # local.properties (DO NOT COMMIT THIS FILE)
    githubUsername=YOUR_GITHUB_USERNAME
    githubPat=YOUR_GITHUB_CLASSIC_PAT
    ```

    <Info>
      Important:

      `local.properties` is listed in `.gitignore` by default. Never commit this file to version control.
      PATs are private credentials--treat them like passwords.
      If your token expires or you lose access, generate a new one from your GitHub settings.
    </Info>

    ***

    #### Add Seam SDK dependencies

    Include the required Seam SDK components in your `app/build.gradle.kts`.

    The `seam-phone-sdk-android-core` module provides the core functionality and must be included for all other components to work.

    Each additional dependency enables support for a specific lock or credential integration. For example, to use **Salto Space**, add the `seam-phone-sdk-android-saltospace` module. You can include as many integration modules as your app requires.

    **Kotlin script (build.gradle.kts):**

    ```kotlin theme={null}
    val seamVersion = "3.1.6" // Or the desired version

    dependencies {
        // ... other dependencies
        implementation("co.seam:seam-phone-sdk-android-core:$seamVersion")
        implementation("co.seam:seam-phone-sdk-android-saltoks:$seamVersion")
        implementation("co.seam:seam-phone-sdk-android-saltospace:$seamVersion")
        implementation("co.seam:seam-phone-sdk-android-latch:$seamVersion")
        implementation("co.seam:seam-phone-sdk-android-assaabloy:$seamVersion")
        implementation("co.seam:seam-phone-sdk-android-legic:$seamVersion")
        // ...
    }
    ```

    **Groovy script (build.gradle):**

    ```groovy theme={null}
    // app/build.gradle.kts
    def seamVersion = "3.1.6" // Or the desired version

    dependencies {
        // ... other dependencies
        implementation "co.seam:seam-phone-sdk-android-core:$seamVersion"
        implementation "co.seam:seam-phone-sdk-android-saltoks:$seamVersion"
        implementation "co.seam:seam-phone-sdk-android-saltospace:$seamVersion"
        implementation "co.seam:seam-phone-sdk-android-latch:$seamVersion"
        implementation "co.seam:seam-phone-sdk-android-assaabloy:$seamVersion"
        implementation "co.seam:seam-phone-sdk-android-legic:$seamVersion"
        // ...
    }
    ```
  </Tab>

  <Tab title="iOS Swift">
    You can install SeamSDK via CocoaPods or Swift Package Manager (SPM).\
    SeamSDK supports per-lock-provider integration granularity. Include only the modules you need to keep your app footprint minimal.

    **CocoaPods:**

    ```ruby theme={null}
    use_frameworks!
    platform :ios, '15.0'

    target 'YourApp' do
      # Local pod install with file path to SeamSdk.podspec
      pod 'SeamSDK', :path => 'PATH_TO_SEAM_SDK/SeamSDK.podspec'
      # Optional subspecs for specific providers:
      pod 'SeamSDK/SeamDormakabaIntegration', :path => 'PATH_TO_SEAM_SDK/SeamSDK.podspec'
      pod 'SeamSDK/SeamLatchIntegration', :path => 'PATH_TO_SEAM_SDK/SeamSDK.podspec'
    end
    ```

    **Swift Package Manager:**

    ```swift theme={null}
    dependencies: [
        .package(path: "PATH_TO_SEAM_SDK/SeamSDK")
    ],
    targets: [
        .target(
            name: "YourApp",
            dependencies: ["SeamSDK", "SeamSaltoIntegration"]
        )
    ]
    ```
  </Tab>
</Tabs>

***

## 2. Implement any Manufacturer- and Mobile OS-Specific Requirements

Note the following manufacturer- and OS-specific requirements:

### Manufacturer-Specific Requirements

See the [device or system integration guide](/device-and-system-integration-guides#access-control-systems) for the access control system or device for which you are planning to develop. Further, you may need to register for developer access with the ACS that you have chosen to use.

***

### iOS Requirement

While not required, you can optionally request the `com.apple.developer.passkit.pass-presentation-suppression` entitlement from the Apple Developer portal. This entitlement prevents Apple Wallet from appearing when scanning for Bluetooth low energy (BLE) or similar locks, improving the unlock experience.

***

## 3. Configure a User Identity for your App User and Generate a Client Session Token

A [user identity](../managing-mobile-app-user-accounts-with-user-identities) enables the application to request a user's mobile access permissions and use the app to unlock doors.

First, use the Seam API or Seam Console to create a [user identity](../managing-mobile-app-user-accounts-with-user-identities#what-is-a-user-identity) that will correspond to the App User Account using your internal user ID or other identifying information.

Then, using the user identity, create a [client session](/core-concepts/authentication/client-session-tokens/index) and capture the resulting [client session token](/core-concepts/authentication/client-session-tokens/index). This token will be used to authenticate the user on your application.

<CodeGroup>
  ```javascript JavaScript theme={null}
  // Create the user identity.
  const userIdentity = await seam.userIdentities.create({
    email_address: 'jane@example.com',
  })

  // Create the client session.
  const clientSession = await seam.clientSessions.create({
    user_identity_ids: [userIdentity.user_identity_id],
  })

  // Use this token to launch your mobile controller.
  const token = clientSession.token
  ```

  ```bash cURL theme={null}
  # Create the user identity.
  user_identity=$(curl -X 'POST' \
    'https://connect.getseam.com/user_identities/create' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${API_KEY}" \
    -H 'Content-Type: application/json' \
    -d '{
          "email_address": "jane@example.com"
    }')

  # Get the user identity ID.
  user_identity_id=$(echo $user_identity | jq -r '.user_identity.user_identity_id')

  # Create the client session.
  client_session=$(curl -X 'POST' \
    'https://connect.getseam.com/client_sessions/create' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${API_KEY}" \
    -H 'Content-Type: application/json' \
    -d "{
          \"user_identity_ids\": [\"$user_identity_id\"]
    }")

  # Get the resulting client session token and
  # use this token to launch your mobile controller.
  token=$(echo $client_session | jq -r '.client_session.token')
  ```

  ```python Python theme={null}
  # Create the user identity.
  user_identity = seam.user_identities.create(
      email_address="jane@example.com"
  )

  # Create the client session.
  client_session = seam.client_sessions.create(
      user_identity_ids=[user_identity.user_identity_id]
  )

  # Use this token to launch your mobile controller.
  token = client_session.token
  ```

  ```ruby Ruby theme={null}
  # Create the user identity.
  user_identity = client.user_identities.create(
      email_address: "jane@example.com"
  )

  # Create the client session.
  client_session = client.client_sessions.create(
      user_identity_ids: [user_identity.user_identity_id]
  )

  # Use this token to launch your mobile controller.
  token = client_session.token
  ```

  ```php PHP theme={null}
  // Create the user identity.
  $user_identity = $seam->user_identities->create(
    email_address: "jane@example.com"
  );

  // Create the client session.
  $client_session = $seam->client_sessions->create(
    user_identity_ids: [$user_identity->user_identity_id]
  );

  // Use this token to launch your mobile controller.
  $token = $client_session->token;
  ```
</CodeGroup>

***

## 4. Initialize the Mobile SDK with the Client Session Token

Use the client session token that you generated earlier to bootstrap the Seam SDK on the device. Under the hood, this action sets up credential synchronization and starts a background sync loop to keep permissions up to date.

### Initialization and Error Handling

Perform initialization and activation within your app’s asynchronous context (for example, Swift’s `Task` or Kotlin coroutines) so that you can handle errors. The initialization call may fail due to configuration issues (such as an invalid token), and the activation call may fail due to network or runtime errors. Catch these errors and present a user-friendly message or fallback UI as appropriate.

<CodeGroup>
  ```swift iOS Swift theme={null}
  import SeamSDK

  // Initialize the Mobile SDK with the client session token (CST).
  Task {
  do {
  // Bootstrap the SDK with the CST from your login flow.
  try Seam.initialize(clientSessionToken: token)
  // Start credential sync and background polling.
  try await Seam.shared.activate()
  print("Seam SDK is now active.")
  } catch let error as SeamError {
  // Handle SDK-specific initialization errors (invalid token, etc).
  showAlert(title: "Initialization Failed", message: error.localizedDescription)
  }
  }

  ```

  ```kotlin Android Kotlin theme={null}
  try {
      SeamSDK.initialize(context, "seam_cst_...")
      SeamSDK.getInstance().activate()
  } catch (seamError: SeamError) {
      when (seamError) {
          is SeamError.AlreadyInitialized -> {
              // handle error when SDK is already initialized
          }
          is SeamError.DeactivationInProgress -> {
              // handle error when app is being deactivated
          }
          is SeamError.InternetConnectionRequired -> {
              // handle error when internet connection is required
          }
          is SeamError.InvalidClientSessionToken ->  {
              // handle error when client session token is invalid
          }
          else -> {
              // handle other errors
          }
      }
  }
  ```
</CodeGroup>

### Credential Errors

Any errors that occur between activation and deactivation surface on individual credential objects through their `errors` property. You can observe the `credentials` list to detect and handle these issues in real time.

<Tabs>
  <Tab title="iOS Swift">
    **Observe credential errors**

    ```swift theme={null}
    import SeamSDK
    import Combine

    private var credentialErrorsCancellable: AnyCancellable?

    func startMonitoringCredentialErrors() {
        credentialErrorsCancellable = Seam.shared.$credentials
            .sink { credentials in
                for credential in credentials where !credential.errors.isEmpty {
                    print("Errors for \(credential.displayName):", credential.errors)
                }
            }
    }
    ```

    **Credential error types**

    * `awaitingLocalCredential`: Waiting for a local credential to become available.
    * `expired`: The credential has expired and is no longer valid.
    * `userInteractionRequired(action)`: User interaction is required to resolve the issue; inspect action for details.
    * `unsupportedDevice`: The current device is not supported.
    * `contactSeamSupport`: Configuration error requiring developer attention.
    * `unknown`: An unclassified or unexpected credential error occurred.

    **userInteractionRequired actions**

    * `completeOtpAuthorization(otpUrl:)`: The user must complete OTP authorization via the provided URL.
    * `enableInternet`: The user must enable internet connectivity.
    * `enableBluetooth`: The user must enable Bluetooth on the device.
    * `grantBluetoothPermission`: The user must grant Bluetooth permission to the app.
    * `appRestartRequired`: The user must restart the app to resolve the issue.
  </Tab>

  <Tab title="Android Kotlin">
    **Observe credential errors**

    ```kotlin theme={null}
    // One of the attributes of the credential is a list of errors of type `SeamCredentialError`
    coroutineScope.launch {
        SeamSDK.getInstance().credentials.collect { credentialsList ->
            val errors = credentialsList.flatMap { it.errors }
            errors.forEach { error ->
                when (error) {
                    is SeamCredentialError.Expired -> { /* handle credential expiration error */}
                    is SeamCredentialError.Loading -> { /* handle not loaded yet */ }
                    is SeamCredentialError.Unknown -> { /* handle unknown error */}
                    is SeamCredentialError.UserInteractionRequired -> {
                        handleUserInteractionRequired(error.interaction)
                    }
                }
            }
        }
    }

    fun handleUserInteractionRequired(interaction: SeamRequiredUserInteraction) {
        when (interaction) {
            is SeamRequiredUserInteraction.CompleteOtpAuthorization -> { /* handle OTP authorization */ }
            is SeamRequiredUserInteraction.EnableBluetooth -> { /* handle Bluetooth error */ }
            is SeamRequiredUserInteraction.EnableInternet -> { /* handle Internet connection error*/ }
            is SeamRequiredUserInteraction.GrantPermissions -> { /* handle permissions error*/ }
        }
    }

    ```

    **Credential error types**

    * `Loading`: The system is waiting for a local credential to become available.
    * `Expired`: The credential has expired and is no longer valid.
    * `UserInteractionRequired(val interaction: SeamRequiredUserInteraction)`: User interaction is required to resolve the issue; check interaction for specifics.
    * `Unknown`: An unclassified or unexpected credential error occurred.

    **userInteractionRequired actions**

    * `CompleteOtpAuthorization(val otpUrl: String)`: The user must complete OTP authorization via the provided URL.
    * `EnableInternet`: The user must enable internet connectivity.
    * `EnableBluetooth`: The user must enable Bluetooth on the device.
    * `GrantPermissions(val permissions: List<String>)`: The user must grant the required permissions.
    * `AppRestartRequired`: The user must restart the app to resolve the issue.
  </Tab>
</Tabs>


# Using Unlock With Tap
Source: https://docs.seam.co/capability-guides/mobile-access/mobile-device-sdks/using-unlock-with-tap

This feature enables your app to perform unlock operations using mobile credentials.

Unlocking with SeamSDK uses proximity to communicate credentials to door readers. When a user initiates an unlock, the SDK performs scanning, error handling, and unlock events using `Seam.shared.unlock(using:)`.

Using this process involves the following steps:

1. Retrieve available mobile credentials.
2. Monitor for permission or credential errors. Unhandled errors are thrown as `credentialErrors([SeamCredentialError])`.
3. Perform the unlock operation.
4. Handle unlock status events.
5. Cancel the unlock operation if needed.

***

## 1. Retrieve Mobile Credentials

Access the current credentials through the published `credentials` array on `Seam.shared`:

<CodeGroup>
  ```swift iOS Swift theme={null}
  import SeamSDK
  import Combine

  // Access credentials
  let credentials = Seam.shared.credentials

  // Observe updates with Combine
  let credentialsSubscription = Seam.shared.$credentials
  .sink { creds in
  // Update UI with new credentials array.
  }

  ```

  ```kotlin Android Kotlin theme={null}
  import co.seam.core.api.SeamCredential
  import co.seam.core.api.SeamSDK

  // Collect credentials
  SeamSDK.getInstance().credentials.collect { credentials ->
      // Update UI with new credentials array.
  }
  ```
</CodeGroup>

## 2. Monitor Credential Errors

Permission or setup issues appear in each credential’s `errors` property. Observe like this:

<CodeGroup>
  ```swift iOS Swift theme={null}
  import SeamSDK
  import Combine

  let errorSubscription = Seam.shared.$credentials
  .flatMap { creds in creds.publisher }
  .map { $0.errors }
  .sink { errors in
  // Handle errors, for example, `.userInteractionRequired`, `.expired`, etc.
  }

  ```

  ```kotlin Android Kotlin theme={null}
  import co.seam.core.api.SeamCredential
  import co.seam.core.api.SeamSDK
  import co.seam.core.sdkerrors.SeamCredentialError
  import co.seam.core.sdkerrors.SeamError
  import co.seam.core.sdkerrors.SeamRequiredUserInteraction

  SeamSDK.getInstance().credentials.collect { credentialsList ->
      val errors = credentialsList.flatMap { it.errors }
      errors.forEach { error ->
          when (error) {
              is SeamCredentialError.Expired -> { /* handle credential expiration error */}
              is SeamCredentialError.Loading -> { /* handle not loaded yet */ }
              is SeamCredentialError.Unknown -> { /* handle unknown error */}
              is SeamCredentialError.UserInteractionRequired -> {
                  handleUserInteractionRequired(error.interaction)
              }
          }
      }
  }

  fun handleUserInteractionRequired(interaction: SeamRequiredUserInteraction) {
      when (interaction) {
          is SeamRequiredUserInteraction.CompleteOtpAuthorization -> { /* handle OTP authorization */ }
          is SeamRequiredUserInteraction.EnableBluetooth -> { /* handle Bluetooth error */ }
          is SeamRequiredUserInteraction.EnableInternet -> { /* handle Internet connection error*/ }
          is SeamRequiredUserInteraction.GrantPermissions -> { /* handle permissions error*/ }
      }
  }
  ```
</CodeGroup>

> **Note:** The `.errors` array on credentials represents per-credential issues, though some issues may be repeated across several credentials (for example, bluetooth requirements). SDK- or credential-level errors (such as invalid token or expired credential) are thrown directly by methods like `unlock(using:)` because `SeamError` or `SeamCredentialError` and must be handled through `do/catch`.

## 3. Perform Unlock Operation

The call to `Seam.shared.unlock(using:)` may throw:

* `SeamError`: For SDK-level issues (for example, invalid token, uninitialized SDK).
* `SeamCredentialError`: For credential-specific issues (for example, expired credential, device not eligible). Ensure that you wrap the call in `do/catch` blocks to handle these errors.

Use Async/Await or Combine to initiate an unlock with a selected credential:

<CodeGroup>
  ```swift iOS Swift theme={null}
  import SeamSDK
  import Combine

  let credentialId = credentials.first!.id

  // Async/Await example
  Task {
      do {
          for try await event in try Seam.shared.unlock(using: credentialId).values {
              switch event {
              case .grantedAccess:
                  // The lock granted access. Show a success indicator.
              default:
                  print("Unlock event: \(event)")
                  // Access wasn't granted. Inform the user and offer retry.
              }
          }
      } catch {
          // Handle unlock error, for example, invalid credential or SDK error
          print("Unlock error: \(error)")
      }
  }

  // Combine example
  do {
      let unlockPublisher = try Seam.shared.unlock(using: credentialId)
      let unlockSubscription = unlockPublisher.sink(
          receiveCompletion: { _ in
              // Unlock completed.
          },
          receiveValue: { event in
              switch event {
              case .grantedAccess:
                  // The lock granted access—show a success indicator.
              default:
                  // Access wasn't granted, inform the user and offer retry.
                  print("Unlock event: \(event)")
              }
          }
      )
      // Retain `unlockSubscription`; discarding it will cancel the unlock attempt.
  } catch {
      // Handle unlock initialization error.
      print("Unlock error: \(error)")
  }
  ```

  ```kotlin Android Kotlin theme={null}
  import co.seam.core.api.SeamCredential
  import co.seam.core.api.SeamSDK
  import co.seam.core.events.SeamUnlockEvent
  import co.seam.core.sdkerrors.SeamCredentialError
  import co.seam.core.sdkerrors.SeamError
  import co.seam.core.sdkerrors.SeamRequiredUserInteraction

  val seamSDK = SeamSDK.getInstance()

  // Perform unlock
  try {
  val credentialId = credential.id
  // Timeout is optional
  seamSDK.unlock(
  credentialId = credentialId,
  timeout = 30.seconds
  )
  } catch (seamError: SeamError) {
  when (seamError) {
  is SeamError.ActivationRequired -> {
  // handle error when SDK is not activated
  }
  is SeamError.CredentialErrors -> {
  val credentialErrors = seamError.errors
  handleCredentialErrors(credentialErrors)
  // handle error when there are credential errors
  }
  is SeamError.InitializationRequired -> {
  // handle error when SDK is not initialized
  }
  is SeamError.IntegrationNotFound -> {
  // handle error when integration is not found, Such as Assa Abloy, Latch and Salto
  }
  is SeamError.InternetConnectionRequired -> {
  // handle error when internet connection is required
  }
  is SeamError.InvalidClientSessionToken -> {
  // handle error when client session token is invalid
  }
  else -> {
  // handle other errors
  }
  }
  }

  // Handle credential errors on unlock
  fun handleCredentialErrors(credentialErrors: List<SeamCredentialError>) {
  credentialErrors.forEach { credentialError ->
  when (credentialError) {
  is SeamCredentialError.Invalid -> {
  // handle error when credential is invalid
  }

              is SeamCredentialError.Expired -> {
                  // handle error when credential is expired
              }

              is SeamCredentialError.Loading -> {
                  // handle error when credential is not loaded yet
              }

              is SeamCredentialError.UserInteractionRequired -> {
                  // handle user interaction required credential error
              }

              is SeamCredentialError.Unknown -> {
                  // handle unknown credential error
              }
          }
      }

  }

  ```
</CodeGroup>

***

## 4. Handle Unlock Events

Handle each `SeamUnlockEvent` to update your UI and logic. Available events:

* **launched**\
  Unlock operation has started.
* **grantedAccess**\
  Access was granted by the lock.
* **timedOut**\
  Unlock operation timed out without success.
* **connectionFailed(debugDescription:)**\
  Unlock operation failed to connect; `debugDescription` may contain additional details.

<Tabs>
  <Tab title="iOS Swift">
    Async/Await example:

    ```swift theme={null}
    Task {
        do {
            for try await event in Seam.shared.unlock(using: credentialID) {
                switch event {
                case .launched:
                    // Show scanning indicator.
                case .grantedAccess:
                    // Show access granted.
                case .timedOut:
                    // Show timeout and offer retry.
                case .connectionFailed(let debugDescription):
                    // Show error with debugDescription.
                }
            }
        } catch {
            // Handle thrown errors.
        }
    }
    ```

    Combine example:

    ```swift theme={null}
    do {
        let unlockPublisher = try Seam.shared.unlock(using: credentialID)
        let unlockSubscription = unlockPublisher
            .receive(on: RunLoop.main)
            .sink(
                receiveCompletion: { _ in
                    // unlock completed.
                },
                receiveValue: { event in
                    switch event {
                    case .launched:
                        // Show scanning indicator.
                    case .grantedAccess:
                        // Show success indicator.
                    case .timedOut:
                        // Operation timed out—offer retry.
                    case .connectionFailed(let debugDescription):
                        // Show debugDescription details.
                    }
                }
            )
        // Retain `unlockSubscription` as a property and cancel when appropriate (for example, in deinit or viewWillDisappear).
    } catch {
        // Handle unlock initialization error.
        print("Unlock initialization error: \(error)")
    }
    ```
  </Tab>

  <Tab title="Android Kotlin">
    ```kotlin theme={null}
    // Start collecting unlock events before unlock
    coroutineScope.launch {
        seamSDK.unlockStatus.collect { event ->
            when (event) {
                is SeamUnlockEvent.ScanningStarted -> { /* handle scanning started */}
                is SeamUnlockEvent.Connecting -> { /* handle connecting */}
                is SeamUnlockEvent.AccessGranted -> { /* handle access granted */}
                is SeamUnlockEvent.Timeout -> { /* handle timeout */}
                is SeamUnlockEvent.ReaderError -> { /* handle reader error */}
                else -> { /* handle other events */}
            }
        }
    }
    ```
  </Tab>
</Tabs>

## 5. Cancel the Unlock Operation

Stop scanning by canceling your active task or subscription.

<CodeGroup>
  ```swift iOS Swift theme={null}
  // For Combine
  unlockSubscription.cancel()

  // For Async/Await, cancel the Task as needed.

  ```

  ```kotlin Android Kotlin theme={null}
  val seamSDK = SeamSDK.getInstance()
  // The unlock function returns a Job
  val job = seamSDK.unlock(
      credentialId = credentialId,
      timeout = 30.seconds
  )

  // Canceling the job stops the unlock process
  job.cancel()
  ```
</CodeGroup>


# Configuring Noise Threshold Settings
Source: https://docs.seam.co/capability-guides/noise-sensors/configure-noise-threshold-settings

Learn how to configure noise thresholds for noise sensors.

Seam enables you to configure the [noise thresholds](#set-up-noise-thresholds) of your noise sensor, as well as to receive events when a disturbance is detected. This guide walks you through how to configure noise thresholds with the Seam API.

## Set Up Noise Thresholds

First, create a threshold using the [Create a Noise Threshold](/api/noise_sensors/noise_thresholds/create) endpoint. For example:

**Request:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  const deviceId = '98dc7c66-045d-49cb-a62b-4bb431b0a9fa'

  const noiseThresholdAttempt = await seam.noiseThresholds.create({
    device_id: deviceId,
    starts_daily_at: '20:00:00[America/Los_Angeles]',
    ends_daily_at: '06:00:00[America/Los_Angeles]',
    noise_threshold_decibels: 70,
  })

  console.log(noiseThresholdAttempt)
  ```

  ```bash cURL theme={null}
  curl -X 'POST' \
    'https://connect.getseam.com/noise_sensors/noise_thresholds/create' \
    -H 'accept: application/json' \
    -H 'Authorization: Bearer ${API_KEY}' \
    -H 'Content-Type: application/json' \
    -d '{
    "device_id": "98dc7c66-045d-49cb-a62b-4bb431b0a9fa",
    "starts_daily_at": "20:00:00[America/Los_Angeles]",
    "ends_daily_at": "06:00:00[America/Los_Angeles]",
    "noise_threshold_decibels": 70
  }'
  ```

  ```python Python theme={null}
  device_id = "98dc7c66-045d-49cb-a62b-4bb431b0a9fa"

  noise_threshold = seam.noise_sensors.noise_thresholds.create(
      device_id = device_id,
      starts_daily_at = "20:00:00[America/Los_Angeles]",
      ends_daily_at = "06:00:00[America/Los_Angeles]",
      noise_threshold_decibels = 70
  )

  pprint(noise_threshold)
  ```

  ```csharp C# theme={null}
  var deviceId = "98dc7c66-045d-49cb-a62b-4bb431b0a9fa";
  var noiseThresholdAttempt = seam.NoiseThresholdsNoiseSensors.Create(
    deviceId: deviceId,
    startsDailyAt: "20:00:00[America/Los_Angeles]",
    endsDailyAt: "06:00:00[America/Los_Angeles]",
    noiseThresholdDecibels: 70
  );
  Type t = noiseThresholdAttempt.GetType();
  PropertyInfo[] props = t.GetProperties();
  foreach (var prop in props)
  {
    Console.WriteLine(prop.Name + ": " + prop.GetValue(noiseThresholdAttempt));
  }
  ```
</CodeGroup>

**Response:**

<CodeGroup>
  ```json JavaScript theme={null}
  {
    "action_attempt": {
      "status": "pending",
      "action_type": "CREATE_NOISE_THRESHOLD",
      "action_attempt_id": "5e24ef90-8043-44d8-89f9-9f7ae60ec390",
      "result": null,
      "error": null
    },
    "ok": true
  }
  ```

  ```json cURL theme={null}
  {
    "action_attempt": {
      "status": "pending",
      "action_type": "CREATE_NOISE_THRESHOLD",
      "action_attempt_id": "64130fb6-94ed-4268-a7e5-ccba4165fab8",
      "result": null,
      "error": null
    },
    "ok": true
  }
  ```

  ```json Python theme={null}
  NoiseThreshold(noise_threshold_id='1b64e4b6-4d5d-4416-acca-dc3b1cbc00cd',
                 device_id='98dc7c66-045d-49cb-a62b-4bb431b0a9fa',
                 name='builtin_quiet_hours',
                 noise_threshold_decibels=70,
                 starts_daily_at='20:00:00[America/Los_Angeles]',
                 ends_daily_at='06:00:00[America/Los_Angeles]',
                 noise_threshold_nrs=None)
  ```

  ```json C# theme={null}
  Status: pending
  ActionType: CREATE_NOISE_THRESHOLD
  ActionAttemptId: eb611597-64d2-4b1a-995b-fb00361922c6
  Result:
  Error:
  ```
</CodeGroup>

This threshold creates a noise threshold of 70 decibels from 20:00-06:00 PST called `builtin_quiet_hours`.

Once you have created a threshold, connect it to a webhook to log events.

### Best Practices

* For Minut devices, you can configure two thresholds—one for quiet hours and one for the rest of the day.
* For NoiseAware devices, you can configure as many thresholds as you want, provided that they do not overlap during daytime hours.

## Set Up Webhooks

You can set up webhooks in the [Seam Console](https://console.seam.co).

1. In the left-hand navigation pane of Seam Console, click **Webhooks**.

2. On the **Webhooks** page, click **+ Add Webhook**.

   <img alt="On the Webhooks page in the Seam Console, click + Add Webhook." />

3. In the **Create Webhook** dialog:
   1. Type your URL.
   2. Select the event types for which you want to receive events.
   3. Click **Create**.

The Seam Console displays the URL and secret for the newly-created webhook. To test your webhook, click **Test your webhook**.

## Monitor Events

Once you have configured your thresholds and webhooks, you can monitor events with the Seam API. The following sample shows how events look:

```json theme={null}
{
  "created_at": "2023-01-09T18:54:32.737Z",
  "device_id": "c1296d07-3e96-4ee9-8219-3cd33a09aa37",
  "event_id": "c1296d07-3e96-4ee9-8219-3cd33a09aa37",
  "event_type": "noise_sensors.noise_threshold_triggered",
  "minut_metadata": {},
  "noise_level_decibels": 50,
  "noise_level_nrs": 40,
  "noise_threshold_id": "c1296d07-3e96-4ee9-8219-3cd33a09aa37",
  "noise_threshold_name": "builtin_first_disturbance",
  "noiseaware_metadata": {}
}
```

For a detailed reference of event parameters, see [Events](/api/noise_sensors/noise_thresholds/events).


# Noise Sensors
Source: https://docs.seam.co/capability-guides/noise-sensors/index

Learn about managing noise sensors that detect noise levels that exceed configured thresholds in specific areas.

## What Is a Noise Sensor?

Noise sensors are devices that measure that sound level in a given area. You can use noise sensors to monitor noise levels remotely and receive notifications when the noise volume is too loud. The Seam API enables you to configure the noise thresholds of a noise sensor and receive events when a disturbance is detected.

## What Is a Threshold?

Thresholds represent the limits of noise tolerated at a property, which can be customized for each hour of the day. Each device has its own default thresholds, but you can use the API to modify them.

## Use Cases

* You can configure noise threshold default settings for a customer's portfolio or on a property-by-property basis. When a new noise sensor is added, you can use the Seam API to configure its noise thresholds automatically according to these defaults.
* You can react to noise disturbances by sending notifications to your users when a `noise_sensor.noise_threshold_triggered` event occurs.
* Seam provides prebuilt UI components for displaying information for a noise sensor. You can show the noise level, ways to configure noise thresholds, and the activity log of any noise events.

## **Best Practices**

While you can theoretically set noise thresholds to any decibel value, we have found that setting them within the following specific ranges lead to fewer false positives:

| Property Type | Decibels |
| ------------- | -------- |
| Apartment     | 50-70    |
| House         | 70-90    |
| Estate        | 80-100   |

## **Next Steps**

See the following topics:

* [Configuring Noise Threshold Settings](/capability-guides/noise-sensors/configure-noise-threshold-settings)
* [Noise Sensors API Reference](/api/noise_sensors/object)


# Reservation Automations
Source: https://docs.seam.co/capability-guides/reservation-automations

Learn how to automate access and climate around reservations.

Reservation Automations sync reservation and guest data with your access and climate systems. Instead of building custom workflows for check-in, mid-stay changes, and checkout, you send reservation data to Seam and device settings update automatically.

Built for short-term bookings—whether hotel stays, gym classes, coworking rooms, or event rentals—Reservation Automations ensure access and climate settings apply only during the reserved time.

***

### How it works

Reservation Automations follow the lifecycle of a reservation:

1. You create spaces and assign devices using [`/spaces/create`](/api/spaces/create).
2. You send reservation and guest data with `push_data`.
3. Seam applies the right access and climate settings at the right times.
4. Webhooks notify you when settings are issued, updated, or revoked.
5. If a reservation is canceled, you call `delete_data` to roll back device settings.

***

### Before you begin <a href="#before-you-begin" />

Set up these resources in your Seam workspace:

* [Customer](/capability-guides/customer-portals/index) – identify who the automation belongs to with a `customer_key`.
* [Spaces](../core-concepts/mapping-your-resources-to-seam-resources) – represent the real-world units your customer manages (i.e. *Room 101* in a hotel, *Studio 3* in a gym). Each space must be created via [`/spaces/create`](/api/spaces/create) with a `space_key` and assigned devices or entrances **before** you call `push_data`. Reservations reference these spaces by `space_key`.
* Devices or entrances – connect locks, thermostats, or ACS entrances to each space (e.g., assign the lock in Room 101 to the *Room 101* space). Use `device_ids` for smart locks and thermostats, or `acs_entrance_ids` for access control system entrances.
* Unique user identity emails – each `user_identity` you push must have a unique `email_address`. If an email already exists from a previous call, the reservation is silently skipped.

<Warning>
  Although `push_data` accepts a `spaces` array, it only creates a lightweight
  resource reference — it does **not** assign devices or entrances to the space.
  If you skip [`/spaces/create`](/api/spaces/create),
  the space will have no devices and automations will have nothing to configure.
  The call still returns `ok: true`, making this a silent failure. Always create
  spaces with device or entrance assignments first using `/spaces/create`.
</Warning>

<Check>
  You can also let customers configure their own accounts, spaces, and devices
  with [Customer Portals](/capability-guides/customer-portals/index).
</Check>

***

### 1. Create spaces with devices

Before pushing reservation data, create a space for each bookable unit using the [`/spaces/create`](/api/spaces/create) endpoint. Each space must have a `space_key` (your identifier) and at least one assigned device or entrance.

```bash theme={null}
curl -X POST \
  https://connect.getseam.com/spaces/create \
  -H "Authorization: Bearer $SEAM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Room 101",
    "space_key": "unit-101-key",
    "device_ids": ["YOUR_LOCK_DEVICE_ID"]
  }'
```

Use `device_ids` for smart locks and thermostats, or `acs_entrance_ids` for access control system entrances. You can include both if the space has multiple access points.

The `space_key` is what you reference in `push_data` reservations. Without it, `push_data` cannot match reservations to the space.

***

### 2. Customize automation settings

After enabling automations, you can configure how access credentials are issued for each reservation. These settings are available in **Console** > **Developer** > **Automations** under the access automation section.

**Access methods**

Choose which credential types to issue when a reservation is created. You must enable at least one.

| Method           | Description                                   |
| ---------------- | --------------------------------------------- |
| **PIN code**     | A numeric code the guest enters on a keypad.  |
| **Plastic card** | A physical card encoded for the lock.         |
| **Mobile key**   | A digital key delivered to the guest's phone. |

**Access method creation strategy**

Controls how many access methods are created per device when multiple types are enabled:

| Strategy                      | Behavior                                                |
| ----------------------------- | ------------------------------------------------------- |
| **First available** (default) | Creates only the first supported method on each device. |
| **First two available**       | Creates up to two supported methods on each device.     |
| **All available**             | Creates every supported method on each device.          |

**Card count**

The number of plastic cards to create per reservation. Only applies when the plastic card access method is enabled.

**Instant key max use count**

The maximum number of times a mobile key can be used. Only applies when the mobile key access method is enabled.

**Use guest phone last 4 digits as code**

When enabled, Seam will attempt to use the last 4 digits of the guest's phone number as the PIN code instead of generating a random one. The phone number is looked up from the user identity data you provide via `push_data`.

PIN code priority:

1. An explicit `preferred_code` on the reservation always takes precedence.
2. If no `preferred_code` is set and this option is enabled, Seam uses the last 4 digits of the guest's phone number.
3. If the phone number is unavailable or has fewer than 4 digits, Seam falls back to an auto-generated code.

<Info>
  The derived code is a best-effort preference, not a guarantee. If the code
  conflicts with a device's PIN constraints (for example, the code is already in
  use on that lock) Seam assigns an auto-generated code for that device and adds
  a relevant warning to the access grant.
</Info>

**Allow shared email and phone across guests**

When enabled, multiple guests can share the same email address or phone number. This is useful when the same person has multiple reservations or holds different roles.

<img alt="" />

### 3. Push reservation data

Use the `push_data` endpoint to send customer, user, and reservation data to Seam. Automations use this information to configure devices at the right times.

A **reservation** represents a time-bound assignment of a user to a space. This can be a hotel stay, a gym day pass, or a coworking member's conference room booking. Each reservation must include a unique `reservation_key`, which can be your system's identifier for that record. Seam uses this key to know whether it should create a new reservation, update an existing one, or remove it later with `delete_data`.

```bash theme={null}
curl -X POST \
  https://connect.getseam.com/customers/push_data \
  -H "Authorization: Bearer $SEAM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_key": "sample_customer_key",
    "user_identities": [
      {
        "user_identity_key": "user_789",
        "name": "John Doe",
        "email_address": "john@example.com"
      }
    ],
    "reservations": [
      {
        "reservation_key": "res_456",
        "user_identity_key": "user_789",
        "starts_at": "2025-08-12T19:47:27.490Z",
        "ends_at": "2025-08-14T19:47:27.490Z",
        "space_keys": ["unit-101-key"]
      }
    ]
  }'
```

* Call `push_data` with a new `reservation_key` to create a reservation.
* Call it again with the same `reservation_key` to update times or other details—Seam automatically reconfigures the device settings.

<Info>
  The `push_data` [API
  reference](/api/customers/push_data) also documents
  `access_grants` and `bookings` as alternative top-level keys. This guide uses
  `reservations`, which is the recommended key for short-term booking workflows.
  If you use `access_grants` instead, use `access_grant_keys` (not
  `reservation_keys`) when calling
  [`delete_data`](/api/customers/delete_data).
</Info>

***

### 4. Use webhooks to listen for updates

Configure webhooks in **Console** > **Developer** > **Webhooks** to get notified when automations apply or revoke settings.

**Key events:**

* `access_method.issued` – access created
* `access_method.reissued` – access updated
* `access_method.deleted` – access removed

Webhook payloads include the keys that triggered the event, letting you sync state with your application.

***

### 5. Delete data

The `delete_data` endpoint is optional but important. Use it when access or device settings should no longer apply—such as when:

* A hotel reservation is canceled
* A conference room reservation ends early
* A gym class is dropped
* An event reservation is called off

Calling `delete_data` removes the underlying reservation records, which tells automations to immediately roll back any device settings tied to them. This could mean revoking access, resetting thermostats, or clearing other applied states. Without cleanup, those settings may stay active longer than intended.

```bash theme={null}
curl -X POST \
  https://connect.getseam.com/customers/delete_data \
  -H "Authorization: Bearer $SEAM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "reservation_keys": ["res_456"],
    "user_identity_keys": ["user_789"]
  }'
```

* Pass a `reservation_key` to cancel a specific reservation and remove its device settings.
* Pass a `user_identity_key` to remove all device settings tied to a specific person.
* Pass a `customer_key` to offboard an entire customer and clear all their spaces, users, and settings.

***

### Troubleshooting

#### I called `push_data` and got `ok: true` but no access code was created

`push_data` returns a success response even when automations cannot act on the data. Check these common causes:

| Symptom                      | Cause                                            | Fix                                                                                                                                              |
| ---------------------------- | ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| No access code created       | Space does not exist or is missing a `space_key` | Create the space via [`/spaces/create`](/api/spaces/create) with a `space_key` and `device_ids` or `acs_entrance_ids` before calling `push_data` |
| No access code created       | No devices or entrances assigned to the space    | Add `device_ids` or `acs_entrance_ids` when creating the space, or update the space to include them                                              |
| Reservation silently skipped | Duplicate `email_address` on a `user_identity`   | Each user identity must have a unique email. Check **Console** → **Automation Runs** for `user_identity_email_or_phone_conflict` errors          |
| Automation did not run       | Automations not enabled                          | Go to **Console** → **Developer** → **Automations** and verify automations are enabled for your workspace                                        |

<Info>
  Check **Console** → **Automation Runs** for detailed error information. Errors
  like `user_identity_email_or_phone_conflict` are only visible there — they do
  not appear in the `push_data` response.
</Info>

***


# Seam Bridge
Source: https://docs.seam.co/capability-guides/seam-bridge

Use Seam Bridge to connect on-premises access systems to Seam.

## Overview

Seam Bridge is a lightweight app that brings your on-premises access system online—without exposing any ports to the public internet.

Install it on a computer in the same local network as your access system. Seam Bridge creates a secure tunnel between your on-premises system and Seam Cloud, handling all the encryption and authentication for you.

With Seam Bridge, you get the reliability of a local system, plus the flexibility of the cloud.

<Info>
  It is important to understand the difference between Seam Bridge and smart
  lock Wi-Fi bridges. Seam Bridge is specifically designed to connect
  on-premises access systems to the Seam platform. On the other hand, Smart lock
  Wi-Fi bridges enable remote management of smart lock devices that do not have
  integrated Wi-Fi connectivity. That is, a smart lock Wi-Fi bridge uses a
  short-range communication protocol, such as Bluetooth, to connect one or more
  locks to the internet through a property's local Wi-Fi network.
</Info>

***

## Getting Started

Download the Seam Bridge application onto an on-premises computer. Then, pair Seam Bridge with your Seam [workspace](/core-concepts/workspaces/index) and connect the on-premises access system to Seam. You install and pair Seam Bridge while you are connecting your on-premises access system to Seam. That is, the [Connect Webview](/core-concepts/connect-webviews/index) that you use to connect your on-premises access system to Seam walks you through the process of downloading and pairing Seam Bridge.

For detailed information, see the setup instructions within the [system integration guide](/device-and-system-integration-guides#access-control-systems) for your on-premises access system.

***

## **Download Seam Bridge**

In a web browser, go to [the Seam Bridge repo](https://www.seam.co/seam-bridge/releases/latest) and download the latest version of the Seam Bridge application for the appropriate operating system.

<img alt="Download the Seam Bridge application for your operating system." />

***

## System Setup Guides

Please refer to these guides to set up the Seam Bridge application.

<CardGroup>
  <Card title="Windows Setup" href="/capability-guides/seam-bridge/seam-bridge-setup-for-windows" />

  <Card title="macOS Setup" href="/capability-guides/seam-bridge/seam-bridge-setup-for-macos" />

  <Card title="Linux Setup" href="/capability-guides/seam-bridge/seam-bridge-setup-for-linux" />
</CardGroup>

***

## Troubleshooting Seam Bridge

If issues affect the connections between Seam Bridge, your on-premises access system, and the Seam platform, the Seam Bridge app displays status, error, and other information to help you understand and troubleshoot these issues.

The **Connected Systems** area displays the status of each connection. A green checkmark indicates a healthy connection.

The Seam Bridge app also displays communication errors at the top of the window.

<img
  alt="Seam Bridge displays information about the connections to on-premises
access systems."
/>

***

## Next Steps

Go to the setup instructions within the [system integration guide](/device-and-system-integration-guides#access-control-systems) for your on-premises access system. These instructions describe how to pair Seam Bridge with your workspace and then connect your on-premises access system to Seam through Seam Bridge.


# Seam Bridge Setup for Linux
Source: https://docs.seam.co/capability-guides/seam-bridge/seam-bridge-setup-for-linux

Step-by-step instructions for installing, launching, and configuring Seam Bridge on Linux.

## System Requirements

### Supported distributions

Ubuntu, Debian, Fedora, Arch, OpenSUSE, and most Linux desktops that include WebKitGTK.

### Runtime dependencies

WebKitGTK 3 or 4

1. Check if installed:

   ```bash theme={null}
   ldd ./seambridge | grep webkit
   ```

2. If not installed, the user must install (depending on distro):
   * **Ubuntu/Debian**

     ```bash theme={null}
     sudo apt install libwebkit2gtk-4.0-37
     ```

   * **Fedora**

     ```bash theme={null}
     sudo dnf install webkit2gtk3
     ```

   * **Arch**

     ```bash theme={null}
     sudo pacman -S webkit2gtk
     ```

### Minimum hardware

* 1 GB RAM
* \~150 MB disk space
* x64 architecture
* LAN Network access

***

## Run Seam Bridge

### Launch the app and allow required permissions

1. Open the downloaded Seam Bridge file.

2. If it does not open, you may need to mark it as executable.

   ```bash theme={null}
   chmod +x ./seambridge
   ```

3. Launch the app:

   ```
   ./seambridge
   ```

4. If the app does not start due to permissions, you may need to allow it through your system’s security settings:

   * Some Linux distributions block files downloaded from the internet.
   * If this happens, remove the quarantine attribute (if present):

     ```bash theme={null}
     xattr -d com.apple.quarantine ./seambridge
     ```

   *(On most Linux systems this won’t appear, but it’s safe to run.)*

5. If your Linux system prompts you to allow the app to access the network, approve the request so Seam Bridge can connect to your on-premises system.

6. Seam Bridge will launch.

***

### Complete Seam Bridge setup

1. Accept the **Terms of Service.**

2. Enter a name for the site that you are connecting using Seam Bridge—for example, `My Site`—and then click **Start pairing**.

   <img alt="" />

3. Seam Bridge displays a **Pairing code.** Use this code when connecting Seam Bridge to your workspace. Return to this window whenever a new pairing code is requested.

   <img alt="" />

***

### Set up Seam Bridge to reboot on restart

Use `systemd` to keep an app running on Linux. It supervises the process, restarts it on crash, and handles boot startup.

#### Create a systemd service file

1. Open Terminal.

2. Create the service file:\\

   ```bash theme={null}
   sudo nano /etc/systemd/system/SeamBridge.service
   ```

3. Add this template:

   ```
   [Unit]
   Description=Seam Bridge - Keep Running
   After=network.target

   [Service]
   ExecStart=/usr/local/bin/SeamBridge.exe
   Restart=always
   RestartSec=3
   WorkingDirectory=/usr/local/bin
   User=ubuntu
   Environment=NODE_ENV=production

   [Install]
   WantedBy=multi-user.target
   ```

4. Replace paths and `User` as needed.

#### Enable and start the service

1. Within Terminal, run the following commands:

```
sudo systemctl daemon-reload
sudo systemctl enable SeamBridge.service
sudo systemctl start SeamBridge.service
```

#### Verify status

1. Run the following command in Terminal to confirm that the service is running:

```
systemctl status SeamBridge.service
```

You should see the service running and supervised.

#### Test auto-restart

1. Kill the process manually with `pkill SeamBridge`.
2. `systemd` should restart it immediately.


# Seam Bridge Setup for macOS
Source: https://docs.seam.co/capability-guides/seam-bridge/seam-bridge-setup-for-macos

Step-by-step instructions for installing, launching, and configuring Seam Bridge on macOS.

### System Requirements

* **Supported versions:**
  * macOS 10.13 High Sierra or later
  * Intel and Apple Silicon supported
* **Minimum hardware**
  * 1 GB RAM
  * \~200–300 MB disk space depending on bundle size
* **Network:** LAN connection required

***

## Run Seam Bridge

### Unzip and launch the app

1. Double click on the zipped file to unzip the file.
2. Try opening the SeamBridge.app by double-clicking it.
3. macOS will show a *“Seam Bridge" Not Opened* dialog.\\
   <img alt="" />
4. Select **Done** to close the dialog.

### Approve the app in System Settings

1. Open **System Settings**.
2. Go to **Privacy & Security**.
3. Scroll to the bottom of the page.
4. Look for a message that says:
   * *“Seam Bridge was blocked to protect your Mac.”*
5. Select **Open Anyway**.
6. Select **Open Anyway** in the popup.

<div>
  <img alt="" />

  <img alt="" />
</div>

***

### Complete Seam Bridge setup

1. Accept the **Terms of Service.**

2. Enter a name for the site that you are connecting using Seam Bridge—for example, `My Site`—and then click **Start pairing**.

   <img alt="" />

3. Seam Bridge displays a **Pairing code.** Use this code when connecting Seam Bridge to your workspace. Return to this window whenever a new pairing code is requested.

   <img alt="" />

***

### Set up Seam Bridge to reboot on restarts

Use `launchd` to keep the Seam Bridge running on macOS. A LaunchAgent restarts the app if it crashes and starts it whenever the user logs in.

#### Create and Launch the LaunchAgent file

1. Open **Terminal**.

2. Create a plist file in your user `LaunchAgents` directory:

   ```bash theme={null}
   mkdir -p ~/Library/LaunchAgents
   nano ~/Library/LaunchAgents/com.seambridge.keepalive.plist
   ```

3. Paste this template:

   ```xml theme={null}
   <?xml version="1.0" encoding="UTF-8"?>
   <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
   <plist version="1.0">
     <dict>
       <key>Label</key>
       <string>com.myapp.keepalive</string>

       <key>ProgramArguments</key>
       <array>
         <string>/path/to/app/SeamBridge.app/Contents/MacOS/SeamBridge</string>
       </array>

       <key>KeepAlive</key>
       <true/>

       <key>RunAtLoad</key>
       <true/>
     </dict>
   </plist>

   ```

4. Replace `/path/to/app` with the actual path to your binary/script. Keep the `/Contents/MacOS/SeamBridge` path at the end.

5. To save your changes in Nano:
   * `Ctrl X` to Exit.
   * `Y` to save changes.
   * Confirm the file name and click **Enter**.

6. Within terminal, paste the following command to launch the launch agent:

   ```bash theme={null}
   launchctl load ~/Library/LaunchAgents/com.seambridge.keepalive.plist
   ```

#### Test the setup

1. Kill the app manually.
2. `launchd` should restart it automatically.
3. Restart your Mac and confirm the app launches on login.

#### Prevent sleep from killing your app

1. Go to **System Settings** → **Battery**.
2. Set **Turn display off** as desired but disable **sleep while plugged in**.

***


# Seam Bridge Setup for Windows
Source: https://docs.seam.co/capability-guides/seam-bridge/seam-bridge-setup-for-windows

Step-by-step instructions for installing, launching, and configuring Seam Bridge on Windows.

### System Requirements

* **Supported versions:**
  * Windows 10/11 AMD64/ARM64
* **Minimum hardware:**
  * 1 GB RAM
  * \~150 MB disk space
  * x64 architecture
* **Network:** LAN connection required

***

## Run Seam Bridge

### Launch the app and allow required permissions

1. Open the downloaded executable file.
2. If you are using a Windows computer running Microsoft Defender, you may need to allow Windows to run the Seam Bridge app.
   1. In the **Windows protected your PC** dialog, click **More info**.
   2. Click **Run anyway**.
3. If you are using a Windows computer, you may need to allow public networks to access the Seam Bridge app.
   1. In the **Do you want to allow public and private networks to access this app?** dialog, click **Show more**.
   2. Make sure that the **Public networks** and **Private networks** checkboxes are selected.
   3. Click **Allow**.
4. The Seam Bridge app will launch.

***

### Complete Seam Bridge setup

1. Accept the **Terms of Service.**

2. Enter a name for the site that you are connecting using Seam Bridge—for example, `My Site`—and then click **Start pairing**.

   <img alt="Seam Bridge Welcome screen" />

3. Seam Bridge displays a **Pairing code.** Use this code when connecting Seam Bridge to your workspace. Return to this window whenever a new pairing code is requested.

   <img alt="Seam Bridge pairing code screen" />

***

### Set up Seam Bridge to Reboot on Restart

Use Task Scheduler to auto-start your app and restart it if it fails.

#### **Open Task Scheduler**

1. Press **Win** key and type **Task Scheduler**.
2. Open **Task Scheduler**.

#### **Create a new task**

1. In the right-hand **Actions** pane, select **Create Task…** (not *Create Basic Task*).

   <img alt="Task Scheduler - Create Task option" />

2. In the **General** tab:

   * Name: e.g. `Seam Bridge - Keep Running`.
   * (Recommended) Check **Run when user is logged on.**
   * (If needed) Check **Run with highest privileges**.
   * Pick the right OS under **Configure for** (e.g. Windows 10/11).

   <img alt="Task Properties - General tab" />

3. **Set up trigger to launch at start up**

   * Go to the **Triggers** tab and click **New….**
   * Set **Begin the task** to **At startup**.
   * Make sure **Enabled** is checked, then click **OK**.

   <img alt="Task Properties - Triggers tab, At startup trigger" />

4. **Add another trigger to relaunch Seam Bridge if it closes**

   1. In the **Triggers** tab, select **New…**
   2. Set **Begin the task** to **On a schedule**
   3. Under **Settings**, select:
      * Daily
      * Recur every: 1 day
   4. Under **Advanced settings**, enable:
      * **Repeat task every:** 5 minutes
      * **For a duration of:** 1 day
      * Ensure **Enabled** is checked
   5. Select **OK** to save the trigger.

   <img alt="Task Properties - Triggers tab, scheduled trigger" />

5. **Configure launching the Seam Bridge app**

   * Go to the **Actions** tab and click **New….**
   * Set **Action** to **Start a program**.
   * In **Program/script**, select your app's .exe or script:
     * Example: `C:\Users\user\Downloads\SeamBridge.exe`
   * Click **OK**.

   <img alt="Task Properties - Actions tab" />

6. **Configure settings for relaunching**

   1. Go to the **Settings** tab.
   2. Enable:
      * **Allow task to be run on demand**.
      * **If the task fails, restart every:** `1 minute`, for a duration of: `Indefinitely` or a reasonable number of attempts (> 100).
   3. Uncheck **Stop the task if it runs longer than:**.
   4. Check **If the running task does not end when requested, force it to stop**.

   <img alt="Task Properties - Settings tab" />

7. **Prevent power settings from stopping the task**

   * Go to the **Conditions** tab.
   * If this is a plugged-in machine (kiosk/server style):
     * Uncheck **Start the task only if the computer is on AC power**.
     * Uncheck **Stop if the computer switches to battery power**.

   <img alt="Task Properties - Conditions tab" />

#### **Save and test**

1. Click **OK** to save the task.
2. If prompted, enter the user's password so Windows can run it in the background.
3. In Task Scheduler, right-click your new task and select **Run**.
4. Confirm the app starts as expected.
5. Restart the computer and verify the app launches automatically.

***


# Setting the Current HVAC and Fan Mode Settings
Source: https://docs.seam.co/capability-guides/thermostats/configure-current-climate-settings

Learn how to configure the current climate settings on a thermostat.

You can use the following Seam API "imperative" endpoints to set the current HVAC and fan mode settings for a connected thermostat, individually:

* [`/thermostats/heat`](/api/thermostats/heat)
* [`/thermostats/cool`](/api/thermostats/cool)
* [`/thermostats/heat_cool`](/api/thermostats/heat_cool)
* [`/thermostats/off`](/api/thermostats/off)
* [`/thermostats/set_fan_mode`](/api/thermostats/set_fan_mode)

<Info>
  You can also use the
  [`/thermostats/set_hvac_mode`](/api/thermostats/set_hvac_mode)
  endpoint to set a thermostat to the desired HVAC mode, including `heat`,
  `cool`, `heat_cool`, `eco` (for Google Nest), or `off`, depending on the
  capabilities of the device. For `heat`, `cool`, and `heat_cool`, also specify
  the desired heating and cooling set points, as appropriate.
</Info>

Note that it's important to check the capabilities of a thermostat before attempting to use an imperative endpoint. For example, if a thermostat is attached to an HVAC system that does not have cooling capabilities, you cannot use `/thermostats/cool` or `/thermostats/heat_cool`. To check the capabilities of a thermostat, retrieve the thermostat and confirm the [relevant capability flags](#before-you-begin-confirm-capabilities).

These imperative operations return an [action attempt](../../core-concepts/action-attempts) that enables you to track the progress of the action. Poll this action attempt, until the action completes.

Further, Seam emits a [`thermostat.temperature_reached_set_point` event](/api/thermostats/events#thermostat-temperature_reached_set_point) when the thermostat reports a temperature within 1° Celsius of the heating or cooling temperature that you requested.

***

## HVAC Settings

When you use an imperative endpoint to set the HVAC settings for a thermostat, you specify the [HVAC mode](../../capability-guides/thermostats/understanding-thermostat-concepts/hvac-mode) and the desired [set points](../../capability-guides/thermostats/understanding-thermostat-concepts/set-points) in Fahrenheit or Celsius.

To set the HVAC mode and set points, issue a thermostat [`heat`](#set-a-thermostat-to-heat-mode), [`cool`](#set-a-thermostat-to-cool-mode), [`heat_cool`](#set-a-thermostat-to-heat-cool-mode), `eco` (for Google Nest), or [`off`](#turn-off-heating-and-cooling) request and include the desired set points in the body of the request.

***

## Fan Mode Settings

Seam supports the following fan mode settings:

<table>
  <thead>
    <tr>
      <th>Fan mode</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        <code>on</code>
      </td>

      <td>
        The fan runs all the time, regardless of whether the HVAC system is
        cooling or heating.
      </td>
    </tr>

    <tr>
      <td>
        <code>auto</code>
      </td>

      <td>
        The fan runs whenever the HVAC system is cooling or heating but does not
        run at other times.
      </td>
    </tr>

    <tr>
      <td>
        <code>circulate</code>
      </td>

      <td>
        The fan runs for a specific number of minutes each hour, regardless of
        whether the HVAC system is cooling or heating. To find out whether a
        thermostat supports this setting, view its

        <a href="/capability-guides/thermostats">
          <code>device.properties.available\_fan\_mode\_settings</code>
        </a>

        property.
      </td>
    </tr>
  </tbody>
</table>

***

## Process Overview

To configure and then verify a climate setting on a thermostat, perform the following steps:

1. Confirm the capabilities of the thermostat.

   See [Before You Begin: Confirm Capabilities](#before-you-begin-confirm-capabilities).

2. Execute the imperative climate setting request.\
   See the following instructions:
   * [Set a Thermostat to Heat Mode](#set-a-thermostat-to-heat-mode)
   * [Set a Thermostat to Cool Mode](#set-a-thermostat-to-cool-mode)
   * [Set a Thermostat to Heat-Cool Mode](#set-a-thermostat-to-heat-cool-mode)
   * [Turn off Heating and Cooling](#turn-off-heating-and-cooling)
   * [Set the Fan Mode Setting](#set-the-fan-mode-setting)

3. Poll the action attempt.\
   See [Poll the Action Attempt](#poll-the-action-attempt).

4. If desired, configure a webhook to watch for a `thermostat.temperature_reached_set_point` event that indicates that the thermostat has reported a temperature within 1° Celsius of the heating or cooling [set point](../../capability-guides/thermostats/understanding-thermostat-concepts/set-points) that you requested.\
   See [Webhooks](../../developer-tools/webhooks).

***

## Before You Begin: Confirm Capabilities

Before you attempt to set the HVAC or fan mode settings for a thermostat, 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](../../capability-guides/device-and-system-capabilities#capability-flags) for the device:

* `device.can_hvac_heat`
* `device.can_hvac_cool`
* `device.can_hvac_heat_cool`
* `device.can_turn_off_hvac`

Use the [`/devices/get`](/api/devices/get) endpoint 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 perform the imperative thermostat action.

If the relevant capability flag is `false` or not present, you can view the [properties](/api/devices/object) of the device, [errors or warnings](/api/devices/errors) for the device, and [events](/api/devices/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.

**Request:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  await seam.devices.get({
    device_id: 'a4b775e3-feb2-4c6b-8e78-a73ec2d70b61',
  })
  ```

  ```bash cURL theme={null}
  # Use GET or POST.
  curl -X 'GET' \
    'https://connect.getseam.com/devices/get' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d '{
    "device_id": "a4b775e3-feb2-4c6b-8e78-a73ec2d70b61"
  }'
  ```

  ```python Python theme={null}
  seam.devices.get(
    device_id = "a4b775e3-feb2-4c6b-8e78-a73ec2d70b61"
  )
  ```

  ```ruby Ruby theme={null}
  # Coming soon!
  ```

  ```php PHP theme={null}
  $seam->devices->get(
    device_id: "a4b775e3-feb2-4c6b-8e78-a73ec2d70b61"
  );
  ```

  ```csharp C# theme={null}
  // Coming soon!
  ```
</CodeGroup>

**Response:**

<CodeGroup>
  ```json JavaScript theme={null}
  {
    device_id: 'a4b775e3-feb2-4c6b-8e78-a73ec2d70b61',
    can_hvac_heat: true,      // You can use seam.thermostats.heat() on this device.
    can_hvac_cool: true,      // You can use seam.thermostats.cool() on this device.
    can_hvac_heat_cool: true, // You can use seam.thermostats.heatCool() on this device.
    can_turn_off_hvac: true,  // You can use seam.thermostats.off() on this device.
    ...
  }
  ```

  ```json cURL theme={null}
  {
    "device": {
      "device_id": "a4b775e3-feb2-4c6b-8e78-a73ec2d70b61",
      "can_hvac_heat": true,      // You can use /thermostats/heat on this device.
      "can_hvac_cool": true,      // You can use /thermostats/cool on this device.
      "can_hvac_heat_cool": true, // You can use /thermostats/heat_cool on this device.
      "can_turn_off_hvac": true,  // You can use /thermostats/off on this device.
      ...
    },
    "ok": true
  }
  ```

  ```json Python theme={null}
  Device(
    device_id='a4b775e3-feb2-4c6b-8e78-a73ec2d70b61',
    can_hvac_heat=True,      // You can use seam.thermostats.heat() on this device.
    can_hvac_cool=True,      // You can use seam.thermostats.cool() on this device.
    can_hvac_heat_cool=True, // You can use seam.thermostats.heat_cool() on this device.
    can_turn_off_hvac=True,  // You can use seam.thermostats.off() on this device.
    ...
  )
  ```

  ```json Ruby theme={null}
  # Coming soon!
  ```

  ```json PHP theme={null}
  {
    "device_id": "a4b775e3-feb2-4c6b-8e78-a73ec2d70b61",
    "can_hvac_heat": true,      // You can use $seam->thermostats->heat() on this device.
    "can_hvac_cool": true,      // You can use $seam->thermostats->cool() on this device.
    "can_hvac_heat_cool": true, // You can use $seam->thermostats->heat_cool() on this device.
    "can_turn_off_hvac": true,  // You can use $seam->thermostats->off() on this device.
    ...
  }
  ```

  ```json C# theme={null}
  // Coming soon!
  ```
</CodeGroup>

***

## Set a Thermostat to Heat Mode

You can [set a thermostat to heat mode](/api/thermostats/heat) or use the [`/thermostats/set_hvac_mode`](/api/thermostats/set_hvac_mode) endpoint, and specify a desired heating [set point](../../capability-guides/thermostats/understanding-thermostat-concepts/set-points) temperature. By establishing the set point, the thermostat activates the associated heating system to maintain the specified temperature.

Issue the thermostat `heat` request, providing the `device_id` of the thermostat and the `heating_set_point_celsius` or `heating_set_point_fahrenheit`.

**Request:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  // Get the thermostat.
  const thermostat = await seam.devices.get({
    device_id: 'a4b775e3-feb2-4c6b-8e78-a73ec2d70b61',
  })

  // Confirm that the thermostat supports heat mode.
  if (thermostat.can_hvac_heat) {
    // Perform the heat request.
    await seam.thermostats.heat({
      device_id: thermostat.device_id,
      heating_set_point_celsius: 20,
    })
  }
  ```

  ```bash cURL theme={null}
  # Get the thermostat.
  thermostat=$(
    # Use GET or POST.
    curl -X 'GET' \
      'https://connect.getseam.com/devices/get' \
      -H 'accept: application/json' \
      -H "Authorization: Bearer ${SEAM_API_KEY}" \
      -H 'Content-Type: application/json' \
      -d '{
        "device_id": "a4b775e3-feb2-4c6b-8e78-a73ec2d70b61"
    }')

  # Confirm that the thermostat supports heat mode.
  if  $(jq -r '.device.can_hvac_heat' <<< ${thermostat}); then \
    # Perform the heat request.
    curl -X 'POST' \
      'https://connect.getseam.com/thermostats/heat' \
      -H 'accept: application/json' \
      -H "Authorization: Bearer ${SEAM_API_KEY}" \
      -H 'Content-Type: application/json' \
      -d "{
        \"device_id\": \"$(jq -r '.device.device_id' <<< ${thermostat})\",
        \"heating_set_point_celsius\": 20
    }";
  fi
  ```

  ```python Python theme={null}
  # Get the thermostat.
  thermostat = seam.devices.get(
    device_id = "a4b775e3-feb2-4c6b-8e78-a73ec2d70b61"
  )

  # Confirm that the thermostat supports heat mode.
  if thermostat.can_hvac_heat:
    # Perform the heat request.
    seam.thermostats.heat(
      device_id = thermostat.device_id,
      heating_set_point_celsius = 20
    )
  ```

  ```ruby Ruby theme={null}
  // Get the thermostat.
  thermostat = seam.devices.get({
    device_id: "a4b775e3-feb2-4c6b-8e78-a73ec2d70b61"
  });

  # Confirm that the thermostat supports heat mode.
  if (thermostat.can_hvac_heat)
    # Perform the heat request.
    seam.thermostats.heat(
      device_id: thermostat.device_id,
      heating_set_point_celsius: 20
    )
  end
  ```

  ```php PHP theme={null}
  // Get the thermostat.
  $thermostat = $seam->devices->get(
    device_id: "a4b775e3-feb2-4c6b-8e78-a73ec2d70b61"
  );

  // Confirm that the thermostat supports heat mode.
  if ($thermostat->can_hvac_heat) {
    // Perform the heat request.
    $seam->thermostats->heat(
      device_id: $thermostat->device_id,
      heating_set_point_celsius: 20
    );
  }
  ```

  ```java C# theme={null}
  // Coming soon!
  ```
</CodeGroup>

**Response:**

<CodeGroup>
  ```json JavaScript theme={null}
  {
    "status": "success",
    "action_attempt_id": "97125745-15d9-4970-b5be-c34ec3ce1c81",
    "action_type": "SET_HVAC_MODE",
    "result": {},
    "error": null
  }
  ```

  ```json cURL theme={null}
  {
    "action_attempt": {
      "status": "pending",
      "action_type": "SET_HVAC_MODE",
      "action_attempt_id": "97125745-15d9-4970-b5be-c34ec3ce1c81",
      "result": null,
      "error": null
    },
    "ok": true
  }
  ```

  ```json Python theme={null}
  ActionAttempt(
    action_attempt_id='97125745-15d9-4970-b5be-c34ec3ce1c81',
    action_type='SET_HVAC_MODE',
    status='success',
    result={},
    error=None
  )
  ```

  ```json Ruby theme={null}
  <Seam::Resources::ActionAttempt:0x005f0
    status="success"
    action_type="SET_HVAC_MODE"
    action_attempt_id="97125745-15d9-4970-b5be-c34ec3ce1c81"
    result={}
    error=nil>
  ```

  ```json PHP theme={null}
  {
    "status": "success",
    "action_attempt_id": "97125745-15d9-4970-b5be-c34ec3ce1c81",
    "action_type": "SET_HVAC_MODE",
    "result": {},
    "error": null
  }
  ```

  ```json C# theme={null}
  // Coming soon!
  ```
</CodeGroup>

***

## Set a Thermostat to Cool Mode

You can [set a thermostat to cool mode](/api/thermostats/cool) or use the [`/thermostats/set_hvac_mode`](/api/thermostats/set_hvac_mode) endpoint, and specify a desired cooling [set point](../../capability-guides/thermostats/understanding-thermostat-concepts/set-points) temperature. By establishing the set point, the thermostat activates the associated cooling system to maintain the specified temperature.

Issue the thermostat `cool` request, providing the `device_id` of the thermostat and the `cooling_set_point_celsius` or `cooling_set_point_fahrenheit`.

**Request:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  // Get the thermostat.
  const thermostat = await seam.devices.get({
    device_id: 'a4b775e3-feb2-4c6b-8e78-a73ec2d70b61',
  })

  // Confirm that the thermostat supports cool mode.
  if (thermostat.can_hvac_cool) {
    // Perform the cool request.
    await seam.thermostats.cool({
      device_id: thermostat.device_id,
      cooling_set_point_celsius: 25,
    })
  }
  ```

  ```bash cURL theme={null}
  # Get the thermostat.
  thermostat=$(
    # Use GET or POST.
    curl -X 'GET' \
      'https://connect.getseam.com/devices/get' \
      -H 'accept: application/json' \
      -H "Authorization: Bearer ${SEAM_API_KEY}" \
      -H 'Content-Type: application/json' \
      -d '{
        "device_id": "a4b775e3-feb2-4c6b-8e78-a73ec2d70b61"
    }')

  # Confirm that the thermostat supports cool mode.
  if  $(jq -r '.device.can_hvac_cool' <<< ${thermostat}); then \
    # Perform the cool request.
    curl -X 'POST' \
      'https://connect.getseam.com/thermostats/cool' \
      -H 'accept: application/json' \
      -H "Authorization: Bearer ${SEAM_API_KEY}" \
      -H 'Content-Type: application/json' \
      -d "{
        \"device_id\": \"$(jq -r '.device.device_id' <<< ${thermostat})\",
        \"cooling_set_point_celsius\": 25
    }";
  fi
  ```

  ```python Python theme={null}
  # Get the thermostat.
  thermostat = seam.devices.get(
    device_id = "a4b775e3-feb2-4c6b-8e78-a73ec2d70b61"
  )

  # Confirm that the thermostat supports cool mode.
  if thermostat.can_hvac_cool:
    # Perform the cool request.
    seam.thermostats.cool(
      device_id = thermostat.device_id,
      cooling_set_point_celsius = 25
    )
  ```

  ```ruby Ruby theme={null}
  // Get the thermostat.
  thermostat = seam.devices.get({
    device_id: "a4b775e3-feb2-4c6b-8e78-a73ec2d70b61"
  });

  # Confirm that the thermostat supports cool mode.
  if (thermostat.can_hvac_cool)
    # Perform the cool request.
    seam.thermostats.cool(
      device_id: thermostat.device_id,
      cooling_set_point_celsius: 25
    )
  end
  ```

  ```php PHP theme={null}
  // Get the thermostat.
  $thermostat = $seam->devices->get(
    device_id: "a4b775e3-feb2-4c6b-8e78-a73ec2d70b61"
  );

  // Confirm that the thermostat supports cool mode.
  if ($thermostat->can_hvac_cool) {
    // Perform the cool request.
    $seam->thermostats->cool(
      device_id: $thermostat->device_id,
      cooling_set_point_celsius: 25
    );
  }
  ```

  ```csharp C# theme={null}
  // Coming soon!
  ```
</CodeGroup>

**Response:**

<CodeGroup>
  ```json JavaScript theme={null}
  {
    "status": "success",
    "action_attempt_id": "87478724-0e30-4fed-9f2a-456971b7b04f",
    "action_type": "SET_HVAC_MODE",
    "result": {},
    "error": null
  }
  ```

  ```json cURL theme={null}
  {
    "action_attempt": {
      "status": "pending",
      "action_type": "SET_HVAC_MODE",
      "action_attempt_id": "87478724-0e30-4fed-9f2a-456971b7b04f",
      "result": null,
      "error": null
    },
    "ok": true
  }
  ```

  ```json Python theme={null}
  ActionAttempt(
    action_attempt_id='87478724-0e30-4fed-9f2a-456971b7b04f',
    action_type='SET_HVAC_MODE',
    status='success',
    result={},
    error=None
  )
  ```

  ```json Ruby theme={null}
  <Seam::Resources::ActionAttempt:0x005f0
    status="success"
    action_type="SET_HVAC_MODE"
    action_attempt_id="87478724-0e30-4fed-9f2a-456971b7b04f"
    result={}
    error=nil>
  ```

  ```json PHP theme={null}
  {
    "status": "success",
    "action_attempt_id": "87478724-0e30-4fed-9f2a-456971b7b04f",
    "action_type": "SET_HVAC_MODE",
    "result": {},
    "error": null
  }
  ```

  ```json C# theme={null}
  // Coming soon!
  ```
</CodeGroup>

***

## Set a Thermostat to Heat-Cool Mode

You can [set a thermostat to heat-cool (also known as "auto") mode](/api/thermostats/heat_cool) or use the [`/thermostats/set_hvac_mode`](/api/thermostats/set_hvac_mode) endpoint, and specify desired [set point](../../capability-guides/thermostats/understanding-thermostat-concepts/set-points) temperatures for both heating and cooling. By establishing the set points, the thermostat activates the associated heating and cooling systems as needed to maintain the specified temperature range.

Issue the thermostat `heat_cool` request, providing the `device_id` of the thermostat and the following set points:

* `heating_set_point_celsius` or `heating_set_point_fahrenheit`
* `cooling_set_point_celsius` or `cooling_set_point_fahrenheit`

**Request:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  // Get the thermostat.
  const thermostat = await seam.devices.get({
    device_id: 'a4b775e3-feb2-4c6b-8e78-a73ec2d70b61',
  })

  // Confirm that the thermostat supports heat-cool mode.
  if (thermostat.can_hvac_heat_cool) {
    // Perform the heatCool request.
    await seam.thermostats.heatCool({
      device_id: thermostat.device_id,
      heating_set_point_celsius: 20,
      cooling_set_point_celsius: 25,
    })
  }
  ```

  ```bash cURL theme={null}
  # Get the thermostat.
  thermostat=$(
    # Use GET or POST.
    curl -X 'GET' \
      'https://connect.getseam.com/devices/get' \
      -H 'accept: application/json' \
      -H "Authorization: Bearer ${SEAM_API_KEY}" \
      -H 'Content-Type: application/json' \
      -d '{
        "device_id": "a4b775e3-feb2-4c6b-8e78-a73ec2d70b61"
    }')

  # Confirm that the thermostat supports heat-cool mode.
  if  $(jq -r '.device.can_hvac_heat_cool' <<< ${thermostat}); then \
    # Perform the heat_cool request.
    curl -X 'POST' \
      'https://connect.getseam.com/thermostats/heat_cool' \
      -H 'accept: application/json' \
      -H "Authorization: Bearer ${SEAM_API_KEY}" \
      -H 'Content-Type: application/json' \
      -d "{
        \"device_id\": \"$(jq -r '.device.device_id' <<< ${thermostat})\",
        \"heating_set_point_celsius\": 20,
        \"cooling_set_point_celsius\": 25
    }";
  fi
  ```

  ```python Python theme={null}
  # Get the thermostat.
  thermostat = seam.devices.get(
    device_id = "a4b775e3-feb2-4c6b-8e78-a73ec2d70b61"
  )

  # Confirm that the thermostat supports heat-cool mode.
  if thermostat.can_hvac_heat_cool:
    # Perform the heat_cool request.
    seam.thermostats.heat_cool(
      device_id = thermostat.device_id,
      heating_set_point_celsius = 20,
      cooling_set_point_celsius = 25
    )
  ```

  ```ruby Ruby theme={null}
  // Get the thermostat.
  thermostat = seam.devices.get({
    device_id: "a4b775e3-feb2-4c6b-8e78-a73ec2d70b61"
  });

  # Confirm that the thermostat supports heat-cool mode.
  if (thermostat.can_hvac_heat_cool)
    # Perform the heat_cool request.
    seam.thermostats.heat_cool(
      device_id: thermostat.device_id,
      heating_set_point_celsius: 20,
      cooling_set_point_celsius: 25
    )
  end
  ```

  ```php PHP theme={null}
  // Get the thermostat.
  $thermostat = $seam->devices->get(
    device_id: "a4b775e3-feb2-4c6b-8e78-a73ec2d70b61"
  );

  // Confirm that the thermostat supports heat-cool mode.
  if ($thermostat->can_hvac_heat_cool) {
    // Perform the heat_cool request.
    $seam->thermostats->heat_cool(
      device_id: $thermostat->device_id,
      heating_set_point_celsius: 20,
      cooling_set_point_celsius: 25
    );
  }
  ```

  ```csharp C# theme={null}
  // Coming soon!
  ```
</CodeGroup>

**Response:**

<CodeGroup>
  ```json JavaScript theme={null}
  {
    "status": "success",
    "action_attempt_id": "8050ec59-7f29-4d0d-9842-dedaf304740d",
    "action_type": "SET_HVAC_MODE",
    "result": {},
    "error": null
  }
  ```

  ```json cURL theme={null}
  {
    "action_attempt": {
      "status": "pending",
      "action_type": "SET_HVAC_MODE",
      "action_attempt_id": "8050ec59-7f29-4d0d-9842-dedaf304740d",
      "result": null,
      "error": null
    },
    "ok": true
  }
  ```

  ```json Python theme={null}
  ActionAttempt(
    action_attempt_id='8050ec59-7f29-4d0d-9842-dedaf304740d',
    action_type='SET_HVAC_MODE',
    status='success',
    result={},
    error=None
  )
  ```

  ```json Ruby theme={null}
  <Seam::Resources::ActionAttempt:0x005f0
    status="success"
    action_type="SET_HVAC_MODE"
    action_attempt_id="8050ec59-7f29-4d0d-9842-dedaf304740d"
    result={}
    error=nil>
  ```

  ```json PHP theme={null}
  {
    "status": "success",
    "action_attempt_id": "8050ec59-7f29-4d0d-9842-dedaf304740d",
    "action_type": "SET_HVAC_MODE",
    "result": {},
    "error": null
  }
  ```

  ```json C# theme={null}
  // Coming soon!
  ```
</CodeGroup>

***

## Turn off Heating and Cooling

You can [set a thermostat to "off" mode](/api/thermostats/off) or use the [`/thermostats/set_hvac_mode`](/api/thermostats/set_hvac_mode) endpoint, which deactivates the associated heating and cooling systems. In this state, the thermostat does not regulate indoor temperatures.

Issue the thermostat `off` request, providing the `device_id` of the thermostat.

**Request:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  // Get the thermostat.
  const thermostat = await seam.devices.get({
    device_id: 'a4b775e3-feb2-4c6b-8e78-a73ec2d70b61',
  })

  // Confirm that the thermostat supports off mode.
  if (thermostat.can_turn_off_hvac) {
    // Perform the off request.
    await seam.thermostats.off({
      device_id: thermostat.device_id,
    })
  }
  ```

  ```bash cURL theme={null}
  # Get the thermostat.
  thermostat=$(
    # Use GET or POST.
    curl -X 'GET' \
      'https://connect.getseam.com/devices/get' \
      -H 'accept: application/json' \
      -H "Authorization: Bearer ${SEAM_API_KEY}" \
      -H 'Content-Type: application/json' \
      -d '{
        "device_id": "a4b775e3-feb2-4c6b-8e78-a73ec2d70b61"
    }')

  # Confirm that the thermostat supports off mode.
  if  $(jq -r '.device.can_turn_off_hvac' <<< ${thermostat}); then \
    # Perform the off request.
    curl -X 'POST' \
      'https://connect.getseam.com/thermostats/off' \
      -H 'accept: application/json' \
      -H "Authorization: Bearer ${SEAM_API_KEY}" \
      -H 'Content-Type: application/json' \
      -d "{
        \"device_id\": \"$(jq -r '.device.device_id' <<< ${thermostat})\"
    }";
  fi
  ```

  ```python Python theme={null}
  # Get the thermostat.
  thermostat = seam.devices.get(
    device_id = "a4b775e3-feb2-4c6b-8e78-a73ec2d70b61"
  )

  # Confirm that the thermostat supports off mode.
  if thermostat.can_turn_off_hvac:
    # Perform the off request.
    seam.thermostats.off(
      device_id = thermostat.device_id
    )
  ```

  ```ruby Ruby theme={null}
  // Get the thermostat.
  thermostat = seam.devices.get({
    device_id: "a4b775e3-feb2-4c6b-8e78-a73ec2d70b61"
  });

  # Confirm that the thermostat supports off mode.
  if (thermostat.can_turn_off_hvac)
    # Perform the off request.
    seam.thermostats.off(
      device_id: thermostat.device_id
    )
  end
  ```

  ```php PHP theme={null}
  // Get the thermostat.
  $thermostat = $seam->devices->get(
    device_id: "a4b775e3-feb2-4c6b-8e78-a73ec2d70b61"
  );

  // Confirm that the thermostat supports off mode.
  if ($thermostat->can_turn_off_hvac) {
    // Perform the off request.
    $seam->thermostats->off(
      device_id: $thermostat->device_id
    );
  }
  ```

  ```csharp C# theme={null}
  // Coming soon!
  ```
</CodeGroup>

**Response:**

<CodeGroup>
  ```json JavaScript theme={null}
  {
    "status": "success",
    "action_attempt_id": "ef94c8b2-3ff0-4e56-a97e-033ca07ba0fd",
    "action_type": "SET_HVAC_MODE",
    "result": {},
    "error": null
  }
  ```

  ```json cURL theme={null}
  {
    "action_attempt": {
      "status": "pending",
      "action_type": "SET_HVAC_MODE",
      "action_attempt_id": "ef94c8b2-3ff0-4e56-a97e-033ca07ba0fd",
      "result": null,
      "error": null
    },
    "ok": true
  }
  ```

  ```json Python theme={null}
  ActionAttempt(
    action_attempt_id='ef94c8b2-3ff0-4e56-a97e-033ca07ba0fd',
    action_type='SET_HVAC_MODE',
    status='success',
    result={},
    error=None
  )
  ```

  ```json Ruby theme={null}
  <Seam::Resources::ActionAttempt:0x005f0
    status="success"
    action_type="SET_HVAC_MODE"
    action_attempt_id="ef94c8b2-3ff0-4e56-a97e-033ca07ba0fd"
    result={}
    error=nil>
  ```

  ```json PHP theme={null}
  {
    "status": "success",
    "action_attempt_id": "ef94c8b2-3ff0-4e56-a97e-033ca07ba0fd",
    "action_type": "SET_HVAC_MODE",
    "result": {},
    "error": null
  }
  ```

  ```json C# theme={null}
  // Coming soon!
  ```
</CodeGroup>

***

## Set the Fan Mode Setting

You can [configure the fan mode setting for a thermostat](/api/thermostats/set_fan_mode). For details about the supported fan modes, see [Fan Mode Settings](#fan-mode-settings).

Set the fan mode setting by providing the `device_id` of the thermostat and specifying the desired `fan_mode_setting`.

**Request:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  await seam.thermostats.setFanMode({
    device_id: 'a4b775e3-feb2-4c6b-8e78-a73ec2d70b61',
    fan_mode_setting: 'auto',
  })
  ```

  ```bash cURL theme={null}
  curl -X 'POST' \
    'https://connect.getseam.com/thermostats/set_fan_mode' \
    -H 'accept: application/json' \
    -H 'Authorization: Bearer ${API_KEY}' \
    -H 'Content-Type: application/json' \
    -d '{
    "device_id": "a4b775e3-feb2-4c6b-8e78-a73ec2d70b61",
    "fan_mode_setting": "auto"
  }'
  ```

  ```python Python theme={null}
  seam.thermostats.set_fan_mode(
    device_id = "a4b775e3-feb2-4c6b-8e78-a73ec2d70b61",
    fan_mode_setting = "auto"
  )
  ```

  ```ruby Ruby theme={null}
  # Coming soon!
  ```

  ```php PHP theme={null}
  $seam->thermostats->set_fan_mode(
    device_id: "a4b775e3-feb2-4c6b-8e78-a73ec2d70b61",
    fan_mode_setting: "auto"
  );
  ```

  ```csharp C# theme={null}
  // Coming soon!
  ```
</CodeGroup>

**Response:**

<CodeGroup>
  ```json JavaScript theme={null}
  {
    "status": "success",
    "action_attempt_id": "9c9b584b-c645-4ce0-a9c2-79b6f1db2396",
    "action_type": "SET_FAN_MODE",
    "result": {},
    "error": null
  }
  ```

  ```json cURL theme={null}
  {
    "action_attempt": {
      "status": "pending",
      "action_type": "SET_FAN_MODE",
      "action_attempt_id": "9c9b584b-c645-4ce0-a9c2-79b6f1db2396",
      "result": null,
      "error": null
    },
    "ok": true
  }
  ```

  ```json Python theme={null}
  ActionAttempt(
    action_attempt_id='9c9b584b-c645-4ce0-a9c2-79b6f1db2396',
    action_type='SET_FAN_MODE',
    status='success',
    result={},
    error=None
  )
  ```

  ```json Ruby theme={null}
  # Coming soon!
  ```

  ```json PHP theme={null}
  {
    "status": "success",
    "action_attempt_id": "9c9b584b-c645-4ce0-a9c2-79b6f1db2396",
    "action_type": "SET_FAN_MODE",
    "result": {},
    "error": null
  }
  ```

  ```json C# theme={null}
  // Coming soon!
  ```
</CodeGroup>

***

## Poll the Action Attempt

The imperative HVAC or fan mode setting request returns an [action attempt](../../core-concepts/action-attempts). Use the `action_attempt_id` from this response to poll the associated action attempt using the [`/action_attempts/get`](/api/action_attempts/get) request. When the setting modification completes successfully, the `status` of the action attempt changes to `success`.

**Request:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  await seam.actionAttempts.get(
    action_attempt_id: "9c9b584b-c645-4ce0-a9c2-79b6f1db2396"
  );
  ```

  ```bash cURL theme={null}
  # Use GET or POST.
  curl -X 'GET' \
    'https://connect.getseam.com/action_attempts/get' \
    -H 'accept: application/json' \
    -H 'Authorization: Bearer ${SEAM_API_KEY}' \
    -H 'Content-Type: application/json' \
    -d '{
    "action_attempt_id": "9c9b584b-c645-4ce0-a9c2-79b6f1db2396"
  }'
  ```

  ```python Python theme={null}
  seam.action_attempts.get(
    action_attempt_id = "9c9b584b-c645-4ce0-a9c2-79b6f1db2396"
  )
  ```

  ```ruby Ruby theme={null}
  # Coming soon!
  ```

  ```php PHP theme={null}
  $seam->action_attempts->get(
    action_attempt_id: "a4b775e3-feb2-4c6b-8e78-a73ec2d70b61"
  );
  ```

  ```csharp C# theme={null}
  // Coming soon!
  ```
</CodeGroup>

**Response:**

<CodeGroup>
  ```json JavaScript theme={null}
  {
    "status": "success",
    "action_attempt_id": "9c9b584b-c645-4ce0-a9c2-79b6f1db2396",
    "action_type": "SET_FAN_MODE",
    "result": {},
    "error": null
  }
  ```

  ```json cURL theme={null}
  {
    "action_attempt": {
      "status": "success",
      "action_type": "SET_FAN_MODE",
      "action_attempt_id": "9c9b584b-c645-4ce0-a9c2-79b6f1db2396",
      "result": null,
      "error": null
    },
    "ok": true
  }
  ```

  ```json Python theme={null}
  ActionAttempt(
    action_attempt_id='9c9b584b-c645-4ce0-a9c2-79b6f1db2396',
    action_type='SET_FAN_MODE',
    status='success',
    result={},
    error=None
  )
  ```

  ```json Ruby theme={null}
  # Coming soon!
  ```

  ```json PHP theme={null}
  {
    "status": "success",
    "action_attempt_id": "9c9b584b-c645-4ce0-a9c2-79b6f1db2396",
    "action_type": "SET_FAN_MODE",
    "result": {},
    "error": null
  }
  ```

  ```json C# theme={null}
  // Coming soon!
  ```
</CodeGroup>


# Activating a Climate Preset
Source: https://docs.seam.co/capability-guides/thermostats/creating-and-managing-climate-presets/activating-a-climate-preset

Learn how to activate a preconfigured climate preset immediately.

In addition to [scheduling](../creating-and-managing-thermostat-schedules) climate presets for a thermostat, you can activate a configured climate preset immediately. When you activate a climate preset, it overrides any scheduled climate preset that is already active on the thermostat.

Activating a climate preset returns an [action attempt](../../../core-concepts/action-attempts) that enables you to track the progress of the action. Poll this action attempt, until the action completes.

Further, Seam emits a [`thermostat.temperature_reached_set_point` event](/api/thermostats/events#thermostat-temperature_reached_set_point) when the thermostat reports a temperature within 1° Celsius of the heating or cooling [set point](../understanding-thermostat-concepts/set-points) specified in the climate preset that you've activated. You can configure a [webhook](../../../developer-tools/webhooks) to watch for this event.

***

## Activate a Climate Preset

To activate a climate preset, issue a [`/thermostats/activate_climate_preset`](/api/thermostats/activate_climate_preset) request and specify the `climate_preset_key` of the desired climate preset.

**Request:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  await seam.thermostats.activateClimatePreset({
    device_id: '2d488679-6f07-4810-aed2-e726872c1dd5',
    climate_preset_key: 'occupied',
  })
  ```

  ```bash cURL theme={null}
  curl -X 'POST' \
    'https://connect.getseam.com/thermostats/activate_climate_preset' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d '{
      "device_id": "2d488679-6f07-4810-aed2-e726872c1dd5",
      "climate_preset_key": "occupied"
  }'
  ```

  ```python Python theme={null}
  seam.thermostats.activate_climate_preset(
    device_id = "2d488679-6f07-4810-aed2-e726872c1dd5",
    climate_preset_key = "occupied"
  )
  ```

  ```ruby Ruby theme={null}
  # Coming soon!
  ```

  ```php PHP theme={null}
  $seam->thermostats->activate_climate_preset(
    device_id: "2d488679-6f07-4810-aed2-e726872c1dd5",
    climate_preset_key: "occupied"
  );
  ```

  ```java C# theme={null}
  // Coming soon!
  ```
</CodeGroup>

**Response:**

<CodeGroup>
  ```json JavaScript theme={null}
  {
    "status": "success",
    "action_attempt_id": "05de2295-d1dc-4748-aae3-9931658bde20",
    "action_type": "ACTIVATE_CLIMATE_PRESET",
    "result": {},
    "error": null
  }
  ```

  ```json cURL theme={null}
  {
    "action_attempt": {
      "status": "pending",
      "action_type": "ACTIVATE_CLIMATE_PRESET",
      "action_attempt_id": "05de2295-d1dc-4748-aae3-9931658bde20",
      "result": null,
      "error": null
    },
    "ok": true
  }
  ```

  ```json Python theme={null}
  ActionAttempt(
    action_attempt_id='05de2295-d1dc-4748-aae3-9931658bde20',
    action_type='ACTIVATE_CLIMATE_PRESET',
    error={},
    result={},
    status='success'
  )
  ```

  ```json Ruby theme={null}
  # Coming soon!
  ```

  ```json PHP theme={null}
  {
    "action_attempt_id": "05de2295-d1dc-4748-aae3-9931658bde20",
    "action_type": "ACTIVATE_CLIMATE_PRESET",
    "error": null,
    "result": {},
    "status": "success"
  }
  ```

  ```json C# theme={null}
  // Coming soon!
  ```
</CodeGroup>

***

## Poll the Action Attempt

Activating a climate preset returns an [action attempt](../../../core-concepts/action-attempts). Use the `action_attempt_id` from this response to poll the associated action attempt using the [`/action_attempts/get`](/api/action_attempts/get) request. When the activation completes successfully, the `status` of the action attempt changes to `success`.

**Request:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  await seam.actionAttempts.get(
    action_attempt_id: "05de2295-d1dc-4748-aae3-9931658bde20"
  );
  ```

  ```bash cURL theme={null}
  # Use GET or POST.
  curl -X 'GET' \
    'https://connect.getseam.com/action_attempts/get' \
    -H 'accept: application/json' \
    -H 'Authorization: Bearer ${SEAM_API_KEY}' \
    -H 'Content-Type: application/json' \
    -d '{
    "action_attempt_id": "05de2295-d1dc-4748-aae3-9931658bde20"
  }'
  ```

  ```python Python theme={null}
  seam.action_attempts.get(
    action_attempt_id = "05de2295-d1dc-4748-aae3-9931658bde20"
  )
  ```

  ```ruby Ruby theme={null}
  # Coming soon!
  ```

  ```php PHP theme={null}
  $seam->action_attempts->get(
    action_attempt_id: "05de2295-d1dc-4748-aae3-9931658bde20"
  );
  ```

  ```csharp C# theme={null}
  // Coming soon!
  ```
</CodeGroup>

**Response:**

<CodeGroup>
  ```json JavaScript theme={null}
  {
    "status": "success",
    "action_attempt_id": "05de2295-d1dc-4748-aae3-9931658bde20",
    "action_type": "ACTIVATE_CLIMATE_PRESET",
    "result": {},
    "error": null
  }
  ```

  ```json cURL theme={null}
  {
    "action_attempt": {
      "status": "success",
      "action_attempt_id": "05de2295-d1dc-4748-aae3-9931658bde20",
      "action_type": "ACTIVATE_CLIMATE_PRESET",
      "result": {},
      "error": null
    },
    "ok": true
  }
  ```

  ```json Python theme={null}
  ActionAttempt(
    action_attempt_id='05de2295-d1dc-4748-aae3-9931658bde20',
    action_type='ACTIVATE_CLIMATE_PRESET',
    error={},
    result={},
    status='success'
  )
  ```

  ```json Ruby theme={null}
  # Coming soon!
  ```

  ```json PHP theme={null}
  {
    "action_attempt_id": "05de2295-d1dc-4748-aae3-9931658bde20",
    "action_type": "ACTIVATE_CLIMATE_PRESET",
    "error": null,
    "result": {},
    "status": "success"
  }
  ```

  ```json C# theme={null}
  // Coming soon!
  ```
</CodeGroup>


# Creating and Managing Climate Presets
Source: https://docs.seam.co/capability-guides/thermostats/creating-and-managing-climate-presets/index

Learn how to create, list, update, and delete climate presets for thermostats.

You create a set of climate presets for each thermostat, customized for your—and your users'—needs. Each climate preset is a predefined configuration for a thermostat that specifies settings, such as HVAC mode, fan mode, and temperature set points. These presets make it quick and efficient for users to apply consistent climate settings tailored to different scenarios, enhancing both comfort and energy efficiency.

Once you create climate presets, you can [activate them](/api/thermostats/activate_climate_preset), add them to thermostat [schedules](../creating-and-managing-thermostat-schedules) and [programs](../creating-and-managing-thermostat-programs), and set them as the [fallback climate preset](/capability-guides/thermostats/creating-and-managing-climate-presets/setting-the-fallback-climate-preset).

***

## Climate Preset Properties

Each climate preset can contain the following properties, depending on the [capabilities](/capability-guides/thermostats/index#thermostat-capabilities) of the thermostat:

<table>
  <thead>
    <tr>
      <th>Property</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        <code>climate\_preset\_key</code>
      </td>

      <td>(Required) Key to identify the climate preset.</td>
    </tr>

    <tr>
      <td>
        <code>name</code>
      </td>

      <td>(Optional) User-friendly name to identify the climate preset.</td>
    </tr>

    <tr>
      <td>
        <code>fan\_mode\_setting</code>
      </td>

      <td>
        Desired fan mode setting, such as <code>on</code>, <code>auto</code>, or
        <code>circulate</code>.
      </td>
    </tr>

    <tr>
      <td>
        <code>hvac\_mode\_setting</code>
      </td>

      <td>
        Desired

        <a href="/capability-guides/thermostats/understanding-thermostat-concepts/hvac-mode">
          HVAC mode
        </a>

        setting, such as <code>heat</code>, <code>cool</code>,
        <code>heat\_cool</code>, or <code>off</code>.
      </td>
    </tr>

    <tr>
      <td>
        <code>cooling\_set\_point\_celsius</code>
      </td>

      <td>
        Temperature to which the thermostat should cool (in °C). See also

        <a href="/capability-guides/thermostats/understanding-thermostat-concepts/set-points">
          Set Points
        </a>

        .
      </td>
    </tr>

    <tr>
      <td>
        <code>cooling\_set\_point\_fahrenheit</code>
      </td>

      <td>Temperature to which the thermostat should cool (in °F).</td>
    </tr>

    <tr>
      <td>
        <code>heating\_set\_point\_celsius</code>
      </td>

      <td>Temperature to which the thermostat should heat (in °C).</td>
    </tr>

    <tr>
      <td>
        <code>heating\_set\_point\_fahrenheit</code>
      </td>

      <td>Temperature to which the thermostat should heat (in °F).</td>
    </tr>

    <tr>
      <td>
        <del>
          <code>manual\_override\_allowed</code>
        </del>
      </td>

      <td>
        (Optional) Indicates whether a person at the thermostat or using the API
        can change the thermostat's settings.

        <br />

        <br />

        Deprecated. Use <code>thermostat\_schedule.is\_override\_allowed</code>
        instead.
      </td>
    </tr>

    <tr>
      <td>
        <code>can\_edit</code>
      </td>

      <td>
        Indicates whether the climate preset can be edited. There are some cases
        in which Seam syncs in climate presets (from the device) that cannot be
        modified.
      </td>
    </tr>

    <tr>
      <td>
        <code>can\_delete</code>
      </td>

      <td>
        Indicates whether the climate preset can be deleted. There are some
        cases in which Seam syncs in climate presets (from the device) that
        cannot be deleted.
      </td>
    </tr>
  </tbody>
</table>

***

## Create a Climate Preset

To create a climate preset, issue a [`/thermostats/create_climate_preset`](/api/thermostats/create_climate_preset) request, providing the `device_id` of the desired thermostat. Also, include the desired settings for the climate preset and, optionally, a name.

The following example creates two climate presets with the keys `occupied` and `unoccupied`:

**Request:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  // Get the thermostat.
  const thermostat = await seam.devices.get({
    device_id: '2d488679-6f07-4810-aed2-e726872c1dd5',
  })

  // Confirm that the thermostat supports heat_cool mode
  // so that the climate presets can use this mode.
  if (thermostat.can_hvac_heat_cool) {
    // Create the climate presets.
    await seam.thermostats.createClimatePreset({
      device_id: thermostat.device_id,
      climate_preset_key: 'occupied',
      name: 'Occupied',
      fan_mode_setting: 'auto',
      hvac_mode_setting: 'heat_cool',
      cooling_set_point_celsius: 25,
      heating_set_point_celsius: 20,
    })

    await seam.thermostats.createClimatePreset({
      device_id: thermostat.device_id,
      climate_preset_key: 'unoccupied',
      name: 'Unoccupied',
      fan_mode_setting: 'auto',
      hvac_mode_setting: 'heat_cool',
      cooling_set_point_celsius: 30,
      heating_set_point_celsius: 15,
    })
  }
  ```

  ```bash cURL theme={null}
  # Get the thermostat.
  thermostat=$(
    # Use GET or POST.
    curl -X 'GET' \
      'https://connect.getseam.com/devices/get' \
      -H 'accept: application/json' \
      -H "Authorization: Bearer ${SEAM_API_KEY}" \
      -H 'Content-Type: application/json' \
      -d '{
        "device_id": "2d488679-6f07-4810-aed2-e726872c1dd5"
    }')

  # Confirm that the thermostat supports heat_cool mode
  # so that the climate presets can use this mode.
  if  $(jq -r '.device.can_hvac_heat_cool' <<< ${thermostat}); then \
    # Create the climate presets.
    curl -X 'POST' \
      'https://connect.getseam.com/thermostats/create_climate_preset' \
      -H 'accept: application/json' \
      -H "Authorization: Bearer ${SEAM_API_KEY}" \
      -H 'Content-Type: application/json' \
      -d "{
        \"device_id\": \"$(jq -r '.device.device_id' <<< ${thermostat})\",
        \"climate_preset_key\": \"occupied\",
        \"name\": \"Occupied\",
        \"fan_mode_setting\": \"auto\",
        \"hvac_mode_setting\": \"heat_cool\",
        \"cooling_set_point_celsius\": 25,
        \"heating_set_point_celsius\": 20
    }";

    curl -X 'POST' \
      'https://connect.getseam.com/thermostats/create_climate_preset' \
      -H 'accept: application/json' \
      -H "Authorization: Bearer ${SEAM_API_KEY}" \
      -H 'Content-Type: application/json' \
      -d "{
        \"device_id\": \"$(jq -r '.device.device_id' <<< ${thermostat})\",
        \"climate_preset_key\": \"unoccupied\",
        \"name\": \"Unoccupied\",
        \"fan_mode_setting\": \"auto\",
        \"hvac_mode_setting\": \"heat_cool\",
        \"cooling_set_point_celsius\": 30,
        \"heating_set_point_celsius\": 15
    }";
  fi
  ```

  ```python Python theme={null}
  # Get the thermostat.
  thermostat = seam.devices.get(
    device_id = "2d488679-6f07-4810-aed2-e726872c1dd5"
  )

  # Confirm that the thermostat supports heat_cool mode
  # so that the climate presets can use this mode.
  if thermostat.can_hvac_heat_cool:
    # Create the climate presets.
    seam.thermostats.create_climate_preset(
      device_id = thermostat.device_id,
      climate_preset_key = "occupied",
      name = "Occupied",
      fan_mode_setting = "auto",
      hvac_mode_setting = "heat_cool",
      cooling_set_point_celsius = 25,
      heating_set_point_celsius = 20
    )

    seam.thermostats.create_climate_preset(
      device_id: thermostat.device_id,
      climate_preset_key = "unoccupied",
      name = "Unoccupied",
      fan_mode_setting = "auto",
      hvac_mode_setting = "heat_cool",
      cooling_set_point_celsius = 30,
      heating_set_point_celsius = 15
    )
  ```

  ```ruby Ruby theme={null}
  # Get the thermostat.
  thermostat = seam.devices.get(
    device_id: "2d488679-6f07-4810-aed2-e726872c1dd5"
  )

  # Confirm that the thermostat supports heat_cool mode
  # so that the climate presets can use this mode.
  if (thermostat.can_hvac_heat_cool)
    # Create the climate presets.
    seam.thermostats.create_climate_preset(
      device_id: thermostat.device_id,
      climate_preset_key: "occupied",
      name: "Occupied",
      fan_mode_setting: "auto",
      hvac_mode_setting: "heat_cool",
      cooling_set_point_celsius: 25,
      heating_set_point_celsius: 20
    )

    seam.thermostats.create_climate_preset(
      device_id: thermostat.device_id,
      climate_preset_key: "unoccupied",
      name: "Unoccupied",
      fan_mode_setting: "auto",
      hvac_mode_setting: "heat_cool",
      cooling_set_point_celsius: 30,
      heating_set_point_celsius: 15
    )
  end
  ```

  ```php PHP theme={null}
  // Get the thermostat.
  $thermostat = $seam->devices->get(
    device_id: "2d488679-6f07-4810-aed2-e726872c1dd5"
  );

  // Confirm that the thermostat supports heat_cool mode
  // so that the climate presets can use this mode.
  if ($thermostat->can_hvac_heat_cool) {
    // Create the climate presets.
    $seam->thermostats->create_climate_preset(
      device_id: $thermostat->device_id,
      climate_preset_key: "occupied",
      name: "Occupied",
      fan_mode_setting: "auto",
      hvac_mode_setting: "heat_cool",
      cooling_set_point_celsius: 25,
      heating_set_point_celsius: 20
    );

    $seam->thermostats->create_climate_preset(
      device_id: $thermostat->device_id,
      climate_preset_key: "unoccupied",
      name: "Unoccupied",
      fan_mode_setting: "auto",
      hvac_mode_setting: "heat_cool",
      cooling_set_point_celsius: 30,
      heating_set_point_celsius: 15
    );
  }
  ```

  ```csharp C# theme={null}
  // Coming soon!
  ```
</CodeGroup>

**Response:**

<CodeGroup>
  ```json JavaScript theme={null}
  void
  ```

  ```json cURL theme={null}
  {
    "ok": true
  }
  ```

  ```json Python theme={null}
  None
  ```

  ```json Ruby theme={null}
  nil
  ```

  ```json PHP theme={null}
  void
  ```

  ```json C# theme={null}
  // Coming soon!
  ```
</CodeGroup>

***

## List All Climate Presets for a Thermostat

To list climate presets for a thermostat, issue a [`/devices/get`](/api/devices/get) request, providing the `device_id` of the desired thermostat. Then, inspect the `available_climate_presets` property.

**Request:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  await seam.devices.get({
    device_id: '2d488679-6f07-4810-aed2-e726872c1dd5',
  })
  ```

  ```bash cURL theme={null}
  # Use GET or POST.
  curl -X 'GET' \
    'https://connect.getseam.com/devices/get' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d '{
    "device_id": "2d488679-6f07-4810-aed2-e726872c1dd5"
  }'
  ```

  ```python Python theme={null}
  seam.devices.get(
    device_id = "2d488679-6f07-4810-aed2-e726872c1dd5"
  )
  ```

  ```ruby Ruby theme={null}
  seam.devices.get(
    device_id: "2d488679-6f07-4810-aed2-e726872c1dd5"
  )
  ```

  ```php PHP theme={null}
  $seam->devices->get(
    device_id: "2d488679-6f07-4810-aed2-e726872c1dd5"
  );
  ```

  ```csharp C# theme={null}
  // Coming soon!
  ```
</CodeGroup>

**Response:**

<CodeGroup>
  ```json JavaScript theme={null}
  {
    device_id: '2d488679-6f07-4810-aed2-e726872c1dd5',
    properties: {
      available_climate_presets: [
        {
          climate_preset_key: 'occupied',
          name: 'Occupied',
          display_name: 'Occupied',
          fan_mode_setting: 'auto',
          hvac_mode_setting: 'heat_cool',
          cooling_set_point_celsius: 25,
          heating_set_point_celsius: 20,
          cooling_set_point_fahrenheit: 77,
          heating_set_point_fahrenheit: 68,
          ...
        },
        {
          climate_preset_key: 'unoccupied',
          name: 'Unoccupied',
          display_name: 'Unoccupied',
          fan_mode_setting: 'auto',
          hvac_mode_setting: 'heat_cool',
          cooling_set_point_celsius: 30,
          heating_set_point_celsius: 15,
          cooling_set_point_fahrenheit: 86,
          heating_set_point_fahrenheit: 59,
          ...
        }
      ],
      ...
    },
    ...
  }
  ```

  ```json cURL theme={null}
  {
    "device": {
      "device_id": "2d488679-6f07-4810-aed2-e726872c1dd5",
      "properties": {
        "available_climate_presets": [
          {
            "climate_preset_key": "occupied",
            "name": "Occupied",
            "display_name": "Occupied",
            "fan_mode_setting": "auto",
            "hvac_mode_setting": "heat_cool",
            "cooling_set_point_celsius": 25,
            "heating_set_point_celsius": 20,
            "cooling_set_point_fahrenheit": 77,
            "heating_set_point_fahrenheit": 68,
            ...
          },
          {
            "climate_preset_key": "unoccupied",
            "name": "Unoccupied",
            "display_name": "Unoccupied",
            "fan_mode_setting": "auto",
            "hvac_mode_setting": "heat_cool",
            "cooling_set_point_celsius": 30,
            "heating_set_point_celsius": 15,
            "cooling_set_point_fahrenheit": 86,
            "heating_set_point_fahrenheit": 59,
            ...
          }
        ],
        ...
      },
      ...
    },
    "ok": true
  }
  ```

  ```json Python theme={null}
  Device(
    device_id='2d488679-6f07-4810-aed2-e726872c1dd5',
    properties={
      'available_climate_presets': [
        {
          'climate_preset_key': 'occupied',
          'cooling_set_point_celsius': 25,
          'cooling_set_point_fahrenheit': 77,
          'display_name': 'Occupied',
          'fan_mode_setting': 'auto',
          'heating_set_point_celsius': 20,
          'heating_set_point_fahrenheit': 68,
          'hvac_mode_setting': 'heat_cool',
          'name': 'Occupied',
          ...
        },
        {
          'climate_preset_key': 'unoccupied',
          'cooling_set_point_celsius': 30,
          'cooling_set_point_fahrenheit': 86,
          'display_name': 'Unoccupied',
          'fan_mode_setting': 'auto',
          'heating_set_point_celsius': 15,
          'heating_set_point_fahrenheit': 59,
          'hvac_mode_setting': 'heat_cool',
          'name': 'Unoccupied',
          ...
        }
      ],
      ...
    },
    ...
  )
  ```

  ```json Ruby theme={null}
  <Seam::Resources::Device:0x005f0
    device_id="2d488679-6f07-4810-aed2-e726872c1dd5"
    properties=#<Seam::DeepHashAccessor:0x000001bf948fdbd0 @data={
      "available_climate_presets"=>[
        {
          "climate_preset_key"=>"occupied",
          "name"=>"Occupied",
          "display_name"=>"Occupied",
          "fan_mode_setting"=>"auto",
          "hvac_mode_setting"=>"heat_cool",
          "cooling_set_point_celsius"=>25,
          "heating_set_point_celsius"=>20,
          "cooling_set_point_fahrenheit"=>77,
          "heating_set_point_fahrenheit"=>68,
          ...
        },
        {
          "climate_preset_key"=>"unoccupied",
          "name"=>"Unoccupied",
          "display_name"=>"Unoccupied",
          "fan_mode_setting"=>"auto",
          "hvac_mode_setting"=>"heat_cool",
          "manual_override_allowed"=>true,
          "cooling_set_point_celsius"=>30,
          "heating_set_point_celsius"=>15,
          "cooling_set_point_fahrenheit"=>86,
          "heating_set_point_fahrenheit"=>59,
          ...
        }
      ]
      ...
   }
   ...
  >
  ```

  ```json PHP theme={null}
  {
    "device_id": "2d488679-6f07-4810-aed2-e726872c1dd5",
    "properties": {
      "available_climate_presets": [
          {
            "climate_preset_key": "occupied",
            "cooling_set_point_celsius": 25,
            "cooling_set_point_fahrenheit": 77,
            "display_name": "Occupied",
            "fan_mode_setting": "auto",
            "heating_set_point_celsius": 20,
            "heating_set_point_fahrenheit": 68,
            "hvac_mode_setting": "heat_cool",
            "name": "Occupied",
            ...
          },
          {
            "climate_preset_key": "unoccupied",
            "cooling_set_point_celsius": 30,
            "cooling_set_point_fahrenheit": 86,
            "display_name": "Unoccupied",
            "fan_mode_setting": "auto",
            "heating_set_point_celsius": 15,
            "heating_set_point_fahrenheit": 59,
            "hvac_mode_setting": "heat_cool",
            "name": "Unoccupied",
            ...
          }
      ],
      ...
    },
    ...
  }
  ```

  ```json C# theme={null}
  // Coming soon!
  ```
</CodeGroup>

***

## Update a Climate Preset

To update a climate preset, issue a [`/thermostats/update_climate_preset`](/api/thermostats/update_climate_preset) request, providing the `device_id` of the thermostat and the `climate_preset_key` of the desired climate preset. Also, include the desired updated settings for the climate preset.

**Request:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  await seam.thermostats.updateClimatePreset({
    device_id: '2d488679-6f07-4810-aed2-e726872c1dd5',
    climate_preset_key: 'occupied',
    cooling_set_point_celsius: 24,
  })
  ```

  ```bash cURL theme={null}
  curl -X 'POST' \
    'https://connect.getseam.com/thermostats/update_climate_preset' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d '{
      "device_id": "2d488679-6f07-4810-aed2-e726872c1dd5",
      "climate_preset_key": "occupied",
      "cooling_set_point_celsius": 24
  }'
  ```

  ```python Python theme={null}
  seam.thermostats.update_climate_preset(
    device_id = "2d488679-6f07-4810-aed2-e726872c1dd5",
    climate_preset_key = "occupied",
    cooling_set_point_celsius = 24
  )
  ```

  ```ruby Ruby theme={null}
  seam.thermostats.update_climate_preset(
    device_id: "2d488679-6f07-4810-aed2-e726872c1dd5",
    climate_preset_key: "occupied",
    cooling_set_point_celsius: 24
  )
  ```

  ```php PHP theme={null}
  $seam->thermostats->update_climate_preset(
    device_id: "2d488679-6f07-4810-aed2-e726872c1dd5",
    climate_preset_key: "occupied",
    cooling_set_point_celsius: 24
  );
  ```

  ```csharp C# theme={null}
  // Coming soon!
  ```
</CodeGroup>

**Response:**

<CodeGroup>
  ```json JavaScript theme={null}
  void
  ```

  ```json cURL theme={null}
  {
    "ok": true
  }
  ```

  ```json Python theme={null}
  None
  ```

  ```json Ruby theme={null}
  nil
  ```

  ```json PHP theme={null}
  void
  ```

  ```json C# theme={null}
  // Coming soon!
  ```
</CodeGroup>

***

## Delete a Climate Preset

To delete a climate preset, issue a [`/thermostats/delete_climate_preset`](/api/thermostats/delete_climate_preset) request, providing the `device_id` of the thermostat and the `climate_preset_key` of the desired climate preset.

**Request:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  await seam.thermostats.deleteClimatePreset({
    device_id: '2d488679-6f07-4810-aed2-e726872c1dd5',
    climate_preset_key: 'occupied',
  })
  ```

  ```bash cURL theme={null}
  curl -X 'POST' \
    'https://connect.getseam.com/thermostats/delete_climate_preset' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d '{
      "device_id": "2d488679-6f07-4810-aed2-e726872c1dd5",
      "climate_preset_key": "occupied"
  }'
  ```

  ```python Python theme={null}
  seam.thermostats.delete_climate_preset(
    device_id = "2d488679-6f07-4810-aed2-e726872c1dd5",
    climate_preset_key = "occupied"
  )
  ```

  ```ruby Ruby theme={null}
  seam.thermostats.delete_climate_preset(
    device_id: "2d488679-6f07-4810-aed2-e726872c1dd5",
    climate_preset_key: "occupied"
  )
  ```

  ```php PHP theme={null}
  $seam->thermostats->delete_climate_preset(
    device_id: "2d488679-6f07-4810-aed2-e726872c1dd5",
    climate_preset_key: "occupied"
  );
  ```

  ```java C# theme={null}
  // Coming soon!
  ```
</CodeGroup>

**Response:**

<CodeGroup>
  ```json JavaScript theme={null}
  void
  ```

  ```json cURL theme={null}
  {
    "ok": true
  }
  ```

  ```json Python theme={null}
  None
  ```

  ```json Ruby theme={null}
  nil
  ```

  ```json PHP theme={null}
  void
  ```

  ```json C# theme={null}
  // Coming soon!
  ```
</CodeGroup>


# Setting the Fallback Climate Preset
Source: https://docs.seam.co/capability-guides/thermostats/creating-and-managing-climate-presets/setting-the-fallback-climate-preset

Learn how to set a configured climate preset as the "fallback" preset for a thermostat.

Once you have created climate presets for a thermostat, you can set one of them as the "fallback" preset. Seam applies this fallback preset whenever no other climate preset is active. It works with the Seam API's [scheduling mechanism](../creating-and-managing-thermostat-schedules). The fallback climate preset is only applied once, after a thermostat schedule ends. If settings are changed while the fallback climate preset is active, the thermostat will override the fallback preset with the new settings. For example, you could set a fallback "eco" climate preset for the thermostat in your short-term rental property. Then, you could schedule—in advance—a "comfort" climate preset to correspond to each upcoming guest's stay. Whenever your property is unoccupied—that is, whenever there is no scheduled climate preset—Seam activates the fallback "eco" climate preset.

To set the fallback climate preset for a device, issue a [`/thermostats/set_fallback_climate_preset`](/api/thermostats/set_fallback_climate_preset) request and specify the `climate_preset_key` of the desired climate preset.

**Request:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  await seam.thermostats.setFallbackClimatePreset({
    device_id: '2d488679-6f07-4810-aed2-e726872c1dd5',
    climate_preset_key: 'eco',
  })
  ```

  ```bash cURL theme={null}
  curl -X 'POST' \
    'https://connect.getseam.com/thermostats/set_fallback_climate_preset' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d '{
      "device_id": "2d488679-6f07-4810-aed2-e726872c1dd5",
      "climate_preset_key": "eco"
  }'
  ```

  ```python Python theme={null}
  seam.thermostats.set_fallback_climate_preset(
    device_id = "2d488679-6f07-4810-aed2-e726872c1dd5",
    climate_preset_key = "eco"
  )
  ```

  ```ruby Ruby theme={null}
  # Coming soon!
  ```

  ```php PHP theme={null}
  $seam->thermostats->set_fallback_climate_preset(
    device_id: "2d488679-6f07-4810-aed2-e726872c1dd5",
    climate_preset_key: "eco"
  );
  ```

  ```java C# theme={null}
  // Coming soon!
  ```
</CodeGroup>

**Response:**

<CodeGroup>
  ```json JavaScript theme={null}
  void
  ```

  ```json cURL theme={null}
  {
    "ok": true
  }
  ```

  ```json Python theme={null}
  None
  ```

  ```json Ruby theme={null}
  # Coming soon!
  ```

  ```json PHP theme={null}
  void
  ```

  ```json C# theme={null}
  // Coming soon!
  ```
</CodeGroup>


# Creating and Managing Thermostat Programs
Source: https://docs.seam.co/capability-guides/thermostats/creating-and-managing-thermostat-programs

Learn how to create and manage daily and weekly programs for thermostats.

You can create thermostat weekly programs in a unified manner across the variety of thermostats that Seam supports. This standard feature of smart thermostats enables you to define full-week programs that are made up of reusable daily programs. Each daily program consists of a set of thermostat daily program periods, that is, time blocks with associated [climate presets](/capability-guides/thermostats/creating-and-managing-climate-presets/index).

To set a thermostat weekly program:

1. [Create the climate presets](/capability-guides/thermostats/creating-and-managing-climate-presets/index#create-a-climate-preset) that you want to use in your weekly program.
2. [Create the daily programs](#create-a-daily-program) that you want to use in your weekly program. In each daily program, define a set of time periods. For each of these time periods, specify the starting time for the period and the key that identifies the climate preset that you want to activate at the starting time.
3. [Update the weekly program](#update-the-weekly-program) on the thermostat. To define the weekly program, specify the configured daily program that you want to apply to each day of the week.

You can update daily programs, and you can update the weekly program again as desired. You can also delete any daily programs that are not being used in a weekly program.

***

## Daily Program Period Properties

Each daily program period contains the following properties:

| Property             | Description                                                                                                                             |
| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| `starts_at_time`     | Time at which the thermostat daily program period starts, in [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) format. |
| `climate_preset_key` | Key of the climate preset to activate at the `starts_at_time`.                                                                          |

***

## Daily Program Properties

Each daily program contains the following properties:

| Property                      | Description                                                                      |
| ----------------------------- | -------------------------------------------------------------------------------- |
| `thermostat_daily_program_id` | ID of the thermostat daily program.                                              |
| `device_id`                   | ID of the thermostat device on which the thermostat daily program is configured. |
| `name`                        | User-friendly name to identify the thermostat daily program.                     |
| `periods`                     | Array of thermostat daily program periods.                                       |
| `created_at`                  | Date and time at which the thermostat daily program was created.                 |

***

## Weekly Program Properties

Each weekly program contains the following properties:

| Property               | Description                                                            |
| ---------------------- | ---------------------------------------------------------------------- |
| `device_id`            | ID of the thermostat device on which the weekly program is configured. |
| `monday_program_id`    | ID of the thermostat daily program to run on Mondays.                  |
| `tuesday_program_id`   | ID of the thermostat daily program to run on Tuesdays.                 |
| `wednesday_program_id` | ID of the thermostat daily program to run on Wednesdays.               |
| `thursday_program_id`  | ID of the thermostat daily program to run on Thursdays.                |
| `friday_program_id`    | ID of the thermostat daily program to run on Fridays.                  |
| `saturday_program_id`  | ID of the thermostat daily program to run on Saturdays.                |
| `sunday_program_id`    | ID of the thermostat daily program to run on Sundays.                  |
| `created_at`           | Date and time at which the thermostat weekly program was created.      |

***

## Create a Daily Program

To define a daily program, use `/thermostats/daily_programs/create`, specifying the thermostat that you want to program, a name for the daily program, and the desired set of daily program periods.

The following example creates a weekday daily program with four period, each of which is linked to a configured climate preset:

**Request:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  await seam.thermostats.dailyPrograms.create({
    device_id: '11111111-1111-1111-2222-444444444444',
    name: 'Weekday Program',
    periods: [
      { starts_at_time: '07:00:00', climate_preset_key: 'Home' },
      { starts_at_time: '09:00:00', climate_preset_key: 'Away' },
      { starts_at_time: '16:00:00', climate_preset_key: 'Home' },
      { starts_at_time: '22:30:00', climate_preset_key: 'Sleep' },
    ],
  })
  ```

  ```bash cURL theme={null}
  curl -X 'POST' \
    'https://connect.getseam.com/thermostats/daily_programs/create' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d '{
      "device_id": "11111111-1111-1111-2222-444444444444",
      "name":  "Weekday Program",
      "periods": [
      { "starts_at_time": "07:00:00", "climate_preset_key": "Home" },
      { "starts_at_time": "09:00:00", "climate_preset_key": "Away" },
      { "starts_at_time": "16:00:00", "climate_preset_key": "Home" },
      { "starts_at_time": "22:30:00", "climate_preset_key": "Sleep" }
    ]
  }'
  ```

  ```python Python theme={null}
  seam.thermostats.daily_programs.create(
    device_id = "11111111-1111-1111-2222-444444444444",
    name = "Weekday Program",
    periods = [
      { "starts_at_time": "07:00:00", "climate_preset_key": "Home" },
      { "starts_at_time": "09:00:00", "climate_preset_key": "Away" },
      { "starts_at_time": "16:00:00", "climate_preset_key": "Home" },
      { "starts_at_time": "22:30:00", "climate_preset_key": "Sleep" }
    ]
  )
  ```

  ```ruby Ruby theme={null}
  seam.thermostats.daily_programs.create(
    device_id: "11111111-1111-1111-2222-444444444444",
    name: "Weekday Program",
    periods: [
      { "starts_at_time": "07:00:00", "climate_preset_key": "Home" },
      { "starts_at_time": "09:00:00", "climate_preset_key": "Away" },
      { "starts_at_time": "16:00:00", "climate_preset_key": "Home" },
      { "starts_at_time": "22:30:00", "climate_preset_key": "Sleep" }
    ]
  )
  ```

  ```php PHP theme={null}
  $seam->thermostats->daily_programs->create(
    device_id: "11111111-1111-1111-2222-444444444444",
    name: "Weekday Program",
    periods: [
      { "starts_at_time": "07:00:00", "climate_preset_key": "Home" },
      { "starts_at_time": "09:00:00", "climate_preset_key": "Away" },
      { "starts_at_time": "16:00:00", "climate_preset_key": "Home" },
      { "starts_at_time": "22:30:00", "climate_preset_key": "Sleep" }
    ]
  );
  ```

  ```csharp C# theme={null}
  // Coming soon!
  ```
</CodeGroup>

**Response:**

<CodeGroup>
  ```json JavaScript theme={null}
  {
    thermostat_daily_program_id: '99999999-1111-1111-1111-111111111111',
    device_id: '11111111-1111-1111-2222-444444444444',
    name: 'Weekday Program',
    periods: [
        {'starts_at_time': '07:00:00', 'climate_preset_key': 'Home'},
        {'starts_at_time': '09:00:00', 'climate_preset_key': 'Away'},
        {'starts_at_time': '16:00:00', 'climate_preset_key': 'Home'},
        {'starts_at_time': '22:30:00', 'climate_preset_key': 'Sleep'}
      ],
    ...
  }
  ```

  ```json cURL theme={null}
  {
    "thermostat_daily_program": {
      "thermostat_daily_program_id": "99999999-1111-1111-1111-111111111111",
      "device_id": "11111111-1111-1111-2222-444444444444",
      "name": "Weekday Program",
      "periods": [
        {"starts_at_time": "07:00:00", "climate_preset_key": "Home"},
        {"starts_at_time": "09:00:00", "climate_preset_key": "Away"},
        {"starts_at_time": "16:00:00", "climate_preset_key": "Home"},
        {"starts_at_time": "22:30:00", "climate_preset_key": "Sleep"}
      ],
      ...
    },
    "ok": true
  }
  ```

  ```json Python theme={null}
  ThermostatDailyProgram(
    thermostat_daily_program_id='99999999-1111-1111-1111-111111111111',
    device_id='11111111-1111-1111-2222-444444444444',
    name="Weekday Program",
    periods=[
      { "starts_at_time": "07:00:00", "climate_preset_key": "Home" },
      { "starts_at_time": "09:00:00", "climate_preset_key": "Away" },
      { "starts_at_time": "16:00:00", "climate_preset_key": "Home" },
      { "starts_at_time": "22:30:00", "climate_preset_key": "Sleep" }
    ],
    ...
  )
  ```

  ```json Ruby theme={null}
  <Seam::Resources::ThermostatDailyProgram:0x005f0
    thermostat_daily_program_id="99999999-1111-1111-1111-111111111111"
    device_id="11111111-1111-1111-2222-444444444444"
    name="Weekday Program"
    periods: [
      {"starts_at_time": "07:00:00", "climate_preset_key": "Home"},
      {"starts_at_time": "09:00:00", "climate_preset_key": "Away"},
      {"starts_at_time": "16:00:00", "climate_preset_key": "Home"},
      {"starts_at_time": "22:30:00", "climate_preset_key": "Sleep"}
    ],
    ...
  >
  ```

  ```json PHP theme={null}
  {
    "thermostat_daily_program_id": "99999999-1111-1111-1111-111111111111",
    "device_id": "11111111-1111-1111-2222-444444444444",
    "name": "Weekday Program",
    "periods": [
      {"starts_at_time": "07:00:00", "climate_preset_key": "Home"},
      {"starts_at_time": "09:00:00", "climate_preset_key": "Away"},
      {"starts_at_time": "16:00:00", "climate_preset_key": "Home"},
      {"starts_at_time": "22:30:00", "climate_preset_key": "Sleep"}
    ],
    ...
  }
  ```

  ```json C# theme={null}
  // Coming soon!
  ```
</CodeGroup>

***

## Update a Daily Program

To update a daily program, use `/thermostats/daily_programs/update`, specifying the ID of the daily program that you want to change. You can edit the name for the daily program and the desired replacement set of daily program periods. To delete a daily program period, simply omit it when specifying the complete set of replacement program periods for the daily program.

Updating a daily program returns an [action attempt](../../core-concepts/action-attempts) so that you can track the status of pushing this program change to the thermostat.

The following example changes the climate preset for the second period and the starting time of the third period:

**Request:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  await seam.thermostats.dailyPrograms.update({
    thermostat_daily_program_id: '99999999-1111-1111-1111-111111111111',
    name: 'Weekday Program',
    periods: [
      { starts_at_time: '07:00:00', climate_preset_key: 'Home' },
      { starts_at_time: '09:00:00', climate_preset_key: 'Eco' },
      { starts_at_time: '18:00:00', climate_preset_key: 'Home' },
      { starts_at_time: '22:30:00', climate_preset_key: 'Sleep' },
    ],
  })
  ```

  ```bash cURL theme={null}
  curl -X 'POST' \
    'https://connect.getseam.com/thermostats/daily_programs/update' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d '{
      "thermostat_daily_program_id": "99999999-1111-1111-1111-111111111111",
      "name":  "Weekday Program",
      "periods": [
      { "starts_at_time": "07:00:00", "climate_preset_key": "Home" },
      { "starts_at_time": "09:00:00", "climate_preset_key": "Eco" },
      { "starts_at_time": "18:00:00", "climate_preset_key": "Home" },
      { "starts_at_time": "22:30:00", "climate_preset_key": "Sleep" }
    ]
  }'
  ```

  ```python Python theme={null}
  seam.thermostats.daily_programs.update(
    thermostat_daily_program_id = "99999999-1111-1111-1111-111111111111",
    name = "Weekday Program",
    periods = [
      { "starts_at_time": "07:00:00", "climate_preset_key": "Home" },
      { "starts_at_time": "09:00:00", "climate_preset_key": "Eco" },
      { "starts_at_time": "18:00:00", "climate_preset_key": "Home" },
      { "starts_at_time": "22:30:00", "climate_preset_key": "Sleep" }
    ]
  )
  ```

  ```ruby Ruby theme={null}
  seam.thermostats.daily_programs.update(
    thermostat_daily_program_id: "99999999-1111-1111-1111-111111111111",
    name: "Weekday Program",
    periods: [
      { "starts_at_time": "07:00:00", "climate_preset_key": "Home" },
      { "starts_at_time": "09:00:00", "climate_preset_key": "Eco" },
      { "starts_at_time": "18:00:00", "climate_preset_key": "Home" },
      { "starts_at_time": "22:30:00", "climate_preset_key": "Sleep" }
    ]
  )
  ```

  ```php PHP theme={null}
  $seam->thermostats->daily_programs->update(
    thermostat_daily_program_id: "99999999-1111-1111-1111-111111111111",
    name: "Weekday Program",
    periods: [
      { "starts_at_time": "07:00:00", "climate_preset_key": "Home" },
      { "starts_at_time": "09:00:00", "climate_preset_key": "Eco" },
      { "starts_at_time": "18:00:00", "climate_preset_key": "Home" },
      { "starts_at_time": "22:30:00", "climate_preset_key": "Sleep" }
    ]
  );
  ```

  ```csharp C# theme={null}
  // Coming soon!
  ```
</CodeGroup>

**Response:**

<CodeGroup>
  ```json JavaScript theme={null}
  {
    "status": "success",
    "action_attempt_id": "11111111-2222-3333-4444-555555555555",
    "action_type": "PUSH_THERMOSTAT_PROGRAMS",
    "result": {},
    "error": null
  }
  ```

  ```json cURL theme={null}
  {
    "action_attempt": {
      "status": "pending",
      "action_type": "PUSH_THERMOSTAT_PROGRAMS",
      "action_attempt_id": "11111111-2222-3333-4444-555555555555",
      "result": null,
      "error": null
    },
    "ok": true
  }
  ```

  ```json Python theme={null}
  ActionAttempt(
    action_attempt_id='11111111-2222-3333-4444-555555555555',
    action_type='PUSH_THERMOSTAT_PROGRAMS',
    status='success',
    result={},
    error=None
  )
  ```

  ```json Ruby theme={null}
  <Seam::Resources::ActionAttempt:0x005f0
    status="success"
    action_type="PUSH_THERMOSTAT_PROGRAMS"
    action_attempt_id="11111111-2222-3333-4444-555555555555"
    result={}
    error=nil>
  ```

  ```json PHP theme={null}
  {
    "status": "success",
    "action_attempt_id": "11111111-2222-3333-4444-555555555555",
    "action_type": "PUSH_THERMOSTAT_PROGRAMS",
    "result": {},
    "error": null
  }
  ```

  ```json C# theme={null}
  // Coming soon!
  ```
</CodeGroup>

***

## Delete a Daily Program

To delete a daily program, use `/thermostats/daily_programs/delete`, specifying the ID of the daily program that you want to delete. You cannot delete a daily program that's currently assigned to a weekly program.

**Request:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  await seam.thermostats.dailyPrograms.delete({
    thermostat_daily_program_id: '99999999-1111-1111-1111-111111111111',
  })
  ```

  ```bash cURL theme={null}
  curl -X 'POST' \
    'https://connect.getseam.com/thermostats/daily_programs/delete' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d '{
      "thermostat_daily_program_id": "99999999-1111-1111-1111-111111111111"
  }'
  ```

  ```python Python theme={null}
  seam.thermostats.daily_programs.delete(
    thermostat_daily_program_id = "99999999-1111-1111-1111-111111111111"
  )
  ```

  ```ruby Ruby theme={null}
  seam.thermostats.daily_programs.delete(
    thermostat_daily_program_id: "99999999-1111-1111-1111-111111111111"
  )
  ```

  ```php PHP theme={null}
  $seam->thermostats->daily_programs->delete(
    thermostat_daily_program_id: "99999999-1111-1111-1111-111111111111"
  );
  ```

  ```csharp C# theme={null}
  // Coming soon!
  ```
</CodeGroup>

**Response:**

<CodeGroup>
  ```json JavaScript theme={null}
  void
  ```

  ```json cURL theme={null}
  {
    "ok": true
  }
  ```

  ```json Python theme={null}
  None
  ```

  ```json Ruby theme={null}
  nil
  ```

  ```json PHP theme={null}
  void
  ```

  ```json C# theme={null}
  // Coming soon!
  ```
</CodeGroup>

***

## Update the Weekly Program

You set or update the weekly program using `/thermostats/update_weekly_program`. In this command, specify the ID of the thermostat for which you want to set or update the weekly program, as well as the ID of the configured daily program that you want to use for each day of the week. You can use a different daily program for each day of the week, or you can assign the same daily program to multiple days. If you do not want to specify a program for a day, set the corresponding program ID parameter to null.

To replace a weekly program, use `/thermostats/update_weekly_program`, specifying the desired replacement daily program IDs. The new weekly program overwrites any previous weekly program. To clear all daily programs from the weekly program, set all daily program ID parameters to null.

Updating the weekly program returns an [action attempt](../../core-concepts/action-attempts) so that you can track the status of pushing this program change to the thermostat.

The following example assigns the same weekday program to each weekday and the same weekend program to each weekend day:&#x20;

**Request:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  await seam.thermostats.updateWeeklyProgram({
    device_id: '11111111-1111-1111-2222-444444444444',
    monday_program_id: '99999999-1111-1111-1111-111111111111',
    tuesday_program_id: '99999999-1111-1111-1111-111111111111',
    wednesday_program_id: '99999999-1111-1111-1111-111111111111',
    thursday_program_id: '99999999-1111-1111-1111-111111111111',
    friday_program_id: '99999999-1111-1111-1111-111111111111',
    saturday_program_id: '99999999-1111-1111-1111-222222222222',
    sunday_program_id: '99999999-1111-1111-1111-222222222222',
  })
  ```

  ```bash cURL theme={null}
  curl -X 'POST' \
    'https://connect.getseam.com/thermostats/update_weekly_program' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d '{
      "device_id": "11111111-1111-1111-2222-444444444444",
      "monday_program_id": "99999999-1111-1111-1111-111111111111",
      "tuesday_program_id": "99999999-1111-1111-1111-111111111111",
      "wednesday_program_id": "99999999-1111-1111-1111-111111111111",
      "thursday_program_id": "99999999-1111-1111-1111-111111111111",
      "friday_program_id": "99999999-1111-1111-1111-111111111111",
      "saturday_program_id": "99999999-1111-1111-1111-222222222222",
      "sunday_program_id": "99999999-1111-1111-1111-222222222222"
  }'
  ```

  ```python Python theme={null}
  seam.thermostats.update_weekly_program(
    device_id = "11111111-1111-1111-2222-444444444444",
    monday_program_id = "99999999-1111-1111-1111-111111111111",
    tuesday_program_id = "99999999-1111-1111-1111-111111111111",
    wednesday_program_id = "99999999-1111-1111-1111-111111111111",
    thursday_program_id = "99999999-1111-1111-1111-111111111111",
    friday_program_id = "99999999-1111-1111-1111-111111111111",
    saturday_program_id = "99999999-1111-1111-1111-222222222222",
    sunday_program_id = "99999999-1111-1111-1111-222222222222"
  )
  ```

  ```ruby Ruby theme={null}
  seam.thermostats.update_weekly_program(
    device_id: "11111111-1111-1111-2222-444444444444",
    monday_program_id: "99999999-1111-1111-1111-111111111111",
    tuesday_program_id: "99999999-1111-1111-1111-111111111111",
    wednesday_program_id: "99999999-1111-1111-1111-111111111111",
    thursday_program_id: "99999999-1111-1111-1111-111111111111",
    friday_program_id: "99999999-1111-1111-1111-111111111111",
    saturday_program_id: "99999999-1111-1111-1111-222222222222",
    sunday_program_id: "99999999-1111-1111-1111-222222222222"
  )
  ```

  ```php PHP theme={null}
  $seam->thermostats->update_weekly_program(
    device_id: "11111111-1111-1111-2222-444444444444",
    monday_program_id: "99999999-1111-1111-1111-111111111111",
    tuesday_program_id: "99999999-1111-1111-1111-111111111111",
    wednesday_program_id: "99999999-1111-1111-1111-111111111111",
    thursday_program_id: "99999999-1111-1111-1111-111111111111",
    friday_program_id: "99999999-1111-1111-1111-111111111111",
    saturday_program_id: "99999999-1111-1111-1111-222222222222",
    sunday_program_id: "99999999-1111-1111-1111-222222222222"
  );
  ```

  ```csharp C# theme={null}
  // Coming soon!
  ```
</CodeGroup>

**Response:**

<CodeGroup>
  ```json JavaScript theme={null}
  {
    "status": "success",
    "action_attempt_id": "11111111-2222-3333-4444-666666666666",
    "action_type": "PUSH_THERMOSTAT_PROGRAMS",
    "result": {},
    "error": null
  }
  ```

  ```json cURL theme={null}
  {
    "action_attempt": {
      "status": "pending",
      "action_type": "PUSH_THERMOSTAT_PROGRAMS",
      "action_attempt_id": "11111111-2222-3333-4444-666666666666",
      "result": null,
      "error": null
    },
    "ok": true
  }
  ```

  ```json Python theme={null}
  ActionAttempt(
    action_attempt_id='11111111-2222-3333-4444-666666666666',
    action_type='PUSH_THERMOSTAT_PROGRAMS',
    status='success',
    result={},
    error=None
  )
  ```

  ```json Ruby theme={null}
  <Seam::Resources::ActionAttempt:0x005f0
    status="success"
    action_type="PUSH_THERMOSTAT_PROGRAMS"
    action_attempt_id="11111111-2222-3333-4444-666666666666"
    result={}
    error=nil>
  ```

  ```json PHP theme={null}
  {
    "status": "success",
    "action_attempt_id": "11111111-2222-3333-4444-666666666666",
    "action_type": "PUSH_THERMOSTAT_PROGRAMS",
    "result": {},
    "error": null
  }
  ```

  ```json C# theme={null}
  // Coming soon!
  ```
</CodeGroup>


# Creating and Managing Thermostat Schedules
Source: https://docs.seam.co/capability-guides/thermostats/creating-and-managing-thermostat-schedules

Learn how to create, list, get, update, and delete thermostat schedules for thermostats.

Once you have created a set of [climate presets](/capability-guides/thermostats/creating-and-managing-climate-presets/index) for a thermostat, you can define schedules using the [`/thermostats/schedules/create`](/api/thermostats/schedules/create) endpoint. The Seam API's scheduling mechanism is flexible and intelligent. It can prioritize and handle multiple scheduled climate presets. For example, you could [set a fallback](/capability-guides/thermostats/creating-and-managing-climate-presets/setting-the-fallback-climate-preset) energy-saving climate preset for whenever a short-term rental property is unoccupied. Then, you could schedule—in advance—a "comfort" climate preset to correspond to each upcoming guest's stay.

***

## Thermostat Schedule Properties

Each thermostat schedule can contain the following properties:

<table>
  <thead>
    <tr>
      <th>Property</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        <code>name</code>
      </td>

      <td>
        (Optional) User-friendly name to identify the thermostat schedule.
      </td>
    </tr>

    <tr>
      <td>
        <code>climate\_preset\_key</code>
      </td>

      <td>
        (Required) Key of the climate preset to use for the thermostat schedule.
      </td>
    </tr>

    <tr>
      <td>
        <code>is\_override\_allowed</code>
      </td>

      <td>
        (Optional) Indicates whether a person at the thermostat or using the API
        can change (that is, override) the thermostat's settings from an active
        scheduled climate preset.
      </td>
    </tr>

    <tr>
      <td>
        <code>max\_override\_period\_minutes</code>
      </td>

      <td>
        Number of minutes for which a person at the thermostat or using the API
        can change (that is, override) the thermostat's settings after the
        activation of the scheduled climate preset.

        <br />

        <strong>Note:</strong> If you set this value to <code>null</code>, there
        is no enforced maximum override period. That is, the override applies
        until another climate preset becomes active.

        <br />

        Default: <code>null</code>

        <br />

        See also

        <a href="#specifying-manual-override-permissions">
          Specifying Manual Override Permissions
        </a>

        .
      </td>
    </tr>

    <tr>
      <td>
        <code>starts\_at</code>
      </td>

      <td>
        (Required) Date and time at which the thermostat schedule starts, in

        <a href="https://www.iso.org/iso-8601-date-and-time-format.html">
          ISO 8601
        </a>

        format.
      </td>
    </tr>

    <tr>
      <td>
        <code>ends\_at</code>
      </td>

      <td>
        (Required) Date and time at which the thermostat schedule ends, in

        <a href="https://www.iso.org/iso-8601-date-and-time-format.html">
          ISO 8601
        </a>

        format.
      </td>
    </tr>
  </tbody>
</table>

***

## Setting the Schedule

In the Seam API, use the `starts_at` and `ends_at` parameters to define the time period during which to apply an existing climate preset. For example, a short-term rental host could set `starts_at` to the beginning of a guest reservation or perhaps even slightly before the reservation starts so that the property reaches a comfortable temperature in time for guest arrival. The host could set `ends_at` to coincide with the end of the reservation.

`starts_at` is required and must be unique within all the schedules for the thermostat. However, if you want to schedule a climate preset that starts immediately, set `start_at` to a time in the past. Alternately, you can [activate a climate preset](/capability-guides/thermostats/creating-and-managing-climate-presets/activating-a-climate-preset) immediately.

After a scheduled climate preset starts, Seam emits a [`thermostat.temperature_reached_set_point` event](/api/thermostats/events#thermostat-temperature_reached_set_point) when the thermostat reports a temperature within 1° Celsius of the heating or cooling set point specified in this climate preset. You can configure a webhook to watch for this event.

***

## Specifying Manual Override Permissions

When creating a schedule for a thermostat, you can specify `is_override_allowed` and `max_override_period_minutes`. The `is_override_allowed` parameter indicates whether a person at the thermostat or using the Seam API can change the thermostat's settings for the active duration of the thermostat schedule. Setting `max_override_period_minutes` defines the length of the allowed override period. If an override period is allowed, at the end of this period, Seam sets the thermostat back to the climate preset defined by the thermostat schedule. The override period starts again each time a person makes a change at the thermostat or using the API.

Through these override period settings, the Seam API provides you with the flexibility to customize the thermostat behavior to suit your needs. For example, a multifamily property manager may want to give complete control of the thermostat to a unit's residents as soon as they move into the unit. However, a short-term rental host may want to enforce stricter rules to ensure that their guests are using the associated HVAC system in a reasonable manner.

To allow complete control at the thermostat, set `is_override_allowed` to `true` and `max_override_period_minutes` to `null`. To disable manual overrides entirely, set `is_override_allowed` to `false`.

***

## Create a Thermostat Schedule

To create a thermostat schedule, issue a [`/thermostats/schedules/create`](/api/thermostats/schedules/create) request, providing the `device_id` of the desired thermostat, as well as the `climate_preset_key`, and the `starts_at` and `ends_at` timestamps. You can also specify a `name` for the thermostat schedule and the desired `is_override_allowed` and `max_override_period_minutes` values.

**Request:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  await seam.thermostats.schedules.create({
    device_id: '2d488679-6f07-4810-aed2-e726872c1dd5',
    name: "Jim's stay",
    climate_preset_key: 'occupied',
    starts_at: '2024-11-01T15:00:00Z',
    ends_at: '2024-11-05T12:00:00Z',
    is_override_allowed: true,
    max_override_period_minutes: 90,
  })
  ```

  ```bash cURL theme={null}
  curl -X 'POST' \
    'https://connect.getseam.com/thermostats/schedules/create' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d '{
      "device_id": "2d488679-6f07-4810-aed2-e726872c1dd5",
      "name":  "Jim'\''s stay",
      "climate_preset_key": "occupied",
      "starts_at": "2024-11-01T15:00:00Z",
      "ends_at": "2024-11-05T12:00:00Z",
      "is_override_allowed": true,
      "max_override_period_minutes": 90
  }'
  ```

  ```python Python theme={null}
  seam.thermostats.schedules.create(
    device_id = "2d488679-6f07-4810-aed2-e726872c1dd5",
    name = "Jim's stay",
    climate_preset_key = "occupied",
    starts_at = "2024-11-01T15:00:00Z",
    ends_at = "2024-11-05T12:00:00Z",
    is_override_allowed = True,
    max_override_period_minutes = 90
  )
  ```

  ```ruby Ruby theme={null}
  seam.thermostats.schedules.create({
    device_id: "2d488679-6f07-4810-aed2-e726872c1dd5",
    name: "Jim's stay",
    climate_preset_key: "occupied",
    starts_at: "2024-11-01T15:00:00Z",
    ends_at: "2024-11-05T12:00:00Z",
    is_override_allowed: true,
    max_override_period_minutes: 90
  )
  ```

  ```php PHP theme={null}
  $seam->thermostats->schedules->create(
    device_id: "2d488679-6f07-4810-aed2-e726872c1dd5",
    name: "Jim's stay",
    climate_preset_key: "occupied",
    starts_at: "2024-11-01T15:00:00Z",
    ends_at: "2024-11-05T12:00:00Z",
    is_override_allowed: true,
    max_override_period_minutes: 90
  );
  ```

  ```csharp C# theme={null}
  // Coming soon!
  ```
</CodeGroup>

**Response:**

<CodeGroup>
  ```json JavaScript theme={null}
  {
    thermostat_schedule_id: '4a5bd61f-b402-41a5-9757-d92ba1e20708',
    name: "Jim's stay",
    device_id: '2d488679-6f07-4810-aed2-e726872c1dd5',
    climate_preset_key: 'occupied',
    starts_at: '2024-11-01T15:00:00.000Z',
    ends_at: '2024-11-05T12:00:00.000Z',
    is_override_allowed: true,
    max_override_period_minutes: 90,
    ...
  }
  ```

  ```json cURL theme={null}
  {
    "thermostat_schedule": {
      "thermostat_schedule_id": "56d29fcf-0674-4db5-8e03-b2370a77460a",
      "name": "Jim's stay",
      "device_id": "2d488679-6f07-4810-aed2-e726872c1dd5",
      "climate_preset_key": "occupied",
      "starts_at": "2024-11-01T15:00:00.000Z",
      "ends_at": "2024-11-05T12:00:00.000Z",
      "is_override_allowed": true,
      "max_override_period_minutes": 90,
      ...
    },
    "ok": true
  }
  ```

  ```json Python theme={null}
  ThermostatSchedule(
    thermostat_schedule_id='56d29fcf-0674-4db5-8e03-b2370a77460a',
    name="Jim's stay",
    device_id='2d488679-6f07-4810-aed2-e726872c1dd5',
    climate_preset_key='occupied',
    starts_at='2024-11-01T15:00:00.000Z',
    ends_at='2024-11-05T12:00:00.000Z',
    is_override_allowed=True,
    max_override_period_minutes=90,
    ...
  )
  ```

  ```json Ruby theme={null}
  <Seam::Resources::ThermostatSchedule:0x005f0
    thermostat_schedule_id="4a5bd61f-b402-41a5-9757-d92ba1e20708"
    name="Jim's stay"
    device_id="2d488679-6f07-4810-aed2-e726872c1dd5"
    climate_preset_key="occupied"
    starts_at=2024-11-01 15:00:00 UTC
    ends_at=2024-11-05 12:00:00 UTC
    is_override_allowed=true
    max_override_period_minutes=90
    ...
  >
  ```

  ```json PHP theme={null}
  {
    "thermostat_schedule_id": "a05960b9-d787-4621-a7b0-ab76a566e5e8",
    "name": "Jim's stay",
    "device_id": "2d488679-6f07-4810-aed2-e726872c1dd5",
    "climate_preset_key": "occupied",
    "starts_at": "2024-11-01T15:00:00.000Z",
    "ends_at": "2024-11-05T12:00:00.000Z",
    "is_override_allowed": true,
    "max_override_period_minutes": 90,
    ...
  }
  ```

  ```json C# theme={null}
  // Coming soon!
  ```
</CodeGroup>

***

## Schedule Multiple Climate Presets

Suppose a short-term rental host wants to set a fallback "unoccupied" climate preset that takes effect immediately, as well as scheduling an "occupied" climate preset for two periods that correspond to guest reservations.

<img
  alt="Seam handles a fallback climate preset, along with multiple thermostat
schedules."
/>

The following example shows how to set up these schedules:

**Request:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  // Get the thermostat.
  const thermostat = await seam.devices.get({
    device_id: '2d488679-6f07-4810-aed2-e726872c1dd5',
  })

  // Set the fallback climate preset.
  await seam.thermostats.setFallbackClimatePreset({
    device_id: thermostat.device_id,
    climate_preset_key: 'unoccupied',
  })

  // Create the thermostat schedule for the first reservation.
  await seam.thermostats.schedules.create({
    device_id: thermostat.device_id,
    name: "Joe's stay",
    climate_preset_key: 'occupied',
    starts_at: '2024-11-10T15:00:00Z',
    ends_at: '2024-11-15T12:00:00Z',
    is_override_allowed: true,
    max_override_period_minutes: 90,
  })

  // Create the thermostat schedule for the second reservation.
  await seam.thermostats.schedules.create({
    device_id: thermostat.device_id,
    name: "Jane's stay",
    climate_preset_key: 'occupied',
    starts_at: '2024-11-16T15:00:00Z',
    ends_at: '2024-11-18T12:00:00Z',
    is_override_allowed: true,
    max_override_period_minutes: 90,
  })
  ```

  ```bash cURL theme={null}
  # Get the thermostat.
  thermostat=$(
    # Use GET or POST.
    curl -X 'GET' \
      'https://connect.getseam.com/devices/get' \
      -H 'accept: application/json' \
      -H "Authorization: Bearer ${SEAM_API_KEY}" \
      -H 'Content-Type: application/json' \
      -d '{
        "device_id": "2d488679-6f07-4810-aed2-e726872c1dd5"
    }')

  # Set the fallback climate preset.
  curl -X 'POST' \
    'https://connect.getseam.com/thermostats/set_fallback_climate_preset' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d "{
      \"device_id\": \"$(jq -r '.device.device_id' <<< ${thermostat})\",
      \"climate_preset_key\": \"unoccupied\"
  }"

  # Create the thermostat schedule for the first reservation.
  curl -X 'POST' \
    'https://connect.getseam.com/thermostats/schedules/create' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d "{
      \"device_id\": \"$(jq -r '.device.device_id' <<< ${thermostat})\",
      \"name\":  \"Joe's stay\",
      \"climate_preset_key\": \"occupied\",
      \"starts_at\": \"2024-11-10T15:00:00Z\",
      \"ends_at\": \"2024-11-15T12:00:00Z\",
      \"is_override_allowed\": true,
      \"max_override_period_minutes\": 90
  }"

  # Create the thermostat schedule for the second reservation.
  curl -X 'POST' \
    'https://connect.getseam.com/thermostats/schedules/create' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d "{
      \"device_id\": \"$(jq -r '.device.device_id' <<< ${thermostat})\",
      \"name\":  \"Jane's stay\",
      \"climate_preset_key\": \"occupied\",
      \"starts_at\": \"2024-11-16T15:00:00Z\",
      \"ends_at\": \"2024-11-18T12:00:00Z\",
      \"is_override_allowed\": true,
      \"max_override_period_minutes\": 90
  }"
  ```

  ```python Python theme={null}
  # Get the thermostat.
  thermostat = seam.devices.get(
    device_id = "2d488679-6f07-4810-aed2-e726872c1dd5"
  )

  # Set the fallback climate preset.
  seam.thermostats.set_fallback_climate_preset(
    device_id = thermostat.device_id,
    climate_preset_key = "unoccupied"
  )

  # Create the thermostat schedule for the first reservation.
  seam.thermostats.schedules.create(
    device_id = thermostat.device_id,
    name = "Joe's stay",
    climate_preset_key = "occupied",
    starts_at = "2024-11-10T15:00:00Z",
    ends_at = "2024-11-15T12:00:00Z",
    is_override_allowed = True,
    max_override_period_minutes = 90
  )

  # Create the thermostat schedule for the second reservation.
  seam.thermostats.schedules.create(
    device_id = thermostat.device_id,
    name = "Jane's stay",
    climate_preset_key = "occupied",
    starts_at = "2024-11-16T15:00:00Z",
    ends_at = "2024-11-18T12:00:00Z",
    is_override_allowed = True,
    max_override_period_minutes = 90
  )
  ```

  ```ruby Ruby theme={null}
  # Get the thermostat.
  thermostat = seam.devices.get(
    device_id: "2d488679-6f07-4810-aed2-e726872c1dd5"
  )

  # Set the fallback climate preset.
  seam.thermostats.set_fallback_climate_preset(
    device_id: thermostat.device_id,
    climate_preset_key: "unoccupied"
  )

  # Create the thermostat schedule for the first reservation.
  seam.thermostats.schedules.create(
    device_id: thermostat.device_id,
    name: "Joe's stay",
    climate_preset_key: "occupied",
    starts_at: "2024-11-10T15:00:00Z",
    ends_at: "2024-11-15T12:00:00Z",
    is_override_allowed: true,
    max_override_period_minutes: 90
  )

  # Create the thermostat schedule for the second reservation.
  seam.thermostats.schedules.create(
    device_id: thermostat.device_id,
    name: "Jane's stay",
    climate_preset_key: "occupied",
    starts_at: "2024-11-16T15:00:00Z",
    ends_at: "2024-11-18T12:00:00Z",
    is_override_allowed: true,
    max_override_period_minutes: 90
  )
  ```

  ```php PHP theme={null}
  // Get the thermostat.
  $thermostat = $seam->devices->get(
    device_id: "2d488679-6f07-4810-aed2-e726872c1dd5"
  );

  // Set the fallback climate preset.
  $seam->thermostats->set_fallback_climate_preset(
    device_id: $thermostat->device_id,
    climate_preset_key: "unoccupied"
  );

  // Create the thermostat schedule for the first reservation.
  $seam->thermostats->schedules->create(
    device_id: $thermostat->device_id,
    name: "Joe's stay",
    climate_preset_key: "occupied",
    starts_at: "2024-11-10T15:00:00Z",
    ends_at: "2024-11-15T12:00:00Z",
    is_override_allowed: true,
    max_override_period_minutes: 90
  );

  // Create the thermostat schedule for the second reservation.
  $seam->thermostats->schedules->create(
    device_id: $thermostat->device_id,
    name: "Jane's stay",
    climate_preset_key: "occupied",
    starts_at: "2024-11-16T15:00:00Z",
    ends_at: "2024-11-18T12:00:00Z",
    is_override_allowed: true,
    max_override_period_minutes: 90
  );
  ```

  ```csharp C# theme={null}
  // Coming soon!
  ```
</CodeGroup>

**Response:**

<CodeGroup>
  ```json JavaScript theme={null}
  {
    thermostat_schedule_id: '4082a585-cf6e-4f6c-889d-d208fde226d0',
    name: "Joe's stay",
    device_id: '2d488679-6f07-4810-aed2-e726872c1dd5',
    climate_preset_key: 'occupied',
    starts_at: '2024-11-10T15:00:00.000Z',
    ends_at: '2024-11-15T12:00:00.000Z',
    is_override_allowed: true,
    max_override_period_minutes: 90,
    ...
  }
  {
    thermostat_schedule_id: '9d2b1c55-68cc-4c86-8478-dea3249e26b7',
    name: "Jane's stay",
    device_id: '2d488679-6f07-4810-aed2-e726872c1dd5',
    climate_preset_key: 'occupied',
    starts_at: '2024-11-16T15:00:00.000Z',
    ends_at: '2024-11-18T12:00:00.000Z',
    is_override_allowed: true,
    max_override_period_minutes: 90,
    ...
  }
  ```

  ```json cURL theme={null}
  {
    "thermostat_schedule":{
      "thermostat_schedule_id":"a46b96bf-7b4c-408d-b7c6-74ff7c747ff1",
      "name":"Joe's stay",
      "device_id":"2d488679-6f07-4810-aed2-e726872c1dd5",
      "climate_preset_key":"occupied",
      "starts_at":"2024-11-10T15:00:00.000Z",
      "ends_at":"2024-11-15T12:00:00.000Z",
      "is_override_allowed":true,
      "max_override_period_minutes":90,
      ...
    },
    "ok":true
  }
  {
    "thermostat_schedule":{
      "thermostat_schedule_id":"5acded62-dc35-4d37-b94c-35bc68352ea5",
      "name":"Jane's stay",
      "device_id":"2d488679-6f07-4810-aed2-e726872c1dd5",
      "climate_preset_key":"occupied",
      "starts_at":"2024-11-16T15:00:00.000Z",
      "ends_at":"2024-11-18T12:00:00.000Z",
      "is_override_allowed":true,
      "max_override_period_minutes":90,
      ...
    },
    "ok":true
  }
  ```

  ```json Python theme={null}
  ThermostatSchedule(
    thermostat_schedule_id='c02a3cc5-87f2-409d-b21d-164f2c94d37c'
    name="Joe's stay",
    device_id='2d488679-6f07-4810-aed2-e726872c1dd5',
    climate_preset_key='occupied',
    starts_at='2024-11-10T15:00:00.000Z',
    ends_at='2024-11-15T12:00:00.000Z',
    is_override_allowed=True,
    max_override_period_minutes=90,
    ...
  )
  ThermostatSchedule(
    thermostat_schedule_id='ed14ed8d-c012-4d89-af96-053e0c16197d',
    name="Jane's stay",
    device_id='2d488679-6f07-4810-aed2-e726872c1dd5',
    climate_preset_key='occupied',
    starts_at='2024-11-16T15:00:00.000Z',
    ends_at='2024-11-18T12:00:00.000Z',
    is_override_allowed=True,
    max_override_period_minutes=90,
    ...
  )
  ```

  ```json Ruby theme={null}
  <Seam::Resources::ThermostatSchedule:0x005f0
    thermostat_schedule_id="4082a585-cf6e-4f6c-889d-d208fde226d0"
    name="Joe's stay"
    device_id="2d488679-6f07-4810-aed2-e726872c1dd5"
    climate_preset_key="occupied"
    starts_at=2024-11-10 15:00:00 UTC
    ends_at=2024-11-15 12:00:00 UTC
    is_override_allowed=true
    max_override_period_minutes=90
    ...
  >
  <Seam::Resources::ThermostatSchedule:0x005f0
    thermostat_schedule_id="9d2b1c55-68cc-4c86-8478-dea3249e26b7"
    name="Jane's stay"
    device_id="2d488679-6f07-4810-aed2-e726872c1dd5"
    climate_preset_key="occupied"
    starts_at=2024-11-16 15:00:00 UTC
    ends_at=2024-11-18 12:00:00 UTC
    is_override_allowed=true
    max_override_period_minutes=90
    ...
  >
  ```

  ```json PHP theme={null}
  {
    "thermostat_schedule_id": "89d3507e-60e3-4101-bd1b-ba066ec30ad4",
    "name": "Joe's stay",
    "device_id": "2d488679-6f07-4810-aed2-e726872c1dd5",
    "climate_preset_key": "occupied",
    "starts_at": "2024-11-10T15:00:00.000Z",
    "ends_at": "2024-11-15T12:00:00.000Z",
    "is_override_allowed": true,
    "max_override_period_minutes": 90,
    ...
  }
  {
    "thermostat_schedule_id": "665553d1-94f9-4e92-9739-06ac6362c959",
    "name": "Jane's stay",
    "device_id": "2d488679-6f07-4810-aed2-e726872c1dd5",
    "climate_preset_key": "occupied",
    "starts_at": "2024-11-16T15:00:00.000Z",
    "ends_at": "2024-11-18T12:00:00.000Z",
    "is_override_allowed": true,
    "max_override_period_minutes": 90,
    ...
  }
  ```

  ```json C# theme={null}
  // Coming soon!
  ```
</CodeGroup>

***

## List All Thermostat Schedules for a Thermostat

To retrieve all thermostat schedules for a thermostat, issue a [`/thermostats/schedules/list`](/api/thermostats/schedules/list) request, specifying the `device_id` of the desired thermostat.

**Request:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  await seam.thermostats.schedules.list({
    device_id: '2d488679-6f07-4810-aed2-e726872c1dd5',
  })
  ```

  ```bash cURL theme={null}
  curl -X 'POST' \
    'https://connect.getseam.com/thermostats/schedules/list' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d '{
      "device_id": "2d488679-6f07-4810-aed2-e726872c1dd5"
  }'
  ```

  ```python Python theme={null}
  seam.thermostats.schedules.list(
    device_id = "2d488679-6f07-4810-aed2-e726872c1dd5"
  )
  ```

  ```ruby Ruby theme={null}
  seam.thermostats.schedules.list(
    device_id: "2d488679-6f07-4810-aed2-e726872c1dd5"
  )
  ```

  ```php PHP theme={null}
  $seam->thermostats->schedules->list(
    device_id: "2d488679-6f07-4810-aed2-e726872c1dd5"
  );
  ```

  ```csharp C# theme={null}
  // Coming soon!
  ```
</CodeGroup>

**Response:**

<CodeGroup>
  ```json JavaScript theme={null}
  [
    {
      thermostat_schedule_id: '89d3507e-60e3-4101-bd1b-ba066ec30ad4',
      name: "Joe's stay",
      device_id: '2d488679-6f07-4810-aed2-e726872c1dd5',
      climate_preset_key: 'occupied',
      starts_at: '2024-11-10T15:00:00.000Z',
      ends_at: '2024-11-15T12:00:00.000Z',
      is_override_allowed: true,
      max_override_period_minutes: 90,
      ...
    },
    {
      thermostat_schedule_id: '665553d1-94f9-4e92-9739-06ac6362c959',
      name: "Jane's stay",
      device_id: '2d488679-6f07-4810-aed2-e726872c1dd5',
      climate_preset_key: 'occupied',
      starts_at: '2024-11-16T15:00:00.000Z',
      ends_at: '2024-11-18T12:00:00.000Z',
      is_override_allowed: true,
      max_override_period_minutes: 90,
      ...
    }
  ]
  ```

  ```json cURL theme={null}
  {
    "thermostat_schedules": [
      {
        "thermostat_schedule_id":"89d3507e-60e3-4101-bd1b-ba066ec30ad4",
        "name":"Joe's stay",
        "device_id":"2d488679-6f07-4810-aed2-e726872c1dd5",
        "climate_preset_key":"occupied",
        "starts_at":"2024-11-10T15:00:00.000Z",
        "ends_at":"2024-11-15T12:00:00.000Z",
        "is_override_allowed": true,
        "max_override_period_minutes":90,
        ...
      },
      {
        "thermostat_schedule_id":"665553d1-94f9-4e92-9739-06ac6362c959",
        "name":"Jane's stay",
        "device_id":"2d488679-6f07-4810-aed2-e726872c1dd5",
        "climate_preset_key":"occupied",
        "starts_at":"2024-11-16T15:00:00.000Z",
        "ends_at":"2024-11-18T12:00:00.000Z",
        "is_override_allowed": true,
        "max_override_period_minutes":90,
        ...
      }
    ],
    "ok":true
  }
  ```

  ```json Python theme={null}
  [
    ThermostatSchedule(
      thermostat_schedule_id='89d3507e-60e3-4101-bd1b-ba066ec30ad4',
      name="Joe's stay",
      device_id='2d488679-6f07-4810-aed2-e726872c1dd5',
      climate_preset_key='occupied',
      starts_at='2024-11-10T15:00:00.000Z',
      ends_at='2024-11-15T12:00:00.000Z',
      is_override_allowed=True,
      max_override_period_minutes=90,
      ...
    ),
    ThermostatSchedule(
      thermostat_schedule_id='665553d1-94f9-4e92-9739-06ac6362c959',
      name="Jane's stay",
      device_id='2d488679-6f07-4810-aed2-e726872c1dd5',
      climate_preset_key='occupied',
      starts_at='2024-11-16T15:00:00.000Z',
      ends_at='2024-11-18T12:00:00.000Z',
      is_override_allowed=True,
      max_override_period_minutes=90,
      ...
    )
  ]
  ```

  ```json Ruby theme={null}
  [
    <Seam::Resources::ThermostatSchedule:0x005f0
      thermostat_schedule_id="4082a585-cf6e-4f6c-889d-d208fde226d0"
      name="Joe's stay"
      device_id="2d488679-6f07-4810-aed2-e726872c1dd5"
      climate_preset_key="occupied"
      starts_at=2024-11-10 15:00:00 UTC
      ends_at=2024-11-15 12:00:00 UTC
      is_override_allowed=true
      max_override_period_minutes=90
      ...
    >,
    <Seam::Resources::ThermostatSchedule:0x005f0
      thermostat_schedule_id="9d2b1c55-68cc-4c86-8478-dea3249e26b7"
      name="Jane's stay"
      device_id="2d488679-6f07-4810-aed2-e726872c1dd5"
      climate_preset_key="occupied"
      starts_at=2024-11-16 15:00:00 UTC
      ends_at=2024-11-18 12:00:00 UTC
      is_override_allowed=true
      max_override_period_minutes=90
      ...
    >
  ]
  ```

  ```json PHP theme={null}
  [
    {
      "thermostat_schedule_id": "89d3507e-60e3-4101-bd1b-ba066ec30ad4",
      "name": "Joe's stay",
      "device_id": "2d488679-6f07-4810-aed2-e726872c1dd5",
      "climate_preset_key": "occupied",
      "starts_at": "2024-11-10T15:00:00.000Z",
      "ends_at": "2024-11-15T12:00:00.000Z",
      "is_override_allowed": true,
      "max_override_period_minutes": 90,
      ...
    },
    {
      "thermostat_schedule_id": "665553d1-94f9-4e92-9739-06ac6362c959",
      "name": "Jane's stay",
      "device_id": "2d488679-6f07-4810-aed2-e726872c1dd5",
      "climate_preset_key": "occupied",
      "starts_at": "2024-11-16T15:00:00.000Z",
      "ends_at": "2024-11-18T12:00:00.000Z",
      "is_override_allowed": true,
      "max_override_period_minutes": 90,
      ...
    }
  ]
  ```

  ```json C# theme={null}
  // Coming soon!
  ```
</CodeGroup>

***

## Get an Individual Thermostat Schedule

To get a specific thermostat schedule, issue a [`/thermostats/schedules/get`](/api/thermostats/schedules/get) request, including the `thermostat_schedule_id` of the desired thermostat schedule.

**Request:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  await seam.thermostats.schedules.get({
    thermostat_schedule_id: '89d3507e-60e3-4101-bd1b-ba066ec30ad4',
  })
  ```

  ```bash cURL theme={null}
  curl -X 'POST' \
    'https://connect.getseam.com/thermostats/schedules/get' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d '{
      "thermostat_schedule_id": "89d3507e-60e3-4101-bd1b-ba066ec30ad4"
  }'
  ```

  ```python Python theme={null}
  seam.thermostats.schedules.get(
    thermostat_schedule_id = "89d3507e-60e3-4101-bd1b-ba066ec30ad4"
  )
  ```

  ```ruby Ruby theme={null}
  seam.thermostats.schedules.get(
    thermostat_schedule_id: "89d3507e-60e3-4101-bd1b-ba066ec30ad4"
  )
  ```

  ```php PHP theme={null}
  $seam->thermostats->schedules->get(
    thermostat_schedule_id: "89d3507e-60e3-4101-bd1b-ba066ec30ad4"
  );
  ```

  ```csharp C# theme={null}
  // Coming soon!
  ```
</CodeGroup>

**Response:**

<CodeGroup>
  ```json JavaScript theme={null}
  {
    thermostat_schedule_id: '89d3507e-60e3-4101-bd1b-ba066ec30ad4',
    name: "Joe's stay",
    device_id: '2d488679-6f07-4810-aed2-e726872c1dd5',
    climate_preset_key: 'occupied',
    starts_at: '2024-11-10T15:00:00.000Z',
    ends_at: '2024-11-15T12:00:00.000Z',
    is_override_allowed: true,
    max_override_period_minutes: 90,
    ...
  }
  ```

  ```json cURL theme={null}
  {
    "thermostat_schedule": {
      "thermostat_schedule_id":"89d3507e-60e3-4101-bd1b-ba066ec30ad4",
      "name":"Joe's stay",
      "device_id":"2d488679-6f07-4810-aed2-e726872c1dd5",
      "climate_preset_key":"occupied",
      "starts_at":"2024-11-10T15:00:00.000Z",
      "ends_at":"2024-11-15T12:00:00.000Z",
      "is_override_allowed":true,
      "max_override_period_minutes":90,
      ...
    },
    "ok":true
  }
  ```

  ```json Python theme={null}
  ThermostatSchedule(
    thermostat_schedule_id='89d3507e-60e3-4101-bd1b-ba066ec30ad4',
    name="Joe's stay",
    device_id='2d488679-6f07-4810-aed2-e726872c1dd5',
    climate_preset_key='occupied',
    starts_at='2024-11-10T15:00:00.000Z',
    ends_at='2024-11-15T12:00:00.000Z',
    is_override_allowed=True,
    max_override_period_minutes=90,
    ...
  )
  ```

  ```json Ruby theme={null}
  <Seam::Resources::ThermostatSchedule:0x005f0
    thermostat_schedule_id="89d3507e-60e3-4101-bd1b-ba066ec30ad4"
    name="Joe's stay"
    device_id="2d488679-6f07-4810-aed2-e726872c1dd5"
    climate_preset_key="occupied"
    starts_at=2024-11-10 15:00:00 UTC
    ends_at=2024-11-15 12:00:00 UTC
    is_override_allowed=true
    max_override_period_minutes=90
    ...
  >
  ```

  ```json PHP theme={null}
  {
    "thermostat_schedule_id": "89d3507e-60e3-4101-bd1b-ba066ec30ad4",
    "name": "Joe's stay",
    "device_id": "2d488679-6f07-4810-aed2-e726872c1dd5",
    "climate_preset_key": "occupied",
    "starts_at": "2024-11-10T15:00:00.000Z",
    "ends_at": "2024-11-15T12:00:00.000Z",
    "is_override_allowed": true,
    "max_override_period_minutes": 90,
    ...
  }
  ```

  ```json C# theme={null}
  // Coming soon!
  ```
</CodeGroup>

***

## Update a Thermostat Schedule

To update a thermostat schedule, issue a [`/thermostats/schedules/update`](/api/thermostats/schedules/update) request, providing the `thermostat_schedule_id` of the desired thermostat schedule and the desired updated settings.

**Request:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  await seam.thermostats.schedules.update({
    thermostat_schedule_id: '89d3507e-60e3-4101-bd1b-ba066ec30ad4',
    ends_at: '2024-11-15T15:00:00Z',
  })
  ```

  ```bash cURL theme={null}
  curl -X 'POST' \
    'https://connect.getseam.com/thermostats/schedules/update' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d '{
      "thermostat_schedule_id": "89d3507e-60e3-4101-bd1b-ba066ec30ad4",
      "ends_at": "2024-11-15T15:00:00Z"
  }'
  ```

  ```python Python theme={null}
  seam.thermostats.schedules.update(
    thermostat_schedule_id = "89d3507e-60e3-4101-bd1b-ba066ec30ad4",
    ends_at = "2024-11-15T15:00:00Z"
  )
  ```

  ```ruby Ruby theme={null}
  seam.thermostats.schedules.update(
    thermostat_schedule_id: "89d3507e-60e3-4101-bd1b-ba066ec30ad4",
    ends_at: "2024-11-15T15:00:00Z"
  )
  ```

  ```php PHP theme={null}
  $seam->thermostats->schedules->update(
    thermostat_schedule_id: "89d3507e-60e3-4101-bd1b-ba066ec30ad4",
    ends_at: "2024-11-15T15:00:00Z"
  );
  ```

  ```csharp C# theme={null}
  // Coming soon!
  ```
</CodeGroup>

**Response:**

<CodeGroup>
  ```json JavaScript theme={null}
  void
  ```

  ```json cURL theme={null}
  {
    "ok": true
  }
  ```

  ```json Python theme={null}
  None
  ```

  ```json Ruby theme={null}
  nil
  ```

  ```json PHP theme={null}
  void
  ```

  ```json C# theme={null}
  // Coming soon!
  ```
</CodeGroup>

***

## Delete a Thermostat Schedule

To delete a thermostat schedule, issue a [`/thermostats/schedules/delete`](/api/thermostats/schedules/delete) request, providing the `thermostat_schedule_id` of the desired thermostat schedule.

**Request:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  await seam.thermostats.schedules.delete({
    thermostat_schedule_id: '2d488679-6f07-4810-aed2-e726872c1dd5',
  })
  ```

  ```bash cURL theme={null}
  curl -X 'POST' \
    'https://connect.getseam.com/thermostats/schedules/delete' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d '{
      "thermostat_schedule_id": "2d488679-6f07-4810-aed2-e726872c1dd5"
  }'
  ```

  ```python Python theme={null}
  seam.thermostats.schedules.delete(
    thermostat_schedule_id = "2d488679-6f07-4810-aed2-e726872c1dd5"
  )
  ```

  ```ruby Ruby theme={null}
  seam.thermostats.schedules.delete(
    thermostat_schedule_id: "2d488679-6f07-4810-aed2-e726872c1dd5"
  )
  ```

  ```php PHP theme={null}
  $seam->thermostats->schedules->delete(
    thermostat_schedule_id: "2d488679-6f07-4810-aed2-e726872c1dd5"
  );
  ```

  ```csharp C# theme={null}
  // Coming soon!
  ```
</CodeGroup>

**Response:**

<CodeGroup>
  ```json JavaScript theme={null}
  void
  ```

  ```json cURL theme={null}
  {
    "ok": true
  }
  ```

  ```json Python theme={null}
  None
  ```

  ```json Ruby theme={null}
  nil
  ```

  ```json PHP theme={null}
  void
  ```

  ```json C# theme={null}
  // Coming soon!
  ```
</CodeGroup>


# Thermostats
Source: https://docs.seam.co/capability-guides/thermostats/index

Learn about managing smart thermostats that automatically adjust and program your users' heating and cooling systems for comfort and cost savings.

<img alt="The Seam API provides flexible and robust functionality that enables you to control your users' thermostats." />

The Seam API provides flexible and robust functionality that enables you to control your users' thermostats. In addition to monitoring a thermostat and making immediate changes to its climate settings, with the Seam API, you can create and schedule climate presets, and you can create daily and weekly thermostat programs.

The Seam API's thermostat features enable you to satisfy a variety of scenarios, including the following and many more:

* You can synchronize the thermostat automatically for occupancy.
* You can enable comfortable temperature settings in advance of occupancy. Then, you can minimize costs and maximize efficiency by scheduling your property's thermostats to return to energy savings settings when the property is empty.
* You can use an app to program different climates to apply throughout the day. You can also set your thermostat to an energy-saving vacation mode when you're away.
* You can set unoccupied units' thermostats to energy saving settings and also schedule comfortable climates when units are occupied. Further, you can pass control of a unit's thermostats to the new residents.
* You can configure Seam to help you monitor your thermostats proactively. In this way, reported temperatures outside acceptable thresholds automatically alert you to potential HVAC system issues.

<iframe title="YouTube video" />

***

## Managing Thermostats with Seam

First, connect your users' thermostats to Seam using the [Seam Console](/core-concepts/seam-console/index) or [Connect Webviews](/core-concepts/connect-webviews/index). Connect Webviews provide authorization flows that enable your users to connect their own thermostats to Seam. Then, to control your users' thermostats with Seam, use the following feature sets in the Seam HTTP API or any of the Seam SDKs:

### Learn and Monitor

Retrieve and monitor your users' thermostats using the [`/thermostats/list`](/api/thermostats/list) and [`/devices/get`](/api/devices/get) endpoints. The Seam API returns robust, up-to-date information about your connected thermostats. In addition, you can use these endpoints to learn the capabilities of each thermostat.

Further, you can use the [`/thermostats/set_temperature_threshold`](/api/thermostats/set_temperature_threshold) endpoint to set upper and lower acceptable temperature bounds. If the thermostat reports a temperature outside this range, Seam emits a [`thermostat.temperature_threshold_exceeded` event](/api/thermostats/events#thermostat-temperature_threshold_exceeded).

### Perform Remote Management

Manage your users' thermostats remotely using "imperative" endpoints. That is, depending on the capabilities of a thermostat, you can use the Seam API to set the thermostat to heat mode, cool mode, heat/cool (auto) mode, eco mode (for Google Nest), or off. In addition, you can set the thermostat's fan mode setting to `on`, `auto`, or `circulate`.

### Create Climate Presets

Create named climate presets, such as "occupied," "eco," "unoccupied," "vacation mode," and so on. In each of these custom climate presets, and depending on each thermostat's capabilities, you can define the desired heating and cooling set points, as well as the fan mode setting. These presets make it quick and efficient for users to apply consistent climate settings tailored to different scenarios, enhancing both comfort and energy efficiency.

### Set the Fallback Preset

You can set one of the configured climate presets as the fallback. Whenever another climate preset is not active, Seam reverts the thermostat back to the fallback climate preset.

### Create Thermostat Schedules

Schedule the climate presets that you have created. Simply specify the key of the climate preset, along with a starting and ending timestamp. You can also indicate whether a person at the thermostat or using the API can change the thermostat's settings for the duration of the thermostat schedule. Further, you can set the maximum override period in minutes. At the end of this override period, Seam sets the thermostat back to the climate preset defined by the thermostat schedule.

You can schedule multiple climate presets to meet your needs. Seam handles the prioritization of scheduled climate presets.

Note that, in addition to scheduling named climate presets, you can also activate a climate preset immediately.

### Configure Weekly Thermostat Programs

You can define custom weekly programs for any thermostat that Seam supports. Start by defining a set of daily thermostat programs, each consisting of sets of periods. For each period, specify a starting time and the key that identifies the configured climate preset to apply at the starting time. Then, assemble the thermostat's weekly program. For each day, you can specify the ID of a configured daily program. Once you have set the weekly program, you can update it again to change any of the assigned daily programs. Further, you can also update any of the daily programs to change the starting times and the corresponding climate presets.

Seam handles the interaction between thermostat programs and schedules, so you can define both for a single device.

***

## Thermostat Capabilities

Seam decomposes the ensemble of features that a thermostat provides into one or more capabilities, as follows:

* `device.can_hvac_heat`
* `device.can_hvac_cool`
* `device.can_hvac_heat_cool`
* `device.can_turn_off_hvac`
* `device.can_program_thermostat_weekly_programs`

For detailed information about these capabilities, see [Device and System Capabilities](../../capability-guides/device-and-system-capabilities).

***

## Supported Devices

Seam supports integration with the following smart thermostat manufacturers:

<table>
  <thead>
    <tr>
      <th />

      <th />

      <th />

      <th />

      <th />

      <th />
    </tr>
  </thead>

  <tbody>
    <tr>
      <td />

      <td>
        <strong>ecobee Thermostats</strong>
      </td>

      <td />

      <td />

      <td>
        <a href="/device-and-system-integration-guides/ecobee-thermostats/index">
          ecobee-thermostats.md
        </a>
      </td>

      <td>
        <a href="/images/ecobee-logo.png">ecobee-logo.png</a>
      </td>
    </tr>

    <tr>
      <td />

      <td>
        <strong>Google Nest Thermostats</strong>
      </td>

      <td />

      <td />

      <td>
        <a href="/device-and-system-integration-guides/google-nest-thermostats/index">
          google-nest-thermostats
        </a>
      </td>

      <td>
        <a href="/images/nest-logo.png">nest-logo.png</a>
      </td>
    </tr>

    <tr>
      <td />

      <td>
        <strong>Honeywell Resideo Thermostats</strong>
      </td>

      <td />

      <td />

      <td>
        <a href="/device-and-system-integration-guides/honeywell-thermostats/index">
          honeywell-thermostats
        </a>
      </td>

      <td>
        <a href="/images/honeywell_logo.png">honeywell\_logo.png</a>
      </td>
    </tr>

    <tr>
      <td />

      <td>
        <strong>Sensi Thermostats</strong>
      </td>

      <td />

      <td />

      <td>
        <a href="/device-and-system-integration-guides/sensi-thermostats/index">
          broken-reference
        </a>
      </td>

      <td>
        <a href="/images/sensi-logo.png">sensi-logo.png</a>
      </td>
    </tr>
  </tbody>
</table>

***

## Next Steps

To learn how to manage thermostats, see the following guides:

* [Understanding Thermostat Concepts](/capability-guides/thermostats/understanding-thermostat-concepts/index)
* [Retrieving Thermostats](/capability-guides/thermostats/retrieving-thermostats)
* [Setting and Monitoring Temperature Thresholds](../../capability-guides/thermostats/setting-and-monitoring-temperature-thresholds)
* [Setting the Current HVAC and Fan Mode Settings](/capability-guides/thermostats/configure-current-climate-settings)
* [Creating and Managing Climate Presets](/capability-guides/thermostats/creating-and-managing-climate-presets/index)
* [Setting the Fallback Climate Preset](../../capability-guides/thermostats/creating-and-managing-climate-presets/setting-the-fallback-climate-preset)
* [Activating a Climate Preset](../../capability-guides/thermostats/creating-and-managing-climate-presets/activating-a-climate-preset)
* [Creating and Managing Thermostat Schedules](../../capability-guides/thermostats/creating-and-managing-thermostat-schedules)
* [Creating and Managing Thermostat Programs](../../capability-guides/thermostats/creating-and-managing-thermostat-programs)


# Retrieving Thermostats
Source: https://docs.seam.co/capability-guides/thermostats/retrieving-thermostats

Learn how to retrieve all thermostats or a specific thermostat by ID.

When you use the [`/thermostats/list`](/api/thermostats/list) and [`/devices/get`](/api/devices/get) endpoints to retrieve information about your connected thermostats, the Seam API returns the following categories of information:

<table>
  <thead>
    <tr>
      <th>Category</th>
      <th>Details</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Current conditions </td>

      <td>
        Current temperature in Fahrenheit and Celsius, current relative
        humidity, and so on. This includes such properties as
        <code>temperature\_celsius</code>, <code>temperature\_fahrenheit</code>,
        <code>is\_cooling</code>, <code>is\_heating</code>,
        <code>is\_fan\_running</code>, <code>relative\_humidity</code>
      </td>
    </tr>

    <tr>
      <td>Current operational status</td>

      <td>
        Whether the associated HVAC system is currently heating or cooling,
        whether the fan is currently running. These properties are named
        <code>current\_climate\_setting</code> and reflect what the thermostat is
        set to 'achieve'.
      </td>
    </tr>

    <tr>
      <td>Available HVAC modes for the thermostat</td>

      <td>
        <code>heat</code>, <code>cool</code>, <code>heat\_cool</code>, and
        <code>off</code>.
      </td>
    </tr>

    <tr>
      <td>Available fan modes for the thermostat</td>

      <td>
        <code>on</code>, <code>auto</code>, and <code>circulate</code>.
      </td>
    </tr>

    <tr>
      <td>
        Thermostat <a href="/capability-guides/thermostats#thermostat-capabilities">capability flags</a>
      </td>

      <td>
        <p>Capabilities of the thermostat—at a granular level.</p>
        <p>These capability flags include the following:</p>

        <ul>
          <li>
            <code>device.can\_hvac\_heat</code>
          </li>

          <li>
            <code>device.can\_hvac\_cool</code>
          </li>

          <li>
            <code>device.can\_hvac\_heat\_cool</code>
          </li>

          <li>
            <code>device.can\_turn\_off\_hvac</code>
          </li>
        </ul>
      </td>
    </tr>

    <tr>
      <td>Available climate presets</td>
      <td>Climate presets that you can schedule on the thermostat.</td>
    </tr>

    <tr>
      <td>Climate preset constraints</td>

      <td>
        Constraints related to climate presets for the specific thermostat brand
        or model.

        <br />

        For example, a thermostat might have a minimum or maximum cooling or
        heating

        <a href="/capability-guides/thermostats/understanding-thermostat-concepts/set-points">
          set point
        </a>

        or a

        <a href="../../capability-guides/thermostats/understanding-thermostat-concepts/set-points#minimum-heating-cooling-temperature-delta">
          minimum delta
        </a>

        between the cooling and heating set points.
      </td>
    </tr>
  </tbody>
</table>

## List All Thermostats

To retrieve all [thermostats](./), issue a [`/thermostats/list`](/api/thermostats/list) request. You can filter by a variety of criteria, including `connected_account_id`, `connect_webview_id`, `manufacturer`, `user_identifier_key`, and so on.

The following example retrieves all Google Nest thermostats:

**Request:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  await seam.thermostats.list({
    manufacturer: 'nest',
  })
  ```

  ```bash cURL theme={null}
  # Use GET or POST.
  curl -X 'GET' \
    'https://connect.getseam.com/thermostats/list' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${API_KEY}" \
    -H 'Content-Type: application/json' \
    -d '{
    "manufacturer": "nest"
    }'
  ```

  ```python Python theme={null}
  seam.thermostats.list(
    manufacturer = "nest"
  )
  ```

  ```ruby Ruby theme={null}
  seam.thermostats.list(
    manufacturer: "nest"
  )
  ```

  ```php PHP theme={null}
  $seam->thermostats->list(
    manufacturer: "nest"
  );
  ```

  ```csharp C# theme={null}
  // Coming soon!
  ```
</CodeGroup>

**Response:**

<CodeGroup>
  ```json JavaScript theme={null}
  [
    {
      device_id: 'a4b775e3-feb2-4c6b-8e78-a73ec2d70b61',
      device_type: 'nest_thermostat',
      properties: {
        online: true,
        is_cooling: false,
        is_heating: false,
        manufacturer: 'nest',
        is_fan_running: false,
        relative_humidity: 0.46,
        temperature_celsius: 24.64,
        temperature_fahrenheit: 76.352,
        available_hvac_mode_settings: [
          'heat',
          'cool',
          'heat_cool',
          'off'
        ],
        current_climate_setting: {
          display_name: 'eco',
          hvac_mode_setting: 'heat_cool',
          manual_override_allowed: true,
          cooling_set_point_celsius: 25,
          cooling_set_point_fahrenheit: 77,
          heating_set_point_celsius: 20,
          heating_set_point_fahrenheit: 68
        },
        ...
      },
      can_hvac_cool: true,
      can_hvac_heat: true,
      can_turn_off_hvac: true,
      can_hvac_heat_cool: true,
      ...
    },
    ...
  ]
  ```

  ```json cURL theme={null}
  {
    "thermostats": [
      {
        "device_id": "a4b775e3-feb2-4c6b-8e78-a73ec2d70b61",
        "device_type": "nest_thermostat",
        "properties": {
          "online": true,
          "is_cooling": false,
          "is_heating": false,
          "is_fan_running": false,
          "manufacturer": "nest",
          "relative_humidity": 0.46,
          "temperature_celsius": 24.64,
          "temperature_fahrenheit": 76.352,
          "current_climate_setting": {
            "display_name": "eco",
            "hvac_mode_setting": "heat_cool",
            "manual_override_allowed": true,
            "cooling_set_point_celsius": 25,
            "cooling_set_point_fahrenheit": 77,
            "heating_set_point_celsius": 20,
            "heating_set_point_fahrenheit": 68
          },
          "available_hvac_mode_settings": [
            "heat",
            "cool",
            "heat_cool",
            "off"
          ],
          ...
        },
        "can_hvac_cool": true,
        "can_hvac_heat": true,
        "can_turn_off_hvac": true,
        "can_hvac_heat_cool": true,
        ...
      },
      ...
    ],
    "ok": true
  }
  ```

  ```json Python theme={null}
  [
    Device(
      can_hvac_cool=True,
      can_hvac_heat=True,
      can_hvac_heat_cool=True,
      can_turn_off_hvac=True,
      device_id='a4b775e3-feb2-4c6b-8e78-a73ec2d70b61',
      device_type='nest_thermostat',
      properties={
        'available_hvac_mode_settings': [
          'heat',
          'cool',
          'heat_cool',
          'off'
        ],
        'current_climate_setting': {
          'display_name': 'eco',
          'cooling_set_point_celsius': 25,
          'cooling_set_point_fahrenheit': 77,
          'heating_set_point_celsius': 20,
          'heating_set_point_fahrenheit': 68,
          'hvac_mode_setting': 'heat_cool',
          'manual_override_allowed': True
        },
        'is_cooling': False,
        'is_fan_running': False,
        'is_heating': False,
        'manufacturer': 'nest',
        'online': True,
        'relative_humidity': 0.46,
        'temperature_celsius': 24.64,
        'temperature_fahrenheit': 76.352,
        ...
      },
      ...
    ),
    ...
  ]
  ```

  ```json Ruby theme={null}
  [
    <Seam::Resources::Device:0x005f0
      device_id="a4b775e3-feb2-4c6b-8e78-a73ec2d70b61"
      device_type="nest_thermostat"
      properties=#<Seam::DeepHashAccessor:0x0000016b1791f068 @data={
        "online"=>true,
        "is_cooling"=>false,
        "is_heating"=>false,
        "manufacturer"=>"nest",
        "is_fan_running"=>false,
        "relative_humidity"=>0.36,
        "temperature_celsius"=>21.11111111111111,
        "temperature_fahrenheit"=>70,
        "available_hvac_mode_settings"=>[
          "heat",
          "cool",
          "heat_cool",
          "off"
        ],
        "current_climate_setting"=>{
          "climate_preset_key"=>"unoccupied",
          "can_edit"=>true,
          "can_delete"=>true,
          "display_name"=>"unoccupied",
          "fan_mode_setting"=>"auto",
          "hvac_mode_setting"=>"heat_cool",
          "manual_override_allowed"=>true,
          "cooling_set_point_celsius"=>30,
          "heating_set_point_celsius"=>15,
          "cooling_set_point_fahrenheit"=>86,
          "heating_set_point_fahrenheit"=>59
        },
        ...
      }>
      can_hvac_cool=true
      can_hvac_heat=true
      can_turn_off_hvac=true
      can_hvac_heat_cool=true
      ...
    >,
    ...
  ]
  ```

  ```json PHP theme={null}
  [
    {
      "can_hvac_cool": true,
      "can_hvac_heat": true,
      "can_hvac_heat_cool": true,
      "can_turn_off_hvac": true,
      "device_id": "a4b775e3-feb2-4c6b-8e78-a73ec2d70b61",
      "device_type": "nest_thermostat",
      "properties": {
        "manufacturer": "nest",
        "online": true,
        "available_hvac_mode_settings": [
          "heat",
          "cool",
          "heat_cool",
          "off"
        ],
        "current_climate_setting": {
          "display_name": "eco",
          "cooling_set_point_celsius": 25,
          "cooling_set_point_fahrenheit": 77,
          "heating_set_point_celsius": 20,
          "heating_set_point_fahrenheit": 68,
          "hvac_mode_setting": "heat_cool",
          "manual_override_allowed": true
        },
        "is_cooling": false,
        "is_fan_running": false,
        "is_heating": false,
        "relative_humidity": 0.46,
        "temperature_celsius": 24.64,
        "temperature_fahrenheit": 76.352,
        ...
      },
      ...
    },
    ...
  ]
  ```

  ```json C# theme={null}
  // Coming soon!
  ```
</CodeGroup>

***

## Get an Individual Thermostat

To get a specific [thermostat](./), issue a [`/devices/get`](/api/devices/get) request, including the desired `device_id`.

**Request:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  await seam.devices.get({
    device_id: 'a4b775e3-feb2-4c6b-8e78-a73ec2d70b61',
  })
  ```

  ```bash cURL theme={null}
  # 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": "a4b775e3-feb2-4c6b-8e78-a73ec2d70b61"
  }'
  ```

  ```python Python theme={null}
  seam.devices.get(
    device_id = "a4b775e3-feb2-4c6b-8e78-a73ec2d70b61"
  )
  ```

  ```ruby Ruby theme={null}
  # Coming soon!
  ```

  ```php PHP theme={null}
  $seam->devices->get(
    device_id: "a4b775e3-feb2-4c6b-8e78-a73ec2d70b61"
  );
  ```

  ```csharp C# theme={null}
  // Coming soon!
  ```
</CodeGroup>

**Response:**

<CodeGroup>
  ```json JavaScript theme={null}
  {
    device_id: 'a4b775e3-feb2-4c6b-8e78-a73ec2d70b61',
    device_type: 'nest_thermostat',
    properties: {
      online: true,
      is_cooling: false,
      is_heating: false,
      manufacturer: 'nest',
      is_fan_running: false,
      relative_humidity: 0.46,
      temperature_celsius: 24.64,
      temperature_fahrenheit: 76.352,
      current_climate_setting: [Object],
      available_hvac_mode_settings: [
        'heat',
        'cool',
        'heat_cool',
        'off'
      ],
      current_climate_setting: {
        display_name: 'eco',
        hvac_mode_setting: 'heat_cool',
        manual_override_allowed: true,
        cooling_set_point_celsius: 25,
        cooling_set_point_fahrenheit: 77,
        heating_set_point_celsius: 20,
        heating_set_point_fahrenheit: 68
      },
      ...
    },
    can_hvac_cool: true,
    can_hvac_heat: true,
    can_turn_off_hvac: true,
    can_hvac_heat_cool: true,
    ...
  }
  ```

  ```json cURL theme={null}
  {
    "device": {
      "device_id": "a4b775e3-feb2-4c6b-8e78-a73ec2d70b61",
      "device_type": "nest_thermostat",
      "properties": {
        "online": true,
        "is_cooling": false,
        "is_heating": false,
        "is_fan_running": false,
        "manufacturer": "nest",
        "relative_humidity": 0.46,
        "temperature_celsius": 24.64,
        "temperature_fahrenheit": 76.352,
        "current_climate_setting": {
          "display_name": "eco",
          "hvac_mode_setting": "heat_cool",
          "manual_override_allowed": true,
          "cooling_set_point_celsius": 25,
          "cooling_set_point_fahrenheit": 77,
          "heating_set_point_celsius": 20,
          "heating_set_point_fahrenheit": 68
        },
        "available_hvac_mode_settings": [
          "heat",
          "cool",
          "heat_cool",
          "off"
        ],
        ...
      },
      "can_hvac_cool": true,
      "can_hvac_heat": true,
      "can_turn_off_hvac": true,
      "can_hvac_heat_cool": true,
      ...
    },
    "ok": true
  }
  ```

  ```json Python theme={null}
  Device(
    can_hvac_cool=True,
    can_hvac_heat=True,
    can_hvac_heat_cool=True,
    can_turn_off_hvac=True,
    device_id='a4b775e3-feb2-4c6b-8e78-a73ec2d70b61',
    device_type='nest_thermostat',
    properties={
      'available_hvac_mode_settings': [
        'heat',
        'cool',
        'heat_cool',
        'off'
      ],
      'current_climate_setting': {
        'display_name': 'eco',
        'cooling_set_point_celsius': 25,
        'cooling_set_point_fahrenheit': 77,
        'heating_set_point_celsius': 20,
        'heating_set_point_fahrenheit': 68,
        'hvac_mode_setting': 'heat_cool',
        'manual_override_allowed': True
      },
      'is_cooling': False,
      'is_fan_running': False,
      'is_heating': False,
      'manufacturer': 'nest',
      'online': True,
      'relative_humidity': 0.46,
      'temperature_celsius': 24.64,
      'temperature_fahrenheit': 76.352,
      ...
    },
    ...
  )
  ```

  ```json Ruby theme={null}
  # Coming soon!
  ```

  ```json PHP theme={null}
  {
    "can_hvac_cool": true,
    "can_hvac_heat": true,
    "can_hvac_heat_cool": true,
    "can_turn_off_hvac": true,
    "device_id": "a4b775e3-feb2-4c6b-8e78-a73ec2d70b61",
    "device_type": "nest_thermostat",
    "properties": {
      "manufacturer": "nest",
      "online": true,
      "available_hvac_mode_settings": [
        "heat",
        "cool",
        "heat_cool",
        "off"
      ],
      "current_climate_setting": {
        "display_name": "eco",
        "cooling_set_point_celsius": 25,
        "cooling_set_point_fahrenheit": 77,
        "heating_set_point_celsius": 20,
        "heating_set_point_fahrenheit": 68,
        "hvac_mode_setting": "heat_cool",
        "manual_override_allowed": true
      },
      "is_cooling": false,
      "is_fan_running": false,
      "is_heating": false,
      "relative_humidity": 0.46,
      "temperature_celsius": 24.64,
      "temperature_fahrenheit": 76.352,
      ...
    },
    ...
  }
  ```

  ```json C# theme={null}
  // Coming soon!
  ```
</CodeGroup>


# Setting and Monitoring Temperature Thresholds
Source: https://docs.seam.co/capability-guides/thermostats/setting-and-monitoring-temperature-thresholds

Learn how to use temperature thresholds to monitor your thermostat for potential HVAC system misuse or malfunctioning.

You can configure Seam to emit a [`thermostat.temperature_threshold_exceeded` event](/api/thermostats/events#thermostat-temperature_threshold_exceeded) if a thermostat reports a temperature outside a specific threshold range. This capability helps you to monitor your thermostats proactively, alerting you to potential HVAC system misuse or malfunctioning.

Use the [`/thermostats/set_temperature_threshold`](/api/thermostats/set_temperature_threshold) endpoint to set upper and lower acceptable temperature bounds. Then, you can use a [webhook](../../developer-tools/webhooks) to monitor for `thermostat.temperature_threshold_exceeded` events.

When the thermostat reports a temperature outside the threshold range, Seam also adds a warning on the thermostat. You can use the [`/devices/get`](/api/devices/get) endpoint to get the thermostat and then inspect its `device.warnings` property.

***

## Set a Temperature Threshold

To set a temperature threshold for a thermostat, issue a [`/thermostats/set_temperature_threshold`](/api/thermostats/set_temperature_threshold) request, providing the `device_id` of the desired thermostat. Also, include the following parameters:

* `lower_limit_celsius` or `lower_limit_fahrenheit`
* `upper_limit_celsius` or `upper_limit_fahrenheit`

**Request:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  await seam.thermostats.setTemperatureThreshold({
    device_id: '2d488679-6f07-4810-aed2-e726872c1dd5',
    lower_limit_celsius: 4,
    upper_limit_celsius: 30,
  })
  ```

  ```bash cURL theme={null}
  curl -X 'POST' \
    'https://connect.getseam.com/thermostats/set_temperature_threshold' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d '{
      "device_id": "2d488679-6f07-4810-aed2-e726872c1dd5",
      "lower_limit_celsius": 4,
      "upper_limit_celsius": 30
  }'
  ```

  ```python Python theme={null}
  seam.thermostats.set_temperature_threshold(
    device_id = "2d488679-6f07-4810-aed2-e726872c1dd5",
    lower_limit_celsius = 4,
    upper_limit_celsius = 30
  )
  ```

  ```ruby Ruby theme={null}
  # Coming soon!
  ```

  ```php PHP theme={null}
  $seam->thermostats->set_temperature_threshold(
    device_id: "2d488679-6f07-4810-aed2-e726872c1dd5",
    lower_limit_celsius: 4,
    upper_limit_celsius: 30
  );
  ```

  ```java C# theme={null}
  // Coming soon!
  ```
</CodeGroup>

**Response:**

<CodeGroup>
  ```json JavaScript theme={null}
  void
  ```

  ```json cURL theme={null}
  {
    "ok": true
  }
  ```

  ```json Python theme={null}
  None
  ```

  ```json Ruby theme={null}
  # Coming soon!
  ```

  ```json PHP theme={null}
  void
  ```

  ```json C# theme={null}
  // Coming soon!
  ```
</CodeGroup>

***

## View a Temperature Threshold

The temperature threshold range that you set for a thermostat is a property of the [`thermostat`](/capability-guides/thermostats) resource itself. To view the threshold values, use the [`/devices/get`](/api/devices/get) endpoint and inspect the `thermostat.temperature_threshold`.

**Request:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  await seam.devices.get({
    device_id: 'a4b775e3-feb2-4c6b-8e78-a73ec2d70b61',
  })
  ```

  ```bash cURL theme={null}
  # 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": "a4b775e3-feb2-4c6b-8e78-a73ec2d70b61"
  }'
  ```

  ```python Python theme={null}
  seam.devices.get(
    device_id = "a4b775e3-feb2-4c6b-8e78-a73ec2d70b61"
  )
  ```

  ```ruby Ruby theme={null}
  # Coming soon!
  ```

  ```php PHP theme={null}
  $seam->devices->get(
    device_id: "a4b775e3-feb2-4c6b-8e78-a73ec2d70b61"
  );
  ```

  ```csharp C# theme={null}
  // Coming soon!
  ```
</CodeGroup>

**Response:**

<CodeGroup>
  ```json JavaScript theme={null}
  {
    device_id: 'a4b775e3-feb2-4c6b-8e78-a73ec2d70b61',
    temperature_threshold: {
      lower_limit_celsius: 4,
      lower_limit_fahrenheit: 39.2,
      upper_limit_celsius: 30,
      upper_limit_fahrenheit: 86
    },
    ...
  }
  ```

  ```json cURL theme={null}
  {
    "device": {
      "device_id": "a4b775e3-feb2-4c6b-8e78-a73ec2d70b61",
      "temperature_threshold": {
        "lower_limit_celsius": 4,
        "lower_limit_fahrenheit": 39.2,
        "upper_limit_celsius": 30,
        "upper_limit_fahrenheit": 86
      },
      ...
    },
    "ok": true
  }
  ```

  ```json Python theme={null}
  Device(
    device_id='a4b775e3-feb2-4c6b-8e78-a73ec2d70b61',
    temperature_threshold={
      lower_limit_celsius: 4,
      lower_limit_fahrenheit: 39.2,
      upper_limit_celsius: 30,
      upper_limit_fahrenheit: 86
    },
    ...
  )
  ```

  ```json Ruby theme={null}
  # Coming soon!
  ```

  ```json PHP theme={null}
  {
    "device_id": "a4b775e3-feb2-4c6b-8e78-a73ec2d70b61",
    "temperature_threshold": {
      "lower_limit_celsius": 4,
      "lower_limit_fahrenheit": 39.2,
      "upper_limit_celsius": 30,
      "upper_limit_fahrenheit": 86
    },
    ...
  }
  ```

  ```json C# theme={null}
  // Coming soon!
  ```
</CodeGroup>

***

## Change a Temperature Threshold

To change the temperature threshold range for a thermostat, issue a new [`/thermostats/set_temperature_threshold`](/api/thermostats/set_temperature_threshold) request. The new threshold values replace the previous ones.

***

## Monitor a Temperature Threshold

To monitor a thermostat for temperatures outside the bounds of the configured threshold range, you can configure a [webhook](../../developer-tools/webhooks) to receive `thermostat.temperature_threshold_exceeded` events. This event includes the `device_id` of the affected thermostat, as well as the configured threshold values and the reported temperature that exceeded this threshold range.

When the reported temperature for a thermostat returns to within the configured threshold range, Seam emits a `thermostat.temperature_threshold_no_longer_exceeded` event.

***

## Delete a Temperature Threshold

To delete the temperature threshold range for a thermostat, issue a `/thermostats/set_temperature_threshold` request, providing either of the following parameter combinations:

* Provide only the `device_id` of the desired thermostat.
* Provide the `device_id` of the desired thermostat and set the following parameters to null:
  * `lower_limit_celsius` or `lower_limit_fahrenheit`
  * `upper_limit_celsius` or `upper_limit_fahrenheit`

<Tabs>
  <Tab title="JavaScript">
    **Request:**

    ```javascript theme={null}
    await seam.thermostats.setTemperatureThreshold({
      device_id: '2d488679-6f07-4810-aed2-e726872c1dd5',
    })
    ```

    or

    ```javascript theme={null}
    await seam.thermostats.setTemperatureThreshold({
      device_id: '2d488679-6f07-4810-aed2-e726872c1dd5',
      lower_limit_celsius: null,
      upper_limit_celsius: null,
    })
    ```

    **Response:**

    ```json theme={null}
    void
    ```
  </Tab>

  <Tab title="cURL">
    **Request:**

    ```bash theme={null}
    curl -X 'POST' \
      'https://connect.getseam.com/thermostats/set_temperature_threshold' \
      -H 'accept: application/json' \
      -H "Authorization: Bearer ${SEAM_API_KEY}" \
      -H 'Content-Type: application/json' \
      -d '{
        "device_id": "2d488679-6f07-4810-aed2-e726872c1dd5"
    }'
    ```

    or

    ```bash theme={null}
    curl -X 'POST' \
      'https://connect.getseam.com/thermostats/set_temperature_threshold' \
      -H 'accept: application/json' \
      -H "Authorization: Bearer ${SEAM_API_KEY}" \
      -H 'Content-Type: application/json' \
      -d '{
        "device_id": "2d488679-6f07-4810-aed2-e726872c1dd5",
        "lower_limit_celsius": null,
        "upper_limit_celsius": null
    }'
    ```

    **Response:**

    ```json theme={null}
    {
      "ok": true
    }
    ```
  </Tab>

  <Tab title="Python">
    **Request:**

    ```python theme={null}
    seam.thermostats.set_temperature_threshold(
      device_id = "2d488679-6f07-4810-aed2-e726872c1dd5"
    )
    ```

    or

    ```python theme={null}
    seam.thermostats.set_temperature_threshold(
      device_id = "2d488679-6f07-4810-aed2-e726872c1dd5",
      lower_limit_celsius = None,
      upper_limit_celsius = None
    )
    ```

    **Response:**

    ```
    None
    ```
  </Tab>

  <Tab title="Ruby">
    **Request:**

    ```ruby theme={null}
    # Coming soon!
    ```

    **Response:**

    ```
    # Coming soon!
    ```
  </Tab>

  <Tab title="PHP">
    **Request:**

    ```php theme={null}
    $seam->thermostats->set_temperature_threshold(
      device_id: "2d488679-6f07-4810-aed2-e726872c1dd5"
    );
    ```

    or

    ```php theme={null}
    $seam->thermostats->set_temperature_threshold(
      device_id: "2d488679-6f07-4810-aed2-e726872c1dd5",
      lower_limit_celsius: null,
      upper_limit_celsius: null
    );
    ```

    **Response:**

    ```json theme={null}
    void
    ```
  </Tab>

  <Tab title="C#">
    **Request:**

    ```java theme={null}
    // Coming soon!
    ```

    **Response:**

    ```json theme={null}
    // Coming soon!
    ```
  </Tab>
</Tabs>


# Testing Your Thermostat App with Simulate Endpoints
Source: https://docs.seam.co/capability-guides/thermostats/testing-your-thermostat-app-with-simulate-endpoints

Learn how to use the Seam suite of simulate endpoints to test your thermostat app.

Seam's suite of `simulate` endpoints help you to test your thermostat app against events that can be difficult to orchestrate in your quality assurance (QA) environment using real devices. Seam provides the following thermostat-related `simulate` endpoints that you can use in a [sandbox workspace](/core-concepts/workspaces/index#sandbox-workspaces):

* [`/thermostats/simulate/hvac_mode_adjusted`](#simulate-adjusting-the-hvac-mode)
* [`/thermostats/simulate/temperature_reached`](#simulate-reaching-a-desired-temperature)

Seam supports these endpoints for all thermostat [sandbox devices](/device-and-system-integration-guides).

<Info>
  Seam provides additional `simulate` endpoints to help you [test your app
  against device disconnection and
  removal](../../core-concepts/devices/testing-your-app-against-device-disconnection-and-removal).
</Info>

***

## Checking Capability Flags

Before using the `simulate` endpoints, check the relevant capabilities of the sandbox thermostat that you want to test. For example, if you want to use `/thermostats/simulate/hvac_mode_adjusted` to simulate having set the [HVAC mode](./understanding-thermostat-concepts/hvac-mode) on a thermostat to `heat`, you must first make sure that the thermostat supports heat mode.

The following device properties show the relevant capabilities of a thermostat:

* `device.can_hvac_heat`
* `device.can_hvac_cool`
* `device.can_hvac_heat_cool`
* `device.can_turn_off_hvac`

For more information, see [Thermostat Capabilities](/capability-guides/thermostats/index#thermostat-capabilities).

***

## Simulate Adjusting the HVAC Mode

The `/thermostats/simulate/hvac_mode_adjusted` endpoint enables you to simulate having adjusted the [HVAC mode](./understanding-thermostat-concepts/hvac-mode) for a thermostat. This simulation is helpful for testing that your app is receiving [thermostat events](/api/thermostats/events) correctly, such as `thermostat.manually_adjusted`.

You can simulate having set the HVAC mode to any of the following settings:

* `heat`
* `cool`
* `heat_cool`
* `off`

When you set the HVAC mode to `heat`, `cool`, or `heat_cool`, you must also set the following applicable [set points](./understanding-thermostat-concepts/set-points) to the desired degrees Fahrenheit or Celsius:

| HVAC Mode Setting | Required Set Points                                                                                                                                                                                           |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `heat`            | <ul><li><code>heating\_set\_point\_fahrenheit</code> or <code>heating\_set\_point\_celsius</code></li></ul>                                                                                                   |
| `cool`            | <ul><li><code>cooling\_set\_point\_fahrenheit</code> or <code>cooling\_set\_point\_celsius</code></li></ul>                                                                                                   |
| `heat_cool`       | <ul><li><code>heating\_set\_point\_fahrenheit</code> or <code>heating\_set\_point\_celsius</code></li><li><code>cooling\_set\_point\_fahrenheit</code> or <code>cooling\_set\_point\_celsius</code></li></ul> |
| `off`             | <ul><li>None</li></ul>                                                                                                                                                                                        |

To simulate having adjusted the HVAC mode for a thermostat:

**Code:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  // Get the device.
  const thermostat = await seam.devices.get({
    device_id: '11111111-1111-1111-2222-444444444444',
  })

  // Confirm that Seam supports the desired HVAC mode for the thermostat.
  // In this example, we're simulating having set the thermostat to heat mode.
  if (thermostat.can_hvac_heat) {
    // Perform the simulated HVAC mode adjustment.
    await seam.thermostats.simulate.hvacModeAdjusted({
      device_id: thermostat.device_id,
      hvac_mode: 'heat',
      heating_set_point_fahrenheit: 68,
    })
  }
  ```

  ```bash cURL theme={null}
  # Get the device.
  thermostat=$(
    # Use GET or POST.
    curl -X 'GET' \
      'https://connect.getseam.com/devices/get' \
      -H 'accept: application/json' \
      -H "Authorization: Bearer ${SEAM_API_KEY}" \
      -H 'Content-Type: application/json' \
      -d '{
        "device_id": "11111111-1111-1111-2222-444444444444"
    }')

  # Confirm that Seam supports the desired HVAC mode for the thermostat.
  # In this example, we're simulating having set the thermostat to heat mode.
  if  $(jq -r '.device.can_hvac_heat' <<< ${thermostat}); then \
    # Perform the simulated HVAC mode adjustment.
    curl -X 'POST' \
      'https://connect.getseam.com/thermostats/simulate/hvac_mode_adjusted' \
      -H 'accept: application/json' \
      -H "Authorization: Bearer ${SEAM_API_KEY}" \
      -H 'Content-Type: application/json' \
      -d "{
        \"device_id\": \"$(jq -r '.device.device_id' <<< ${thermostat})\",
        \"hvac_mode\": \"heat\",
        \"heating_set_point_fahrenheit\": 68
    }";
  fi
  ```

  ```python Python theme={null}
  # Get the device.
  thermostat = seam.devices.get(
    device_id="11111111-1111-1111-2222-444444444444"
  )

  # Confirm that Seam supports the desired HVAC mode for the thermostat.
  # In this example, we're simulating having set the thermostat to heat mode.
  if thermostat.can_hvac_heat:
    # Perform the simulated HVAC mode adjustment.
    seam.thermostats.simulate.hvac_mode_adjusted(
      device_id = thermostat.device_id,
      hvac_mode = "heat",
      heating_set_point_fahrenheit = 68
    )
  ```

  ```ruby Ruby theme={null}
  # Get the device.
  thermostat = client.devices.get(device_id: "11111111-1111-1111-2222-444444444444")

  # Confirm that Seam supports the desired HVAC mode for the thermostat.
  # In this example, we're simulating having set the thermostat to heat mode.
  if (thermostat.can_hvac_heat)
    # Perform the simulated HVAC mode adjustment.
    client.thermostats.simulate.hvac_mode_adjusted(
      device_id: thermostat.device_id,
      hvac_mode: "heat",
      heating_set_point_fahrenheit: 68
    )
  end
  ```

  ```php PHP theme={null}
  // Get the device.
  $thermostat = $seam->devices->get(device_id: "11111111-1111-1111-2222-444444444444");

  // Confirm that Seam supports the desired HVAC mode for the thermostat.
  // In this example, we're simulating having set the thermostat to heat mode.
  if ($thermostat->can_hvac_heat) {
    // Perform the simulated HVAC mode adjustment.
    $seam->thermostats->simulate->hvac_mode_adjusted(
      device_id: $thermostat->device_id,
      hvac_mode: "heat",
      heating_set_point_fahrenheit: 68
    );
  }
  ```

  ```csharp C# theme={null}
  // Get the device.
  Device thermostat = seam.Devices.Get(deviceId: "11111111-1111-1111-2222-444444444444");

  // Confirm that Seam supports the desired HVAC mode for the thermostat.
  // In this example, we're simulating having set the thermostat to heat mode.
  if (thermostat.CanHvacHeat == true) {
    // Perform the simulated HVAC mode adjustment.
    seam.Thermostats.Simulate.HvacModeAdjusted(
      deviceId: thermostat.DeviceId,
      hvacMode: "heat",
      heatingSetPointFahrenheit: 68
    );
  }
  ```
</CodeGroup>

**Output:**

<CodeGroup>
  ```json JavaScript theme={null}
  void
  ```

  ```json cURL theme={null}
  {
    "ok": true
  }
  ```

  ```json Python theme={null}
  None
  ```

  ```json Ruby theme={null}
  nil
  ```

  ```json PHP theme={null}
  void
  ```

  ```json C# theme={null}
  void
  ```
</CodeGroup>

***

## Simulate Reaching a Desired Temperature

The `/thermostats/simulate/temperature_reached` endpoint enables you to simulate the thermostat reaching a specified temperature. This simulation is helpful for testing that your app is receiving [thermostat events](/api/thermostats/events) correctly, such as `thermostat.temperature_changed` and `thermostat.temperature_reached_set_point`.

Specify the desired temperature that you want to simulate the thermostat reaching using either of the following parameters:

* `temperature_celsius`
* `temperature_fahrenheit`

To simulate reaching a desired temperature:

**Code:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  // Get the device.
  const thermostat = await seam.devices.get({
    device_id: '11111111-1111-1111-2222-444444444444',
  })

  // Simulate reaching the specified temperature.
  await seam.thermostats.simulate.temperatureReached({
    device_id: thermostat.device_id,
    temperature_celsius: 25,
  })
  ```

  ```bash cURL theme={null}
  # Get the device.
  thermostat=$(
    # Use GET or POST.
    curl -X 'GET' \
      'https://connect.getseam.com/devices/get' \
      -H 'accept: application/json' \
      -H "Authorization: Bearer ${SEAM_API_KEY}" \
      -H 'Content-Type: application/json' \
      -d '{
        "device_id": "11111111-1111-1111-2222-444444444444"
    }')

  # Simulate reaching the specified temperature.
  curl -X 'POST' \
    'https://connect.getseam.com/thermostats/simulate/temperature_reached' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d "{
      \"device_id\": \"$(jq -r '.device.device_id' <<< ${thermostat})\",
      \"temperature_celsius\": 25
  }"
  ```

  ```python Python theme={null}
  # Get the device.
  thermostat = seam.devices.get(
    device_id="11111111-1111-1111-2222-444444444444"
  )

  # Simulate reaching the specified temperature.
  seam.thermostats.simulate.temperature_reached(
    device_id = thermostat.device_id,
    temperature_celsius = 25
  )
  ```

  ```ruby Ruby theme={null}
  # Get the device.
  thermostat = client.devices.get(device_id: "11111111-1111-1111-2222-444444444444")

  # Simulate reaching the specified temperature.
  client.thermostats.simulate.temperature_reached(
    device_id: thermostat.device_id,
    temperature_celsius: 25
  )
  ```

  ```php PHP theme={null}
  // Get the device.
  $thermostat = $seam->devices->get(device_id: "11111111-1111-1111-2222-444444444444");

  // Simulate reaching the specified temperature.
  $seam->thermostats->simulate->temperature_reached(
    device_id: $thermostat->device_id,
    temperature_celsius: 25
  );
  ```

  ```csharp C# theme={null}
  // Get the device.
  Device thermostat = seam.Devices.Get(deviceId: "11111111-1111-1111-2222-444444444444");

  // Simulate reaching the specified temperature.
  seam.Thermostats.Simulate.TemperatureReached(
    deviceId: thermostat.DeviceId,
    temperatureCelsius: 25
  );
  ```
</CodeGroup>

**Output:**

<CodeGroup>
  ```json JavaScript theme={null}
  void
  ```

  ```json cURL theme={null}
  {
    "ok": true
  }
  ```

  ```json Python theme={null}
  None
  ```

  ```json Ruby theme={null}
  nil
  ```

  ```json PHP theme={null}
  void
  ```

  ```json C# theme={null}
  void
  ```
</CodeGroup>


# HVAC Mode
Source: https://docs.seam.co/capability-guides/thermostats/understanding-thermostat-concepts/hvac-mode

Learn about the HVAC mode setting that you can configure for thermostats.

HVAC mode (`hvac_mode_setting`) governs the operation of your heating, ventilation, and air conditioning (HVAC) system to achieve and maintain your preferred temperature. These HVAC mode options include the following:

* **Heat (`heat`):** In this mode, the thermostat activates only the heating system when the room temperature drops below the heating set point temperature.
* **Cool (`cool`):** In this mode, the thermostat activates only the cooling system when the room temperature rises above the cooling set point temperature.
* **Heat-Cool** or **Auto (`heat_cool`):** In this dual mode, the thermostat automatically switches between heating and cooling to maintain a temperature between the heating and cooling set point temperatures for maximum comfort.
* **Off (`off`):** In this mode, the thermostat is off, which turns off both the heating and cooling systems for the space.
* **Eco (`eco`):** This setting represents Google Nest's eco mode.

***

## HVAC Mode Constraints

Some models of thermostats have specific requirements and constraints related to setting the HVAC mode. You can retrieve these requirements by issuing a [Get Device](/api/devices/get) or [List Devices](/api/devices/list) request.

The following example shows a set of thermostat HVAC mode requirements:

```json theme={null}
{
  "thermostat": {
    "device_id": "518f692b-f865-4590-8c3e-3849e9984c75",
    "device_type": "ecobee_thermostat",
    "capabilities_supported": [
      "thermostat"
    ],
    "properties": {
      "available_hvac_mode_settings": [
        "off",
        "cool",
        "heat",
        "heat_cool"
      ],
    },
    ...
  },
  ...
}
```

***

## Available HVAC Mode Settings

The `available_hvac_mode_settings` property includes an array of available HVAC modes. For example, if the array contains `["heat", "off"]`, it means that you can only set the thermostat to either `heat` mode or `off` mode. The availability of heating or cooling options depends on the connected systems. If the thermostat is not connected to a specific system, the corresponding options may be absent.

The following example shows a thermostat that supports both heating and cooling:

```json theme={null}
"available_hvac_mode_settings": [
  "off",
  "cool",
  "heat",
  "heat_cool"
 ]
```

***


# Understanding Thermostat Concepts
Source: https://docs.seam.co/capability-guides/thermostats/understanding-thermostat-concepts/index

Learn about HVAC mode and set points.

To manage your thermostats effectively with Seam, it is important to understand the following concepts:

* [HVAC mode](/capability-guides/thermostats/understanding-thermostat-concepts/hvac-mode)

  The `hvac_mode_setting` governs the operation of your heating, ventilation, and air conditioning (HVAC) system to achieve and maintain your preferred temperature.

* [Set points](/capability-guides/thermostats/understanding-thermostat-concepts/set-points)

  Temperature set points for a thermostat control the target temperatures that the thermostat activates the heating or cooling system to reach.


# Set Points
Source: https://docs.seam.co/capability-guides/thermostats/understanding-thermostat-concepts/set-points

Learn about heating and cooling set point temperatures that you can configure for thermostats.

Temperature set points for a thermostat control the target temperatures that the thermostat activates the heating or cooling system to reach. That is, these set points define the precise temperatures that the thermostat strives to maintain in the space for heating, cooling, or automatic heat-cool operation. Choosing appropriate set points for a space is important for energy efficiency and comfort.

You can configure heating and cooling set point temperatures in Fahrenheit or Celsius.

***

## Heating Set Point

For heating, the heating set point (`heating_set_point_fahrenheit` or `heating_set_point_celsius`) is the target temperature that the thermostat turns on the furnace or heating system to reach. Once the space reaches the configured temperature, the thermostat turns off the heating system, until the temperature of the space drops below the set point again.

<img alt="The heating set point is the target temperature that the thermostat turns on the furnace or heating system to reach." />

***

## Cooling Set Point

For cooling, the cooling set point (`cooling_set_point_fahrenheit` or `cooling_set_point_celsius`) is the target temperature that the thermostat turns on the air conditioner or cooling system to reach. Once that space reaches the configured temperature, the thermostat turns off the cooling system, until the temperature of the space rises above the set point again.

<img alt="The cooling set point is the target temperature that the thermostat turns on the air conditioner or cooling system to reach." />

***

## Heat-Cool Set Points

In heat-cool mode, the thermostat uses the heating set point (`heating_set_point_fahrenheit` or `heating_set_point_celsius`) as the target temperature for turning on the heating system and the cooling set point (`cooling_set_point_fahrenheit` or `cooling_set_point_celsius`) as the target temperature for turning on the cooling system. The thermostat activates heating or cooling as needed to keep the temperature of the space between these two configured set points for maximum comfort.

Note that there may be a required minimum temperature difference between the cooling and heating set points. For more information, see [Minimum Heating Cooling Temperature Delta](#minimum-heating-cooling-temperature-delta).

<img alt="In heat-cool mode, the thermostat uses the heating and cooling set points as the target temperatures for turning on the heating and cooling systems, respectively." />

***

## Set Point Constraints

Some models of thermostats have specific requirements and constraints related to configuring set points. You can fetch the requirements by issuing a [Get Device](/api/devices/get) or [List Thermostats](/api/thermostats/list) request.&#x20;

The following example shows a set of thermostat set point requirements:

```json theme={null}
{
  "thermostat": {
    "device_id": "518f692b-f865-4590-8c3e-3849e9984c75",
    "device_type": "ecobee_thermostat",
    "capabilities_supported": [
      "thermostat"
    ],
    "properties": {
      ...
      "max_cooling_set_point_celsius": 33.333333333333336,
      "max_heating_set_point_celsius": 26.11111111111111,
      "min_cooling_set_point_celsius": 18.333333333333336,
      "min_heating_set_point_celsius": 7.222222222222222,
      "min_heating_cooling_delta_celsius": 2.7777777777777777,
      "min_heating_set_point_fahrenheit": 45,
      "max_heating_set_point_fahrenheit": 79,
      "min_cooling_set_point_fahrenheit": 65,
      "max_cooling_set_point_fahrenheit": 92,
      "min_heating_cooling_delta_fahrenheit": 5,
      ...
    },
    ...
  },
  ...
}
```

***

### Set Point Temperature Range

The thermostat settings have restrictions on the range of set point temperatures that users can choose for both cooling and heating. For cooling, the `min_cooling_set_point_*` and `max_cooling_set_point_*` properties indicate the permissible temperature range. For heating, the `min_heating_set_point_*` and `max_heating_set_point_*` properties indicate the permissible temperature range. These properties are available in both Celsius and Fahrenheit, as the suffix indicates. See these parameters to ensure that your selected set points fall within the defined operational limits of the thermostat.

The following example shows the set point temperature range, including both heating and cooling:

```json theme={null}
"max_cooling_set_point_celsius": 33.333333333333336,
"min_cooling_set_point_celsius": 18.333333333333336,
"max_heating_set_point_celsius": 26.11111111111111,
"min_heating_set_point_celsius": 7.222222222222222,
"min_cooling_set_point_fahrenheit": 65,
"max_cooling_set_point_fahrenheit": 92,
"min_heating_set_point_fahrenheit": 45,
"max_heating_set_point_fahrenheit": 79
```

***

### Minimum Heating Cooling Temperature Delta

The `min_heating_cooling_delta_celsius` and `min_heating_cooling_delta_fahrenheit` properties denote the minimum temperature difference—that is, delta—in degrees between the cooling and heating set points when in heat-cool (auto) mode. You must configure the cooling set point to be higher than the heating set point by at least the specified delta. This setting helps to prevent the thermostat from rapidly switching between heating and cooling modes, thereby avoiding [short cycling](https://www.thespruce.com/what-it-means-when-furnace-is-short-cycling-5208093).

The following example shows a configured minimum delta between the cooling and heating set points:

```json theme={null}
"min_heating_cooling_delta_celsius": 2.7777777777777777,
"min_heating_cooling_delta_fahrenheit": 5
```


# Action Attempts
Source: https://docs.seam.co/core-concepts/action-attempts

Learn about action attempts and how they help you to track the progress of asynchronous actions in the physical world.

You can perform actions against a device. However, devices exist in the physical world. The physical world is intrinsically asynchronous.

This means that certain actions can take seconds, minutes, or even days to complete. Furthermore, an action can fail, and you may also not find out until later.

This situation is challenging because the world of APIs is generally synchronous (request-response). APIs must answer instantly, but an instant response would imply instant completion of a long-lived physical process. Clearly, in this case, an instant response is not possible.

To solve this issue, we created action attempts.

When you request for a device to perform an action, the Seam API immediately returns an action attempt object. In the background, the Seam API performs the action.

This action attempt enables you to keep track of the progress of your action.

Our client libraries do this automatically for you. However, you can also choose not to wait and to check on the action at a later time.

For more information, see [Action Attempts](/api/action_attempts/object) in the Seam API reference.


# API Keys
Source: https://docs.seam.co/core-concepts/authentication/api-keys

Create an API key for authorization that enables you to control devices connected to a specific Seam workspace.

You [create an API key](#create-an-api-key) in your [sandbox workspace](/core-concepts/workspaces/index#sandbox-workspaces) or [production workspace](/core-concepts/workspaces/index#production-workspaces) to authorize your use of the Seam API. When using the Seam HTTP API or any of the Seam SDKs, you must provide this API key to issue commands that enable you to control the devices in the associated workspace. It is useful to [export your API key](#export-an-api-key) as an environment variable. You can also [test your API key](#test-an-api-key).

<Warning>
  Never use an API key in a web browser or expose it to your users.
</Warning>

## Create an API Key

Each API key is associated with a specific workspace. For example, if you have a sandbox workspace and a production workspace, you must create and use a different API key for each of these two workspaces.

<Info>
  If you need to access multiple workspaces, create a [Personal Access
  Token](/core-concepts/authentication/personal-access-tokens) to use instead of a workspace-specific API
  key.
</Info>

1. In the upper-left corner of [Seam Console](https://console.seam.co/), click the workspace switcher.<img alt="Use the Seam Console workspace switcher to switch between workspaces and create new workspaces." />
2. Click **New Workspace**.
3. Click the workspace for which you want to create an API key.
4. In the left navigation pane, click **API Keys**.
5. In the upper-right corner of the **API Keys** page, click **Add API Key**.
6. In the **Add API Key** dialog, type a name for your new API key and then click **Create API Key**.
7. Copy the newly-created API key and store it for future use.

<Info>
  Production API keys do not include `test`, while API keys for sandbox
  workspaces do include `test`. In addition, if you accidentally commit your API
  key to a GitHub repo, the `seam_` prefix is detected, and you are notified.
</Info>

## Export an API Key

Once you have created an API key, it is useful to export this key as an environment variable. Then, all installed Seam SDKs automatically use this exported API key.

Open a terminal window and enter the following command to export your API key:

```sh theme={null}
$ export SEAM_API_KEY=seam_test2bMS_94SrGUXuNR2JmJkjtvBQDg5c
```

## Test an API Key

Test an API key by [exporting the key](#export-an-api-key) as an environment variable and then running the code in this section. If the API key is valid, the response displays the corresponding workspace information.

First, export the API key, as follows:

```sh theme={null}
$ export SEAM_API_KEY=seam_test2bMS_94SrGUXuNR2JmJkjtvBQDg5c
```

Then, run the following code to test the API key:

**Code:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  import { Seam } from 'seam'

  const seam = new Seam() // Seam automatically uses your exported SEAM_API_KEY.

  const checkAuth = async () => {
    const workspace = await seam.workspaces.get()
    console.log(workspace)
  }

  checkAuth()
  ```

  ```bash cURL theme={null}
  curl -X 'POST' \
    'https://connect.getseam.com/workspaces/get' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d '{}'
  ```

  ```python Python theme={null}
  from seam import Seam

  seam = Seam()  # Seam automatically uses your exported SEAM_API_KEY.

  workspace = seam.workspaces.get()
  pprint(workspace)
  ```

  ```ruby Ruby theme={null}
  require "seam"

  seam = Seam.new() # Seam automatically uses your exported SEAM_API_KEY.

  workspace = seam.workspaces.get()

  puts workspace.inspect
  ```

  ```php PHP theme={null}
  <?php
  require 'vendor/autoload.php';

  $seam = new Seam\SeamClient(); // Seam automatically uses your exported SEAM_API_KEY.

  $workspace = $seam->workspaces->get();

  echo json_encode($workspace, JSON_PRETTY_PRINT);
  ```

  ```csharp C# theme={null}
  using Seam.Client;

  var seam = new SeamClient(apiToken: SEAM_API_KEY);

  var workspace = seam.Workspaces.Get();

  Console.WriteLine(workspace);
  ```
</CodeGroup>

**Output:**

<CodeGroup>
  ```json JavaScript theme={null}
  {
    workspace_id: '00000000-0000-0000-0000-000000000000',
    name: 'Sandbox',
    company_name: 'Acme',
    connect_partner_name: 'Acme',
    is_sandbox": true
  }
  ```

  ```json cURL theme={null}
  {
    "workspace": {
      "workspace_id": "00000000-0000-0000-0000-000000000000",
      "name": "Sandbox",
      "company_name": "Acme",
      "connect_partner_name": "Acme",
      "is_sandbox": true
    },
    "ok": true
  }
  ```

  ```json Python theme={null}
  Workspace(
    workspace_id='00000000-0000-0000-0000-000000000000',
    name='Sandbox',
    company_name='Acme',
    connect_partner_name='Acme',
    is_sandbox=True
  )
  ```

  ```json Ruby theme={null}
  <
    Seam::Workspace:0x0070328
      workspace_id="00000000-0000-0000-0000-000000000000"
      name="Sandbox"
      company_name="Acme"
      connect_partner_name="Acme"
      is_sandbox=true
  >
  ```

  ```json PHP theme={null}
  {
    "workspace_id": "00000000-0000-0000-0000-000000000000",
    "name": "Sandbox",
    "company_name": "Acme",
    "connect_partner_name": "Acme",
    "is_sandbox": true
  }
  ```

  ```json C# theme={null}
  {
    "workspace_id": "00000000-0000-0000-0000-000000000000",
    "name": "Sandbox",
    "company_name": "Acme",
    "connect_partner_name": "Acme",
    "is_sandbox": true
  }
  ```
</CodeGroup>


# Implementing Client Sessions for Device Management in the Backend
Source: https://docs.seam.co/core-concepts/authentication/client-session-tokens/implementing-client-sessions-for-device-management-in-the-backend

Learn how to use client sessions to control your users' access to devices.

If you are developing an application with multiple customers connecting their devices, [client sessions](./) are a practical way to manage device access for each user. This topic provides an example of implementing client sessions in the backend, ensuring that users can access only the devices that they own.

***

## Connect Your Users' Accounts Using a Client Session

When connecting your customers' devices, you can create a client session for each customer and associate this session with any Connect Webviews that you issue to them.

<CodeGroup>
  ```javascript JavaScript theme={null}
  // Pass your API key to the Seam constructor to authorize access 
  // to your Seam workspace.
  // Set your API key. Remember to switch to your live API key 
  // in production.
  const seam = new Seam("YOUR_API_KEY")

  // Get or create a client session using your own internal user
  // ID as the user_identifier_key.
  const user_identifier_key = "xxxx"
  const client_session = await seam.clientSessions.get_or_create({
  user_identifier_key
  })

  // Create a Connect Webview and link the Connect Webview to the
  // client session, using the user_identifier_key to identify the
  // desired client session.
  const connect_webview = await seam.connectWebviews.create()
  await seam.clientSessions.grant_access({
  user_identifier_key,
  connect_webview_ids: [connect_webview.connect_webview_id],
  })

  // Share the URL of the Connect Webview with the user to enable
  // them connect their devices.
  const connect_webview_url = connect_webview.url

  ```
</CodeGroup>

***

## Filter for a User's Devices with the User Identifier Key

You can use the `user_identifier_key` to retrieve a list of devices that only includes the ones that a specific user owns.

<CodeGroup>
  ```javascript JavaScript theme={null}
  const user_identifier_key = "xxxx"

  const devices = await seam.devices.list({
    user_identifier_key
  })
  ```
</CodeGroup>

***

## Authorize Requests Using the User Identifier Key

You can also use the `user_identifier_key` to ensure that a user has the authorization to interact with a device.

<CodeGroup>
  ```javascript Node theme={null}
  const handleUnlock = async (req, res) => {
    // Retrieve the internal user ID used to set the 
    // user_identifier_key.
    const user_identifier_key = req.auth.userId
    
    // The application user specifies a device to unlock from 
    // among the filtered set of devices.
    const device_id = req.body.device_id
    
    // Confirm that the selected device is, indeed, among the 
    // set of devices that the user owns.
    const devices = await seam.devices.list({
      user_identifier_key,
      device_ids: [device_id],
    }) 
    if (devices.length === 0) return res.send(401).end()
    
    // Trigger an action on the device, like unlocking the door.
    await seam.devices.unlock_door({ device_id })
    
    res.send(204)
  }
  ```
</CodeGroup>


# Client Sessions and Client Session Tokens
Source: https://docs.seam.co/core-concepts/authentication/client-session-tokens/index

Use a client session token to restrict access to the devices that a specific user owns.

A client session enables a client, such as a web browser or mobile phone, to access the Seam API directly. You can use client sessions to simplify your architecture. That is, when you use client sessions and client session tokens with the Seam JavaScript SDK, you can authenticate and authorize users of your web application directly with Seam.

Once you create a client session on the backend, you can pass the resulting generated client session token from the backend to the frontend (that is, to the client). Using client session tokens on the frontend eliminates the need for your user's browser to communicate with your backend server. Instead, the client makes requests directly to the Seam API.

Client sessions make it easy to control your users' access to devices. When you create a client session, you can specify [your own internal user ID for a desired user](/ui-components/overview/getting-started-with-seam-components/get-started-with-client-side-components#3-select-a-user-identifier-key), along with the [connected accounts](/api/connected_accounts/object) associated with this user. Then, you can [use client sessions on the backend to limit your users to only the devices that they own](/core-concepts/authentication/client-session-tokens/implementing-client-sessions-for-device-management-in-the-backend).

<Info>
  If you are just getting started with Seam, see [Seam
  Components](/core-concepts/overview). In only a few minutes and with
  just a few lines of code, you can start controlling devices from your web
  application without interacting with the backend.
</Info>

<img alt="Client sessions and client session tokens increase efficiency by enabling your user's browser to communicate directly with the Seam backend server." />

<Warning>
  You can only use a client session token in a browser context through the Seam
  JavaScript SDK. Do not use a client session token to make requests from the
  backend. Instead, use an [API key](../api-keys). An API key has unlimited
  permission to manage all devices and other Seam API resources within a
  [workspace](/core-concepts/workspaces/index). Never use an API key in the browser or expose
  it to your users.
</Warning>

You can use client sessions in the following two ways:

* Create a client session on the backend and pass the resulting generated client session token to your frontend. You use this client session token in the frontend with the Seam JavaScript SDK or Seam Components.
* Manage client sessions entirely on the frontend by using a [publishable key with the JavaScript SDK or Seam Components](../../../ui-components/overview/getting-started-with-seam-components/get-started-with-client-side-components).

***

## Create a Client Session for an Existing User and Retrieve the Session Token

To [create a client session](/api/client_sessions/create) for an existing user with connected accounts in your workspace, include the IDs of the user's connected accounts (`connected_account_ids`) and [provide your own unique internal user ID (`user_identifier_key`)](/ui-components/overview/getting-started-with-seam-components/get-started-with-client-side-components#3-select-a-user-identifier-key). Then, use the generated client session token to retrieve and manage the resources authorized through the connected accounts associated with this client session.

**Request:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  const client_session = await seam.clientSessions.create({
    user_identifier_key: 'internal-user-id-1',
    connected_account_ids: [
      '3ea0b67f-649f-4131-bfe3-f2035e77a3f9',
      '6e1cad57-b244-40ca-b4f3-30a46c8000d4',
    ],
  })

  console.log(`Client session token: ${client_session.token}`)
  ```
</CodeGroup>

**Response:**

```json theme={null}
Client session token: seam_cst1891oqCmE_6dBwV8PJ2Ffoe9dWYVyMfVHq
```

***

## List Client Sessions

You can [list all client sessions](/api/client_sessions/list) within your workspace.

**Request:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  await seam.clientSessions.list()
  ```
</CodeGroup>

**Response:**

```json theme={null}
[
  {
    workspace_id: '398d80b7-3f96-47c2-b85a-6f8ba21d07be',
    token: 'seam_cst1271Q3JUh_A3ECdSrrqgYp98SmB9qY2NGp',
    user_identifier_key: 'internal user ID 1',
    created_at: '2023-12-26T04:23:46.829Z',
    client_session_id: 'c75d4330-ae01-4dfd-b6c5-f3e94e0d8168',
    user_identity_ids: [],
    connect_webview_ids: [],
    device_count: 4,
    connected_account_ids: [
      '3ea0b67f-649f-4131-bfe3-f2035e77a3f9',
      '6e1cad57-b244-40ca-b4f3-30a46c8000d4'
    ]
  },
  {
    workspace_id: '398d80b7-3f96-47c2-b85a-6f8ba21d07be',
    token: 'seam_cst1891oqCmE_6dBwV8PJ2Ffoe9dWYVyMfVHq',
    user_identifier_key: 'internal user ID 2',
    created_at: '2023-12-26T04:25:50.041Z',
    client_session_id: 'e1006128-19a8-4e4d-9a91-536d80cf9c21',
    user_identity_ids: [],
    connect_webview_ids: [],
    device_count: 4,
    connected_account_ids: [
      '2e884e71-b2c1-41a0-bb2c-ec94a7b4c6a4',
      'b0ccf472-cb63-400c-bf21-5b809f5e1afd'
    ]
  },
  ...
]
```

***

## Get a Client Session

To [get a specific client session](/api/client_sessions/get), provide the client session ID (`client_session_id`).

**Request:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  const clientSession = await seam.clientSessions.get({
    client_session_id: "c75d4330-ae01-4dfd-b6c5-f3e94e0d8168",
  }))
  ```
</CodeGroup>

**Response:**

```json theme={null}
{
  "workspace_id": "398d80b7-3f96-47c2-b85a-6f8ba21d07be",
  "token": "seam_cst1271Q3JUh_A3ECdSrrqgYp98SmB9qY2NGp",
  "user_identifier_key": "internal user ID 1",
  "created_at": "2023-12-26T04:23:46.829Z",
  "client_session_id": "c75d4330-ae01-4dfd-b6c5-f3e94e0d8168",
  "device_count": 4,
  "connected_account_ids": [
    "3ea0b67f-649f-4131-bfe3-f2035e77a3f9",
    "6e1cad57-b244-40ca-b4f3-30a46c8000d4"
  ],
  "connect_webview_ids": [],
  "user_identity_ids": []
}
```

***

## Delete a Client Session

To [delete a client session](/api/client_sessions/delete), provide the client session ID (`client_session_id`).

<CodeGroup>
  ```javascript JavaScript theme={null}
  await seam.clientSessions.delete({
    client_session_id: '639eb8af-19a9-4ae5-817c-6ad08fd078e7',
  })
  ```
</CodeGroup>

***

## Next Steps

* Learn about using [client session tokens with Seam Components](/core-concepts/overview).
* Learn more about [Connect Webviews](/core-concepts/connect-webviews/index).


# Authentication
Source: https://docs.seam.co/core-concepts/authentication/index

Choose the right authentication method for your Seam integration — API keys for server-side, client sessions for frontend apps, or personal access tokens for development.

Seam supports several authentication methods, each designed for a different use case. All methods authenticate against the Seam API at `https://connect.getseam.com`.

<CardGroup>
  <Card title="API Keys" icon="key" href="/core-concepts/authentication/api-keys">
    Server-side authentication for production apps. Create API keys in Seam Console and pass them via the `Authorization` header or SDK constructor.
  </Card>

  <Card title="Personal Access Tokens" icon="user" href="/core-concepts/authentication/personal-access-tokens">
    Authenticate as yourself across all your workspaces. Ideal for development, scripting, and the Seam CLI.
  </Card>

  <Card title="Client Session Tokens" icon="browser" href="/core-concepts/authentication/client-session-tokens">
    Scoped tokens for frontend apps. Grant users access to specific devices without exposing your API key.
  </Card>
</CardGroup>

## Choosing the Right Method

| Method                    | Use case            | Scope                      | Where to use       |
| ------------------------- | ------------------- | -------------------------- | ------------------ |
| **API Key**               | Production backend  | Single workspace           | Server-side only   |
| **Personal Access Token** | Development and CLI | All your workspaces        | Local dev, scripts |
| **Client Session Token**  | Frontend apps       | Scoped to specific devices | Browser, mobile    |

<Info>
  API keys and personal access tokens should never be exposed in client-side code. Use client session tokens for any frontend integration.
</Info>


# Personal Access Tokens
Source: https://docs.seam.co/core-concepts/authentication/personal-access-tokens

Create a Personal Access Token to access multiple Seam workspaces using a single credential.

In some instances, it may be necessary to access multiple workspaces with a single Seam credential. For example, you may want to set up separate workspaces for each of your users to control different sets of devices. For more information about scenarios in which multiple workspaces are useful, see [Per-Customer Workspace Setup](/core-concepts/workspaces/index#per-customer-workspace-setup-less-common).

Because [API keys](/core-concepts/authentication/api-keys) are scoped to a single workspace, Seam provides Personal Access Tokens (PATs) to enable multi-workspace authorization. First, [create a PAT](#create-a-personal-access-token). Then, [use this PAT with a workspace ID](#using-the-pat-to-issue-a-seam-api-request) to access the desired workspace.

<Warning>Never use a PAT in a web browser or expose it to your users.</Warning>

<img alt="Unlike API keys, PATs enable multi-workspace authorization." />

## Create a Personal Access Token

1. In the top navigation pane of [Seam Console](https://console.seam.co/), click **Developer**.
2. In the left navigation pane, **Personal Access Tokens**.
3. In the upper-right corner of the **Personal Access Tokens** page, click **Add Personal Access Token**.
4. In the **Add Personal Access Token** dialog, type a name for your new PAT and then click **Create Personal Access Token**.
5. Copy the newly-created PAT and store it for future use.

## Using the PAT to issue a Seam API request

To use a PAT for authorization in the Seam API, you must specify the PAT in the `Authorization` header for the Seam HTTP API or in the `seam` constructor for the Seam SDK that you are using. You must also specify the ID of the workspace that you want to access. If you are using the Seam HTTP API, include the `seam-workspace` header with the desired workspace ID. If you are using a Seam SDK, specify the desired workspace ID in the `Seam` constructor.

The following example shows how to use a PAT and workspace ID to [list all devices](/api/devices/list) in a workspace:

<CodeGroup>
  ```javascript JavaScript theme={null}
  const seam = new Seam({
    // Specify PAT.
    apiKey: pat,
    // Specify workspace ID.
    workspaceId: workspaceId,
  })

  console.log(await seam.devices.list())
  ```

  ```bash cURL theme={null}
  curl -X 'POST' \
    'https://connect.getseam.com/devices/list' \
    -H 'accept: application/json' \
    -H 'seam-workspace: ${WORKSPACE_ID}' \
    -H 'Authorization: Bearer ${PAT}' \
    -H 'Content-Type: application/json' \
    -d '{}'
  ```

  ```python Python theme={null}
  seam = Seam(
      # Specify PAT.
      api_key=pat,
      # Specify workspace ID.
      workspace_id=workspaceId
  )

  pprint(seam.devices.list())
  ```

  ```ruby Ruby theme={null}
  client = Seam.new(
    # Specify PAT.
    api_key: pat,
    # Specify workspace ID.
    workspace_id: workspace_id
  )

  puts client.devices.list().inspect
  ```

  ```php PHP theme={null}
  $seam = new Seam\SeamClient(
    // Specify PAT.
    $pat,
    // Specify workspace ID.
    $workspace_id
  );

  print_r($seam->devices->list());
  ```

  ```csharp C# theme={null}
  var seam = new SeamClient(
      // Specify PAT.
      apiToken: pat,
      // Specify workspace ID.
      workspaceId: workspaceId
  );

  var devices = seam.Devices.List();
  foreach (var device in devices)
  {
    Console.WriteLine(device);
  }
  ```
</CodeGroup>

<Info>
  Instead of including your PAT in the `Seam` constructor, you can export your PAT as a `SEAM_API_KEY` environment variable. Then, all installed Seam SDKs automatically use this exported PAT.

  ```bash theme={null}
  $ export SEAM_API_KEY=${PAT}
  ```
</Info>


# Attaching Custom Metadata to the Connect Webview
Source: https://docs.seam.co/core-concepts/connect-webviews/attaching-custom-data-to-the-connect-webview

Use custom metadata to link internal IDs from your application to a Seam Connect Webview and connected account.

Adding Custom Metadata to a Connect Webview enables you to store custom information, like customer details or internal IDs from your application. The `custom_metadata` is then transferred to any connected accounts connected through the connect webview, making it easy to find and filter these resources in your Seam workspace.

<Info>
  You can also use unique resource keys as an easy way to link your resources to
  Seam resources. For details, see [Mapping Your Resources to Seam
  Resources](../mapping-your-resources-to-seam-resources).
</Info>

The `custom_metadata` property supports up to 50 JSON key:value pairs. When an account is successfully connected through a Connect Webview, Seam creates a connected account and copies the `custom_metadata` to it.

<Info>
  If the `custom_metadata` property is left blank, Seam stores an empty set (`{}
      `) on both the Connect Webview and connected account resource.
</Info>

To add `custom_metadata` to a Connect Webview:

1. Execute [`/connect_webviews/create`](/api/connect_webviews/create) and specify the internal ID as a key:value pair in the `custom_metadata`.\
   For example:

**Request:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  await seam.connectWebviews.create({
    provider_category: 'stable',
    custom_metadata: {
      your_app_user_id: 'xxxx', // Insert your custom data here.
    },
  })
  ```

  ```bash cURL theme={null}
  curl -X 'POST' \
    'https://connect.getseam.com/connect_webviews/create' \
    -H 'accept: application/json' \
    -H 'Authorization: Bearer ${API_KEY}' \
    -H 'Content-Type: application/json' \
    -d '{
    "provider_category": "stable",
    "custom_metadata": {
      "your_app_user_id": "xxxx"
    }
  }'
  ```

  ```python Python theme={null}
  seam.connect_webviews.create(
    provider_category = "stable",
    custom_metadata = {
      "your_app_user_id": "xxxx" # Insert your custom data here.
    }
  )
  ```

  ```ruby Ruby theme={null}
  client.connect_webviews.create(
    provider_category: "stable",
    custom_metadata: {
      "your_app_user_id": "xxxx" # Insert your custom data here.
    }
  )
  ```

  ```csharp C# theme={null}
  var customMetadata = new Dictionary<string, string>()
  {
    {"id", "internal-user-id"}
  };

  seam.ConnectWebviews.Create(
    providerCategory: Seam.Api.ConnectWebviews.CreateRequest.ProviderCategoryEnum.Stable,
    customMetadata: customMetadata
  );
  ```
</CodeGroup>

**Response:**

<CodeGroup>
  ```json JavaScript theme={null}
  {
    url: 'https://connect.getseam.com/connect_webviews/view?connect_webview_id=3937fa0b-ab09-4a00-9f10-69864750ed07&auth_token=PVHmtzULRFEQDny776KDsegSQ5t2SsZHR',
    status: 'pending',
    workspace_id: '398d80b7-3f96-47c2-b85a-6f8ba21d07be',
    custom_metadata: { id: 'internalId1' },
    ...
  }
  ```

  ```json cURL theme={null}
  {
    "connect_webview": {
      "url": "https://connect.getseam.com/connect_webviews/view?connect_webview_id=3c3f4c15-e7db-47c6-bc5a-1bf206ff269c&auth_token=LrpMC4MVHAY8YJRcNFeX1nQcb7tGNwpot",
      "status": "pending",
      "workspace_id": "398d80b7-3f96-47c2-b85a-6f8ba21d07be",
      "custom_metadata": {
        "id": "internal_id_1"
      },
      ...
    },
    "ok": true
  }
  ```

  ```json Python theme={null}
  ConnectWebview(
    workspace_id='398d80b7-3f96-47c2-b85a-6f8ba21d07be',
    connect_webview_id='49e050d9-cb4c-4600-b24d-cdf9dd2f92b7',
    status='pending',
    url='https://connect.getseam.com/connect_webviews/view?connect_webview_id=49e050d9-cb4c-4600-b24d-cdf9dd2f92b7&auth_token=C1r8ff3GLSr2L1ifEaCopAgrq2Faht2Dh',
    custom_metadata={'id': 'internal_id_1'},
    ...
  )
  ```

  ```json Ruby theme={null}
  <Seam::ConnectWebview:0x00438
    url="https://connect.getseam.com/connect_webviews/view?connect_webview_id=7fe89a3e-a1d7-44dd-b53f-35f8f5f92607&auth_token=3jJWKRBcJvZeGcrA8UnC1y2RieyHDPSwV"
    status="pending"
    workspace_id="398d80b7-3f96-47c2-b85a-6f8ba21d07be"
    custom_metadata={"id"=>"internal_id_1"}
    ...
  >
  ```

  ```json C# theme={null}
  {
    "connect_webview_id": "3874d8b4-4bb5-470a-9fc7-a54931a4b933",
    "url": "https://connect.getseam.com/connect_webviews/view?connect_webview_id=3874d8b4-4bb5-470a-9fc7-a54931a4b933&auth_token=F9t4SkQ6R8mZjJEBV5K4dwoVdkR6VtjdJ",
    "workspace_id": "398d80b7-3f96-47c2-b85a-6f8ba21d07be",
    "custom_metadata": {
      "id": "user1"
    },
    ...
  }
  ```
</CodeGroup>

2. Your app presents the Connect Webview to your user.
3. The user completes the Connect Webview.
4. Seam creates a connected account containing the user's device account information.\
   This connected account includes a `custom_metadata` property that automatically contains the information that you set in the `custom_metadata` property for the Connect Webview.
5. To retrieve the ID of the connected account associated with the completed Connect Webview, [get the `connect_webview`](/api/connect_webviews/get) and check the `connected_account_id` property.
6. To retrieve the connected account, [get the `connected_account`](/api/connected_accounts/get) with the ID that you identified in the previous step.
7. Within the returned `connected_account`, view the `custom_metadata`.

<Info>
  If a Connect Webview was used to connect an existing connected account (for
  example, to reconnect a disconnected account), Seam will replace any existing
  `custom metadata` in the `connected_account` object with the new payload.
</Info>

## Next Steps

Once you have attached custom metadata to Connect Webviews, you can [filter your Connect Webviews](/core-concepts/connect-webviews/filtering-connect-webviews-by-custom-metadata) by this custom metadata.


# Connect Webview Process
Source: https://docs.seam.co/core-concepts/connect-webviews/connect-webview-process

Learn how to create, display, and complete Connect Webviews to connect devices and systems to Seam.

This topic describes the basic Connect Webview process. First, you create the Connect Webview and display it for your user from within your app. Your user completes the Connect Webview flow to authorize the device or system account connection to Seam. Then, you can verify the successful account connection, retrieve the newly-connected devices or systems, and start controlling these devices or systems with Seam.

***

## Step 1: Create a Connect Webview

The Connect Webview flow begins when your user wants to connect their device or ACS account to Seam through your app.

In your app, [create a Connect Webview](/api/connect_webviews/create). The Seam API represents Connect Webviews as `connect_webview` objects.

By default, a Connect Webview displays all of the stable providers that Seam supports, which lets your user pick whatever brand they actually own. This is the recommended approach: it means every provider Seam adds becomes available to your users automatically, with no code change on your side.

If you need to narrow what the Connect Webview displays, specify a `provider_category`. Supported provider categories include the following:

* `stable`
* `beta`
* `consumer_smartlocks`
* `thermostats`
* `noise_sensors`
* `access_control_systems`

To list all providers within a category, use the [List Device Providers](/api/devices/list_device_providers) method with the desired `provider_category` filter. For more information, see [Customize the Brands to Display in Your Connect Webviews](/core-concepts/connect-webviews/customizing-connect-webviews#customize-the-brands-to-display-in-your-connect-webviews).

**Code:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  const createdConnectWebview = await seam.connectWebviews.create({
    custom_redirect_url: 'https://example.com/redirect',
    custom_redirect_failure_url: 'https://example.com/failure-redirect',
    provider_category: 'stable',
    wait_for_device_creation: true,
  })
  ```

  ```bash cURL theme={null}
  curl -X 'POST' \
    'https://connect.getseam.com/connect_webviews/create' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d '{
    "custom_redirect_url": "https://example.com/redirect",
    "custom_redirect_failure_url": "https://example.com/failure-redirect",
    "provider_category": "stable",
    "wait_for_device_creation": true
  }'
  ```

  ```python Python theme={null}
  created_connect_webview = seam.connect_webviews.create(
    custom_redirect_url = "https://example.com/redirect",
    custom_redirect_failure_url = "https://example.com/failure-redirect",
    provider_category = "stable",
    wait_for_device_creation = True
  )
  ```

  ```ruby Ruby theme={null}
  created_connect_webview = client.connect_webviews.create(
    custom_redirect_url: "https://example.com/redirect",
    custom_redirect_failure_url: "https://example.com/failure-redirect",
    provider_category: "stable",
    wait_for_device_creation: true
  )
  ```

  ```php PHP theme={null}
  $created_connect_webview = $seam->connect_webviews->create(
    custom_redirect_url: "https://example.com/redirect",
    custom_redirect_failure_url: "https://example.com/failure-redirect",
    provider_category: "stable",
    wait_for_device_creation: true
  );
  ```

  ```csharp C# theme={null}
  var createdConnectWebview = seam.ConnectWebviews.Create(
    customRedirectUrl: "https://example.com/redirect",
    customRedirectFailureUrl: "https://example.com/failure-redirect",
    providerCategory: Seam.Api.ConnectWebviews.CreateRequest.ProviderCategoryEnum.Stable,
    waitForDeviceCreation: true
  );
  ```
</CodeGroup>

**Output:**

<CodeGroup>
  ```json JavaScript theme={null}
  {
    connect_webview_id: '12345678-1234-1234-1234-123456789012',
    url: 'https://connect.getseam.com/connect_webviews/view?connect_webview_id=12345678-1234-1234-1234-123456789012&auth_token=2r2Rn8V5QUtxE79gNhTmTK58KkuqrwU8d',
    status: 'pending',
    login_successful: false,
    custom_redirect_url: 'https://example.com/redirect',
    custom_redirect_failure_url: 'https://example.com/failure-redirect',
      ...
    ],
    wait_for_device_creation: true,
    ...
  }
  ```

  ```json cURL theme={null}
  {
    "connect_webview": {
      "connect_webview_id": "12345678-1234-1234-1234-123456789012",
      "url": "https://connect.getseam.com/connect_webviews/view?connect_webview_id=12345678-1234-1234-1234-123456789012&auth_token=CvPDERYGGMvqgo6N1gsT7XRBieBtPqtUG",
      "status": "pending",
      "login_successful": false,
      "custom_redirect_url": "https://example.com/redirect",
      "custom_redirect_failure_url": "https://example.com/failure-redirect",
        ...
      ],
      "wait_for_device_creation": true,
      ...
    },
    "ok": true
  }
  ```

  ```json Python theme={null}
  ConnectWebview(
    connect_webview_id='12345678-1234-1234-1234-123456789012',
    url='https://connect.getseam.com/connect_webviews/view?connect_webview_id=12345678-1234-1234-1234-123456789012&auth_token=z7Wu2Lc85gYUbNUhdvCWaEhmQv61FziA',
    status='pending',
    login_successful=False,
    custom_redirect_url='https://example.com/redirect',
    custom_redirect_failure_url='https://example.com/failure-redirect',
      ...
    ],
    wait_for_device_creation=True,
    ...
  )
  ```

  ```json Ruby theme={null}
  <
    Seam::ConnectWebview:0x00438
      connect_webview_id="12345678-1234-1234-1234-123456789012"
      url="https://connect.getseam.com/connect_webviews/view?connect_webview_id=12345678-1234-1234-1234-123456789012&auth_token=6zrib4wrGZMDxvJxPQQFiB6snmx7UAU6E"
      status="pending"
      login_successful=false
      custom_redirect_url="https://example.com/redirect"
      custom_redirect_failure_url="https://example.com/failure-redirect"
        ...
      ]
      wait_for_device_creation=true
      ...
  >
  ```

  ```json PHP theme={null}
  {
    "connect_webview_id": "12345678-1234-1234-1234-123456789012",
    "url": "https:\/\/connect.getseam.com\/connect_webviews\/view?connect_webview_id=12345678-1234-1234-1234-123456789012&auth_token=CvXRmaLfBghshH5rUNKcGivC6BVbjD6JG",
    "status": "pending",
    "login_successful": false,
    "custom_redirect_url": "https:\/\/example.com\/redirect",
    "custom_redirect_failure_url": "https:\/\/example.com\/failure-redirect",
      ...
    ],
    "wait_for_device_creation": true,
    ...
  }
  ```

  ```json C# theme={null}
  {
    "connect_webview_id": "12345678-1234-1234-1234-123456789012",
    "url": "https://connect.getseam.com/connect_webviews/view?connect_webview_id=12345678-1234-1234-1234-123456789012&auth_token=9eBKNtzB6ZKkSPPD33MZFshYSbmBcSMz7",
    "status": "pending",
    "login_successful": false,
    "custom_redirect_url": "https://example.com/redirect",
    "custom_redirect_failure_url": "https://example.com/failure-redirect",
      ...
    ],
    "wait_for_device_creation": true,
    ...
  }
  ```
</CodeGroup>

### Connect Webview Response

The created `connect_webview` object includes a `url` property. You use this URL to display the Connect Webview flow to your user.

***

## Step 2: Display the Connect Webview

In your app, [open the Connect Webview for your user](/core-concepts/connect-webviews/embedding-a-connect-webview-in-your-app#step-1-open-a-connect-webview), using the Connect Webview `url`.

You can [redirect to the Connect Webview URL](/core-concepts/connect-webviews/embedding-a-connect-webview-in-your-app#redirect-to-the-connect-webview-url) or [embed the Connect Webview in an iframe](/core-concepts/connect-webviews/embedding-a-connect-webview-in-your-app#embed-the-connect-webview-in-an-iframe).

<Info>
  If you choose to embed a Connect Webview in an iframe, it's important to
  understand that some providers move to a new tab during their authentication
  flow for security purposes. Seam is not able to abstract away this behavior.
</Info>

For instructions, see [Embedding a Connect Webview in Your App](/core-concepts/connect-webviews/embedding-a-connect-webview-in-your-app).

***

## Step 3: Your User Completes the Connect Webview

The Connect Webview guides your app user through the following authorization steps:

1. In the introduction page of the Connect Webview, the user clicks **Continue**.

<img alt="Connect Webview introduction page" />

2. The user selects their device or ACS brand.

<img alt="In the Connect Webview, the user selects their device or ACS brand." />

3. The user follows the displayed instructions to authorize their account.\
   Seam handles all the necessary authorization steps.

   For most brands, this authorization flow consists of a simple device account login. Some brands also require multifactor authentication or other information.\
   For example, brands like Yale offer multiple backend services, depending on the user's global region. Seam prompts the user to identify the correct service and then proceeds with the appropriate authorization request.

<img alt="In the Connect Webview, the user follows the displayed instructions to authorize the connection to Seam." />

4. The Connect Webview displays a page to indicate the successful device or ACS account connection.

   If an error occurs, the Connect Webview displays the error type, for example, an incorrect password.

   For more complicated errors, the Connect Webview displays a simple **Contact support** link that raises the issue to our support team.

<img alt="The Connect Webview displays a page to indicate the successful device or ACS account connection." />

***

## Step 4: Verify Successful Account Connection

Use one of the following methods to learn when the account connection has completed successfully:

* [Polling](/core-concepts/connect-webviews/verifying-successful-account-connection#polling)
* [Webhook](/core-concepts/connect-webviews/verifying-successful-account-connection#webhook)
* [Event listening](/core-concepts/connect-webviews/verifying-successful-account-connection#event-listening) (for iframes)

For instructions, see [Verifying Successful Account Connection](/core-concepts/connect-webviews/verifying-successful-account-connection).

<Info>
  You do not need to delete a Connect Webview once a user completes it. Instead,
  you can simply ignore completed Connect Webviews.
</Info>

***

## Step 5: Retrieve Connected Devices or ACS

Use the `connected_account_id` from the `connected_account.connected` event or the completed Connect Webview to retrieve the devices or ACS that your user has just connected to Seam.

Once you have retrieved the newly-connected set of devices or ACS, you can start controlling them with the Seam API. For example, for a set of devices, you may first want to prompt your user to group devices by property. For an ACS, you may first want your user to configure the access permissions to grant to new visitors or tenants.

For instructions, see [Retrieving Devices or Access Control Systems Connected Through a Connect Webview](/core-concepts/connect-webviews/retrieving-devices-or-access-control-systems-connected-through-a-connect-webview).

<Info>
  If your user wants to connect additional devices or ACS from different brands
  to Seam, your app must create and present a new Connect Webview for each
  different account that your user wants to connect.
</Info>

***

## Step 6: Use the Seam API to Control Your Users' Connected Devices or ACS

Continue using the Seam API to control your users' connected devices or ACS. For example, if you app user has connected a lock that support remote unlock operations, your app can now unlock the lock.

To learn about the actions that you can perform using the Seam API, see the Seam [capability guides](../../capability-guides/device-and-system-capabilities). These guides provide helpful tutorials and code samples, categorized by capability types.

* [Smart locks](/low-level-apis/smart-locks/index), including [locking/unlocking](../../low-level-apis/smart-locks/lock-and-unlock) and [managing access codes](/low-level-apis/smart-locks/access-codes/index)
* [Access control systems](/low-level-apis/access-systems/index)
* [Thermostats](/capability-guides/thermostats/index)
* [Noise sensors](/capability-guides/noise-sensors/index)
* [Mobile access](/capability-guides/mobile-access/index)


# Customizing Connect Webviews
Source: https://docs.seam.co/core-concepts/connect-webviews/customizing-connect-webviews

You can customize the look and feel, brand list, and behavior of your Connect Webviews.

You can use [Seam Console](/core-concepts/seam-console/index) to customize the [Connect Webviews](./) that you present to your users through your app.

You can customize the following characteristics of your Connect Webviews:

* [Look and feel](#customize-the-look-and-feel-of-your-connect-webviews)
* [Brands (manufacturers) to display](#customize-the-brands-to-display-in-your-connect-webviews), by integration status or device type
* [Device types (capabilities) to connect](#customize-the-types-of-devices-to-connect)
* [Behavior settings](#customize-the-behavior-settings-of-your-connect-webviews), including `automatically_manage_new_devices` and `wait_for_device_creation`

***

## Customize the Look and Feel of Your Connect Webviews

You can customize the look and feel of your Connect Webviews in the following ways:

* **Inviter name:** Define the name to display in your Connect Webviews as the entity requesting user authorization for Seam to access their device or access control system account.
* **Logo:** Choose a logo for your Connect Webviews. Ensure that the image file size does not exceed 1 MB.
* **Logo shape:** Select the shape of your logo displayed in Connect Webviews. Choices are **Circle** (default) or **Square**.
* **Primary button style:** Customize the background and text colors of the action button in your Connect Webview flow using a hex color code. The default color is #232426, which is almost black, and the default text color on the button is white.
* **Success message:** Customize the message that the Connect Webview displays when the connection completes successfully.

It is important to note that any changes you make to the customization features will apply to all of your new Connect Webviews.

<img alt="You can customize the look and feel of Connect Webviews." />

To customize the look and feel of your Connect Webviews:

1. In the top navigation pane of [Seam Console](https://console.seam.co/), click **Developer**.
2. In the left navigation pane, click **Webviews**.
3. On the **Webviews** page, click **Configure your webview**.
4. In the **Customize your Webview** pane, configure any of the following features:

   <table>
     <thead>
       <tr>
         <th>Feature</th>
         <th>Instructions</th>
       </tr>
     </thead>

     <tbody>
       <tr>
         <td>Inviter name</td>

         <td>
           <ol>
             <li>
               In the <strong>Inviter Name</strong> area, click
               <strong>Edit</strong>.
             </li>

             <li>
               Type the desired inviter name and then click
               <strong>Save</strong>.
             </li>
           </ol>
         </td>
       </tr>

       <tr>
         <td>Logo</td>

         <td>
           <ol>
             <li>
               In the <strong>Logo</strong> area, click
               <strong>Upload new logo</strong>.
             </li>

             <li>
               Navigate to and select the image file that contains the desired
               logo.

               <br />

               The image file size cannot exceed 1 MB.
             </li>

             <li>
               Click <strong>Open</strong>.
             </li>
           </ol>
         </td>
       </tr>

       <tr>
         <td>Logo shape</td>

         <td>
           <ol>
             <li>
               In the <strong>Logo Shape</strong> area, click
               <strong>Edit</strong>.
             </li>

             <li>
               Select <strong>Circle</strong> or <strong>Square</strong> and
               then click <strong>Save</strong>.
             </li>
           </ol>
         </td>
       </tr>

       <tr>
         <td>Primary button style</td>

         <td>
           <ol>
             <li>
               In the <strong>Primary Button Style</strong> area, click
               <strong>Edit</strong>.
             </li>

             <li>
               Click the <strong>Button Background Color</strong> field and
               specify the desired color. Default: <code>#232426</code> (almost
               black).
             </li>

             <li>
               Click the <strong>Button Text Color</strong> field and specify
               the desired color. Default: <code>#ffffff</code> (white).
             </li>

             <li>
               Click <strong>Save</strong>.
             </li>
           </ol>
         </td>
       </tr>

       <tr>
         <td>Success message</td>

         <td>
           <ol>
             <li>
               In the <strong>Success Message</strong> area, click
               <strong>Edit</strong>.
             </li>

             <li>
               <p>
                 In the <strong>Message</strong> field, type the desired success
                 message.
               </p>

               <p>
                 To reset the success message, click <strong>Clear</strong>.
               </p>
             </li>

             <li>
               Click <strong>Save</strong>.
             </li>
           </ol>
         </td>
       </tr>
     </tbody>
   </table>

***

## Customize the Brands to Display in Your Connect Webviews

By default, a Connect Webview displays all of the stable providers that Seam supports. Leaving it that way is the recommended approach: your user picks whatever brand they actually own, and every provider Seam adds later becomes available to your users automatically, without you shipping a code change.

When you do need to narrow the set of brands a Connect Webview displays, narrow by *integration status* or *device type* rather than by brand:

* **By integration status** — specify a [`provider_category`](/core-concepts/connect-webviews/connect-webview-process#step-1-create-a-connect-webview), such as `stable` or `beta`, in the [Create Connect Webview](/api/connect_webviews/create) request.
* **By device type** — specify [`accepted_capabilities`](#customize-the-types-of-devices-to-connect), such as `lock` or `thermostat`.

Both approaches keep working as Seam's provider coverage grows, because they describe *what you need* rather than naming individual brands.

<CodeGroup>
  ```javascript JavaScript theme={null}
  // Recommended: display every stable provider Seam supports.
  await seam.connectWebviews.create()

  // Or narrow by integration status when you need to.
  await seam.connectWebviews.create({
    provider_category: 'stable',
  })
  ```

  ```bash cURL theme={null}
  # Recommended: display every stable provider Seam supports.
  curl -X 'POST' \
    'https://connect.getseam.com/connect_webviews/create' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d '{}'
  ```

  ```python Python theme={null}
  # Recommended: display every stable provider Seam supports.
  seam.connect_webviews.create()

  # Or narrow by integration status when you need to.
  seam.connect_webviews.create(provider_category="stable")
  ```

  ```ruby Ruby theme={null}
  # Recommended: display every stable provider Seam supports.
  seam.connect_webviews.create()

  # Or narrow by integration status when you need to.
  seam.connect_webviews.create(provider_category: "stable")
  ```
</CodeGroup>

***

### Device Provider Keys

Seam identifies each provider with a device provider key. These keys appear on device and provider resources and in the [List Device Providers](/api/devices/list_device_providers) response, so you will encounter them when inspecting what a user connected. Seam supports the following device provider keys:

| Provider Name                                                                                                                    | Device Provider Key             |
| -------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- |
| [2N](/device-and-system-integration-guides/2n-intercom-systems)                                                                  | `my_2n`                         |
| [4SUITES](/device-and-system-integration-guides/4suites-locks)                                                                   | `four_suites`                   |
| [Akiles](/device-and-system-integration-guides/akiles-locks)                                                                     | `akiles`                        |
| [Akuvox](https://akuvox.com/)                                                                                                    | `akuvox`                        |
| [ASSA ABLOY Credential Service](/device-and-system-integration-guides/assa-abloy-vingcard-credential-services)                   | `assa_abloy_credential_service` |
| [ASSA ABLOY Visionline Access Control System](/device-and-system-integration-guides/assa-abloy-visionline-access-control-system) | `visionline`                    |
| [August Home](/device-and-system-integration-guides/august-locks)                                                                | `august`                        |
| [Avigilon Alta](/device-and-system-integration-guides/avigilon-alta-access-system)                                               | `avigilon_alta`                 |
| [Brivo](/device-and-system-integration-guides/brivo-access)                                                                      | `brivo`                         |
| [ControlByWeb](/device-and-system-integration-guides/controlbyweb-relays)                                                        | `controlbyweb`                  |
| [DoorKing](https://www.doorking.com/)                                                                                            | `doorking`                      |
| [Dormakaba Community](/device-and-system-integration-guides/dormakaba-community-access-control-system)                           | `dormakaba_community`           |
| [Dormakaba Oracode](/device-and-system-integration-guides/dormakaba-oracode-locks)                                               | `dormakaba_oracode`             |
| [ecobee](/device-and-system-integration-guides/ecobee-thermostats)                                                               | `ecobee`                        |
| [Genie Aladdin Connect](https://www.geniecompany.com/aladdin-connect-by-genie)                                                   | `genie`                         |
| [Honeywell Resideo](/device-and-system-integration-guides/honeywell-thermostats)                                                 | `honeywell_resideo`             |
| [igloohome](/device-and-system-integration-guides/igloohome-locks)                                                               | `igloohome`                     |
| [Kwikset](/device-and-system-integration-guides/kwikset-locks)                                                                   | `kwikset`                       |
| [Latch](/device-and-system-integration-guides/latch-access-control-system)                                                       | `latch`                         |
| [Linear](https://linear-solutions.com/)                                                                                          | `linear`                        |
| [Lockly](/device-and-system-integration-guides/lockly-locks)                                                                     | `lockly`                        |
| [Minut](/device-and-system-integration-guides/minut-sensors)                                                                     | `minut`                         |
| [Nest](/device-and-system-integration-guides/google-nest-thermostats)                                                            | `google_nest`                   |
| [NoiseAware](/device-and-system-integration-guides/noiseaware-sensors)                                                           | `noiseaware`                    |
| [Nuki](/device-and-system-integration-guides/nuki-locks)                                                                         | `nuki`                          |
| [PTI Storlogix Cloud](/device-and-system-integration-guides/pti-storlogix-cloud)                                                 | `pti`                           |
| [Salto KS Access System](/device-and-system-integration-guides/salto-ks-access-control-system)                                   | `salto_ks`                      |
| [Salto KS Locks](/device-and-system-integration-guides/salto-locks)                                                              | `salto_ks`                      |
| [Salto ProAccess Space Access System](/device-and-system-integration-guides/salto-proaccess-space-access-system)                 | `salto_space`                   |
| [Schlage](/device-and-system-integration-guides/schlage-locks)                                                                   | `schlage`                       |
| [Sensi](/device-and-system-integration-guides/sensi-thermostats)                                                                 | `sensi`                         |
| [SmartThings](/device-and-system-integration-guides/smartthings-hubs-+-devices/get-started-with-smartthings-hubs-+-smart-locks)  | `smartthings`                   |
| [Tedee](/device-and-system-integration-guides/tedee-locks)                                                                       | `tedee`                         |
| [TTLock](/device-and-system-integration-guides/ttlock-locks)                                                                     | `ttlock`                        |
| [Wyze](/device-and-system-integration-guides/wyze-locks)                                                                         | `wyze`                          |
| [Yale](/device-and-system-integration-guides/yale-locks)                                                                         | `yale`                          |

To learn what each provider supports, use the [List Device Providers](/api/devices/list_device_providers) method. The information that this method returns for each provider includes a set of [capability flags](../../capability-guides/device-and-system-capabilities#capability-flags), such as `device_provider.can_remotely_unlock`. If at least one supported device from a provider has a specific capability, the corresponding capability flag is `true`.

***

## Customize the Types of Devices to Connect

<Info>
  Currently, the only provider that supports multiple device types is
  SmartThings.
</Info>

Some providers support multiple device types, like smart locks and thermostats. To specify which types of devices your users can connect to Seam for a provider that supports multiple device types, use the `accepted_capabilities` parameter when creating a Connect Webview. This parameter is especially applicable when the Connect Webview [`automatically_manage_new_devices`](#automatically_manage_new_devices) parameter is `true`. Set `accepted_capabilities` to an array containing one or more of the following values to indicate the capabilities of the devices that the Connect Webview can accept:

* `lock`
* `thermostat`
* `noise_sensor`

Seam maintains a default value for this parameter for each provider. For example, for SmartThings, the default value for `accepted_capabilities` is `["locks"]`. To begin accepting SmartThings-connected thermostats, as well as locks, set `accepted_capabilities` to `["locks", "thermostats"]`. For Honeywell Resideo, the default value is `["thermostats"]`.

## Customize the Behavior Settings of Your Connect Webviews

You can use the following two properties to customize the behavior of your Connect Webviews:

* [`automatically_manage_new_devices`](#automatically_manage_new_devices)
* [`wait_for_device_creation`](#wait_for_device_creation)

You configure these properties when you are creating the Connect Webview. Consequently, you can customize these two characteristics for each of your Connect Webviews.

### `automatically_manage_new_devices`

Seam charges fees for different parts of the API, like connecting a device, creating an access code or thermostat schedule, and creating an access control system user. To learn more, contact our team. You can exclude specific devices from your bill by marking them as "[unmanaged](../devices/managed-and-unmanaged-devices)."

The default value for `automatically_manage_new_devices` is `true`. Consequently, by default, Seam imports all devices and makes them available for use. However, if you set this property to `false`, Seam sets the `is_managed` property for all new devices to `false` (that is, unmanaged) when a user first connects their account to Seam.

### `wait_for_device_creation`

This property enables you to specify whether Seam should finish syncing all devices in a newly-connected account before completing the associated Connect Webview.

The default value for `wait_for_device_creation` is `false`. If `wait_for_device_creation` is `false`, you should wait for `connected_account.completed_first_sync` before retrieving your devices. This event indicates that Seam has finished the first sync of the connected account, and the connected devices are available.

Alternately, if you set `wait_for_device_creation` to `true`, Seam finishes syncing all devices in the newly-connected account before proceeding to the final page of the Connect Webview. In this case, you can fetch your devices immediately upon the completion of the Connect Webview.


# Embedding a Connect Webview in Your App
Source: https://docs.seam.co/core-concepts/connect-webviews/embedding-a-connect-webview-in-your-app

Use redirection or an iframe to embed a Connect Webview in your app.

<img alt="Seam makes it easy for your users to authorize your app to control their devices using the Seam API." />

To enable your users to connect their devices or access control system to Seam through your app, use a [Connect Webview](./). First, in your app, add a mechanism—such as a button—to [open a new Connect Webview](#step-1-open-a-connect-webview). Then, you can use either of the following two methods to [display the Connect Webview](#step-2-display-the-connect-webview) in your app:

* [Redirect to the Connect Webview URL.](#redirect-to-the-connect-webview-url) **Recommended.**
* [Embed the Connect Webview in an inline frame (iframe).](#embed-the-connect-webview-in-an-iframe)

<Info>
  **Use a full-page redirect unless you have a specific reason not to.** Some
  device providers refuse to load their own login page inside an iframe, so an
  embedded Connect Webview can break for those brands—and because that decision
  belongs to the provider, Seam cannot work around it or warn you before it
  changes. A full-page redirect works for every provider Seam supports.
</Info>

***

## Step 1: Open a Connect Webview

To enable users to connect their devices or access control system with your app, present a button to create and display a new Connect Webview. If your app has a settings section, we recommend creating a device or ACS settings page and displaying an **Add** or **Link** button, such as **Add Devices**.

When your user clicks this button, your app can either [redirect to the Connect Webview URL](#redirect-to-the-connect-webview-url) or [embed the Connect Webview in an iframe](#embed-the-connect-webview-in-an-iframe) and present it in a modal.

<img
  alt="Add a button to your app to enable your users to connect their devices or
ACS using a Connect Webview."
/>

***

## Step 2: Display the Connect Webview

You can [redirect to the Connect Webview URL](#redirect-to-the-connect-webview-url) or [use an iframe](#embed-the-connect-webview-in-an-iframe) to display the Connect Webview. Seam recommends the redirect. The following sections describe both options:

### Redirect to the Connect Webview URL

To incorporate a Connect Webview in your app using redirection:

1. [Create the Connect Webview.](#step-1-open-a-connect-webview)
   * Make sure to set a `custom_redirect_url` so that the Connect Webview redirects back to the desired page within your app after the Connect Webview flow completes. **This is required for a redirect flow.** Without it, the Connect Webview finishes on a success screen that asks the user to close the window—and a page your app navigated to cannot close itself or return the user to your app. Seam can only close the window automatically when Seam itself opened the Connect Webview in a popup.
   * If you want to redirect to a different page when there is an error, you can set the `custom_redirect_failure_url` to the URL for the desired page.
   * We recommend setting `wait_for_device_creation` to `true` so that the Connect Webview does not complete until Seam completes the first sync of the connected account and devices or ACS.

2. Redirect your app to the URL for the created Connect Webview.\
   Pass the Connect Webview `url` to the client portion of your app and redirect your app to this URL.\
   The resulting page displays the [authorization flow](#step-1-open-a-connect-webview) through which your app user can link their device or ACS account to Seam.\\

   <img alt="The page to which you redirect your app displays the authorization flow." />

   Once the user has completed the authorization flow, the Connect Webview redirects back to your app (specifically to the `custom_redirect_url`). Note that Seam appends the following search parameters to the URL after the redirect:

   * `connect_webview_id`
   * If there is an error, `error_code` and `error_message`

3. [Your user completes the Connect Webview authorization flow.](#opening-connect-webviews-in-ios-or-android-apps)

4. [Learn when the device or ACS account connection has completed successfully.](#step-2-display-the-connect-webview)

5. [Retrieve the devices or ACS that your user has just connected to Seam.](#step-2-display-the-connect-webview)

6. [Use the Seam API to control your users' connected devices or ACS.](#step-2-display-the-connect-webview)

***

### Embed the Connect Webview in an iframe

To incorporate a Connect Webview in your app using an HTML [iframe](https://www.w3schools.com/html/html_iframe.asp):

1. [Create the Connect Webview.](#step-1-open-a-connect-webview)\
   We recommend setting `wait_for_device_creation` to `true` so that the Connect Webview does not complete until Seam completes the first sync of the connected account and devices or ACS.

2. Display the URL for the created Connect Webview in an iframe.\
   Pass the Connect Webview `url` to the client portion of your app and use an HTML [iframe](https://www.w3schools.com/html/html_iframe.asp) to display the Connect Webview URL.

   For example:

   ```html theme={null}
   <iframe
     style="border: none;min-height: 600px;height: 100%;width: 100%"
     allow="clipboard-write"
     src="<your connect_webview.url>"
   />
   ```

3. [Your user completes the Connect Webview authorization flow.](#opening-connect-webviews-in-ios-or-android-apps)

   <Warning>
     Provider behavior limits what an iframe can do, and Seam cannot abstract it
     away:

     * Some providers move to a new tab partway through their authentication flow for security reasons.
     * Some providers refuse to load their login page in an iframe at all, which breaks the connection flow for that brand. Nuki is one known example.

     Because each provider controls this, a brand that embeds correctly today can
     stop doing so after a provider-side update, with no change on your part and
     no warning from Seam. If you support more than a handful of brands, prefer
     the [full-page redirect](#redirect-to-the-connect-webview-url).
   </Warning>

4. [Learn when the device or ACS account connection has completed successfully.](#step-2-display-the-connect-webview)\
   When the connection completes successfully, you can close the iframe.

5. [Retrieve the devices or ACS that your user has just connected to Seam.](#step-2-display-the-connect-webview)

6. [Use the Seam API to control your users' connected devices or ACS.](#step-2-display-the-connect-webview)

***

## Opening Connect Webviews in iOS or Android Apps

If you want to include a Connect Webview flow inside an iOS or Android app, it is important to note that iOS and Android require verification for each link to which a user navigates within an app. Consequently, you must register a navigation delegate to handle any links within the Connect Webview. For example, there is a link from the Connect Webview to the [Seam **Privacy & Legal** webpage](https://www.seam.co/legal). This link includes `target=_blank` in the anchor tag to open the privacy policy in a new tab or window. You must configure your iOS or Android app to handle opening links in a new browser tab or window.

The following example shows how to handle all links to URLs that are not in the `getseam.com` or `seam.co` domain within a Connect Webview embedded in an iOS or Android app:

<CodeGroup>
  ```swift iOS (Swift) theme={null}
  someWebView.navigationDelegate = self

  extension YourViewController: WKNavigationDelegate {
  func webView(_ webView: WKWebView, decidePolicyFor navigationAction: WKNavigationAction, decisionHandler: @escaping (WKNavigationActionPolicy) -> Void) {
  if let url = navigationAction.request.url, navigationAction.navigationType == .linkActivated {
  if (url.host != "getseam.com" || url.host != "seam.co") {
  UIApplication.shared.open(url)
  decisionHandler(.cancel)
  return
  }
  }
  decisionHandler(.allow)
  }
  }

  ```

  ```kotlin Android (Kotlin) theme={null}
  webView.webViewClient = object : WebViewClient() {
    override fun shouldOverrideUrlLoading(view: WebView, url: String): Boolean {
      if (Uri.parse(url).host != "getseam.com" || Uri.parse(url).host != "seam.co") {
        val intent = Intent(Intent.ACTION_VIEW, Uri.parse(url))
        view.context.startActivity(intent)
        return true
      }
      return false
    }
  }
  ```
</CodeGroup>

For details, see the following relevant iOS or Android documentation:

* [iOS WKNavigationDelegate](https://developer.apple.com/documentation/webkit/wknavigationdelegate)
* [Android shouldOverrideUrlLoading](https://developer.android.com/reference/android/webkit/WebViewClient#shouldOverrideUrlLoading\(android.webkit.WebView,%20android.webkit.WebResourceRequest\))


# Filtering Connect Webviews by Custom Metadata
Source: https://docs.seam.co/core-concepts/connect-webviews/filtering-connect-webviews-by-custom-metadata

When listing Connect Webviews, you can filter by custom metadata.

When you use [List Connect Webviews](/api/connect_webviews/list), you can filter the list by one or more [custom metadata](/core-concepts/connect-webviews/attaching-custom-data-to-the-connect-webview) pairs. Include the `custom_metadata_has` parameter with a JSON string that specifies the desired key:value pairs.

**Request:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  const connect_webviews = await seam.connectWebviews.list({
    custom_metadata_has: {
      internal_account_id: 'user-1',
    },
  })

  console.log(connect_webviews)
  ```

  ```bash cURL theme={null}
  curl -X 'POST' \
    'https://connect.getseam.com/connect_webviews/list' \
    -H 'accept: application/json' \
    -H 'Authorization: Bearer ${API_KEY}' \
    -H 'Content-Type: application/json' \
    -d '{
    "custom_metadata_has": {
      "internal_account_id": "user-1"
    },
  }'
  ```

  ```python Python theme={null}
  connect_webviews = seam.connect_webviews.list(
    custom_metadata_has = {
      "internal_account_id": "user-1"
    }
  )

  pprint(connect_webviews)
  ```

  ```ruby Ruby theme={null}
  connect_webviews = client.connect_webviews.list(
    custom_metadata_has: {
      "internal_account_id": "user-1"
    }
  )

  puts connect_webviews.inspect
  ```

  ```php PHP theme={null}
  $webviews = $seam->connect_webviews->list(
    custom_metadata_has: array('internal_account_id' => 'user-1')
  );

  echo json_encode($webviews);
  ```

  ```csharp C# theme={null}
  var customMetadata = new Dictionary<string, string>() {
    {"internal_account_id", "user-1"}
  };

  seam.ConnectWebviews.List(
    customMetadataHas: customMetadata
  );
  ```
</CodeGroup>

**Response:**

<CodeGroup>
  ```json JavaScript theme={null}
  [
    {
      connect_webview_id: '3c3f4c15-e7db-47c6-bc5a-1bf206ff269c',
      url: 'https://connect.getseam.com/connect_webviews/view?connect_webview_id=3c3f4c15-e7db-47c6-bc5a-1bf206ff269c&auth_token=LrpMC4MVHAY8YJRcNFeX1nQcb7tGNwpot',
      status: 'pending',
      workspace_id: '398d80b7-3f96-47c2-b85a-6f8ba21d07be',
      custom_metadata: { internal_account_id: 'user-1' },
      ...
    },
    ...
  ]
  ```

  ```json cURL theme={null}
  {
    "connect_webviews": [
      {
        "connect_webview_id": "3c3f4c15-e7db-47c6-bc5a-1bf206ff269c",
        "url": "https://connect.getseam.com/connect_webviews/view?connect_webview_id=3c3f4c15-e7db-47c6-bc5a-1bf206ff269c&auth_token=LrpMC4MVHAY8YJRcNFeX1nQcb7tGNwpot",
        "status": "pending",
        "workspace_id": "398d80b7-3f96-47c2-b85a-6f8ba21d07be",
        "custom_metadata": {
          "id": "internal_id_1"
        },
        ...
      },
      ...
    ],
    "ok": true
  }
  ```

  ```json Python theme={null}
  [
    ConnectWebview(
      workspace_id='398d80b7-3f96-47c2-b85a-6f8ba21d07be',
      connect_webview_id='3c3f4c15-e7db-47c6-bc5a-1bf206ff269c',
      status='pending',
      url='https://connect.getseam.com/connect_webviews/view?connect_webview_id=xxxx&auth_token=yyyy',
      custom_metadata={"internal_account_id": "user-1"},
      ...
    ),
    ...
  ]
  ```

  ```json Ruby theme={null}
  [
    &#x3C;Seam::ConnectWebview:0x00438
      connect_webview_id="3c3f4c15-e7db-47c6-bc5a-1bf206ff269c"
      url="https://connect.getseam.com/connect_webviews/view?connect_webview_id=3c3f4c15-e7db-47c6-bc5a-1bf206ff269c&#x26;auth_token=LrpMC4MVHAY8YJRcNFeX1nQcb7tGNwpot"
      status="pending"
      workspace_id="398d80b7-3f96-47c2-b85a-6f8ba21d07be"
      custom_metadata={"internal_account_id"=>"user-1"}
      ...
    >,
    ...
  ]
  ```

  ```json PHP theme={null}
  [
    {
      "connect_webview_id": "3c3f4c15-e7db-47c6-bc5a-1bf206ff269c",
      "url": "https://connect.getseam.com/connect_webviews/view?connect_webview_id=xxxx&auth_token=yyyy",
      "status": "pending",
      "workspace_id": "398d80b7-3f96-47c2-b85a-6f8ba21d07be",
      "custom_metadata": {"internal_account_id": "user-1"},
      ...
    },
    ...
  ]
  ```

  ```json C# theme={null}
  {
    "connect_webview_id": "3874d8b4-4bb5-470a-9fc7-a54931a4b933",
    "url": "https://connect.getseam.com/connect_webviews/view?connect_webview_id=3c3f4c15-e7db-47c6-bc5a-1bf206ff269c&auth_token=LrpMC4MVHAY8YJRcNFeX1nQcb7tGNwpot",
    "workspace_id": "398d80b7-3f96-47c2-b85a-6f8ba21d07be",
    "custom_metadata": {
      "internal_account_id": "user-1"
    },
    ...
  }...
  ```
</CodeGroup>


# Connect Webviews
Source: https://docs.seam.co/core-concepts/connect-webviews/index

Use Connect Webviews to connect your users' devices or access control system to Seam. Your users authorize your app to control these devices or ACS with the Seam API.

<img
  alt="The Connect Webview flow walks your users through the process of
authorizing your app to control their devices or ACS with the Seam API."
/>

## What are Connect Webviews?

Seam Connect Webviews are fully-embedded, [customizable](/core-concepts/connect-webviews/customizing-connect-webviews) client-side components that you [add to your app](/core-concepts/connect-webviews/embedding-a-connect-webview-in-your-app) if you want to enable your users to import their own devices or ACS using your app. The Connect Webview flow walks your users through the process of authorizing your app to control their devices or ACS with the Seam API. Using this flow, your app users log in to their device or ACS accounts.

Seam handles all the authentication steps, and—once your user has completed the authorization through your app—you can access and control their devices or ACS using the Seam API. Connect Webviews perform credential validation, multifactor authentication (when applicable), and error handling for each brand that Seam supports. Further, Connect Webviews work across all modern browsers and platforms, including Chrome, Safari, and Firefox.

***

## Get Started with Connect Webviews

First, learn how to [create, display, and complete Connect Webviews](/core-concepts/connect-webviews/connect-webview-process).

Then, learn how to [customize your Connect Webviews](/core-concepts/connect-webviews/customizing-connect-webviews).


# Retrieving Devices or Access Control Systems Connected Through a Connect Webview
Source: https://docs.seam.co/core-concepts/connect-webviews/retrieving-devices-or-access-control-systems-connected-through-a-connect-webview

Learn how to retrieve the set of devices or ACS that your app user connected to Seam through a specific Connect Webview.

When your app user completes a [Connect Webview](./) authorization flow successfully, the resulting [`connected_account.connected` event](/api/connected_accounts/events#connected_account-connected) includes a `connected_account_id`. Also, once the connection is successful, the [`connect_webview` object](/api/connect_webviews/object) includes the `connected_account_id`.

The first step in controlling connected devices or a connected ACS is to retrieve the newly-connected set of devices or ACS.

***

## Retrieve Connected Devices

Use this `connected_account_id` in a [List Devices](/api/devices/list) command to retrieve the devices that your user has just connected to Seam.

<Info>
  If you set `wait_for_device_creation` to `false` when [creating the Connect
  Webview](/core-concepts/connect-webviews/embedding-a-connect-webview-in-your-app#step-1-open-a-connect-webview), you should wait for the
  [`connected_account.completed_first_sync`
  event](/api/connected_accounts/events#connected_account-completed_first_sync) before retrieving the user's
  devices. This event indicates that Seam has finished the first sync of the
  connected account and the devices are now available.
</Info>

**Code:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  // Retrieve all devices for the connected_account_id.
  const connectedDevices = await seam.devices.list({
    connected_account_id: "11111111-1111-1111-1111-222222222222"
  });
  ```

  ```bash cURL theme={null}
  # Retrieve all devices for the connected_account_id.
  connected_devices=$(
    # Use GET or POST.
    curl -X 'GET' \
      'https://connect.getseam.com/devices/list' \
      -H 'accept: application/json' \
      -H "Authorization: Bearer ${SEAM_API_KEY}" \
      -H 'Content-Type: application/json' \
      -d '{
      "connected_account_id": "11111111-1111-1111-1111-222222222222"
    }')
  ```

  ```python Python theme={null}
  # Retrieve all devices for the connected_account_id.
  connected_devices = seam.devices.list(
    connected_account_id="11111111-1111-1111-1111-222222222222"
  )
  ```

  ```ruby Ruby theme={null}
  # Retrieve all devices for the connected_account_id.
  connected_devices = seam.devices.list(
    connected_account_id: "11111111-1111-1111-1111-222222222222"
  )
  ```

  ```php PHP theme={null}
  // Retrieve all devices for the connected_account_id.
  $connected_devices = $seam->devices->list(
    connected_account_id: "11111111-1111-1111-1111-222222222222"
  );
  ```

  ```csharp C# theme={null}
  // Retrieve all devices for the connectedAccountId.
  var connectedDevices = seam.Devices.List(
    connectedAccountId: "11111111-1111-1111-1111-222222222222"
  );
  ```
</CodeGroup>

**Output:**

<CodeGroup>
  ```json JavaScript theme={null}
  [
    {
      connected_account_id: '11111111-1111-1111-1111-222222222222',
      device_id: '11111111-1111-1111-1111-444444444444',
      display_name: 'Front Door Lock',
      is_managed: true,
      ...
    },
    ...
  ]
  ```

  ```json cURL theme={null}
  {
    "devices": [
      {
        "connected_account_id": "11111111-1111-1111-1111-222222222222",
        "device_id": "11111111-1111-1111-1111-444444444444",
        "display_name": "Front Door Lock",
        "is_managed": true,
        ...
      },
      ...
    ],
    "ok": true
  }
  ```

  ```json Python theme={null}
  [
    Device(
      connected_account_id='11111111-1111-1111-1111-222222222222',
      device_id='11111111-1111-1111-1111-444444444444',
      display_name='Front Door Lock',
      is_managed=True,
      ...
    ),
    ...
  ]
  ```

  ```json Ruby theme={null}
  [
    <
      Seam::Device:0x00438
        connected_account_id="11111111-1111-1111-1111-222222222222"
        device_id="11111111-1111-1111-1111-444444444444"
        display_name='Front Door Lock'
        is_managed=true
        ...
    >,
    ...
  ]
  ```

  ```json PHP theme={null}
  [
    {
      "connected_account_id": "11111111-1111-1111-1111-222222222222",
      "device_id": "11111111-1111-1111-1111-444444444444",
      "display_name": "Front Door Lock",
      "is_managed": true,
      ...
    },
    ...
  ]
  ```

  ```json C# theme={null}
  {
    "connected_account_id": "11111111-1111-1111-1111-222222222222",
    "device_id": "11111111-1111-1111-1111-444444444444",
    "display_name": "Front Door Lock",
    "is_managed": true,
    ...
  }
  ...
  ```
</CodeGroup>

***

## Retrieve a Connected Access Control System

Use this `connected_account_id` in a [List ACS Systems](/api/acs/systems/list) command to retrieve the ACS that your user has just connected to Seam.

<Info>
  If you set `wait_for_device_creation` to `false` when [creating the Connect
  Webview](/core-concepts/connect-webviews/embedding-a-connect-webview-in-your-app#step-1-open-a-connect-webview), you should wait for the
  [`connected_account.completed_first_sync`
  event](/api/connected_accounts/events#connected_account-completed_first_sync) before retrieving the user's
  ACS. This event indicates that Seam has finished the first sync of the
  connected account and the `acs_system` is now available.
</Info>

**Code:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  // Retrieve all acs_systems for the connected_account_id.
  const connectedAcsSystems = await seam.acs.systems.list({
    connected_account_id: "11111111-1111-1111-2222-111111111111"
  });
  ```

  ```bash cURL theme={null}
  # Retrieve all acs_systems for the connected_account_id.
  connected_acs_systems=$(
    # Use GET or POST.
    curl -X 'GET' \
      'https://connect.getseam.com/acs/systems/list' \
      -H 'accept: application/json' \
      -H "Authorization: Bearer ${SEAM_API_KEY}" \
      -H 'Content-Type: application/json' \
      -d '{
      "connected_account_id": "11111111-1111-1111-2222-111111111111"
    }')
  ```

  ```python Python theme={null}
  # Retrieve all acs_systems for the connected_account_id.
  connected_acs_systems = seam.acs.list(
    connected_account_id="11111111-1111-1111-2222-111111111111"
  )
  ```

  ```ruby Ruby theme={null}
  # Coming soon!
  ```

  ```php PHP theme={null}
  // Retrieve all acs_systems for the connected_account_id.
  $connected_acs_systems = $seam->acs->systems->list(
    connected_account_id: "11111111-1111-1111-2222-111111111111"
  );
  ```

  ```csharp C# theme={null}
  // Retrieve all acs_systems for the connectedAccountId.
  var connectedAcsSystems = seam.Acs.Systems.List(
    connectedAccountId: "11111111-1111-1111-2222-111111111111"
  );
  ```
</CodeGroup>

**Output:**

<CodeGroup>
  ```json JavaScript theme={null}
  [
    {
      connected_account_ids: [
        '11111111-1111-1111-2222-111111111111'
      ],
      acs_system_id: '11111111-1111-1111-1111-111111111111',
      name: 'My ACS',
      ...
    },
    ...
  ]
  ```

  ```json cURL theme={null}
  {
    "acs_systems": [
      {
        "connected_account_ids": [
          "11111111-1111-1111-2222-111111111111"
        ],
        "acs_system_id": "11111111-1111-1111-1111-111111111111",
        "name": "My ACS",
        ...
      },
      ...
    ],
    "ok": true
  }
  ```

  ```json Python theme={null}
  [
    AcsSystem(
      connected_account_ids=[
        '11111111-1111-1111-2222-111111111111'
      ],
      acs_system_id='11111111-1111-1111-1111-111111111111',
      name='My ACS',
      ...
    ),
    ...
  ]
  ```

  ```json Ruby theme={null}
  # Coming soon!
  ```

  ```json PHP theme={null}
  [
    {
      "connected_account_ids": [
        "11111111-1111-1111-2222-111111111111"
      ],
      "acs_system_id": "11111111-1111-1111-1111-111111111111",
      "name": "My ACS",
      ...
    },
    ...
  ]
  ```

  ```json C# theme={null}
  {
    "connected_account_ids": [
      "11111111-1111-1111-2222-111111111111"
    ],
    "acs_system_id": "11111111-1111-1111-1111-111111111111",
    "name": "My ACS",
    ...
  }
  ...
  ```
</CodeGroup>


# Verifying Successful Account Connection
Source: https://docs.seam.co/core-concepts/connect-webviews/verifying-successful-account-connection

Learn how to find out when your user's device or ACS account has connected successfully to Seam.

Use one of the following methods to find out when your user's account has connected successfully to Seam through your app:

* If you've redirected your app to the Connect Webview, [poll](#polling) or use a [webhook](#webhook) to determine when the Connect Webview has completed successfully. You can then [retrieve the device or ACS](/core-concepts/connect-webviews/retrieving-devices-or-access-control-systems-connected-through-a-connect-webview) associated with the newly-connected account.
* If you've embedded the Connect Webview in an [iframe](https://www.w3schools.com/html/html_iframe.asp), use [event listening](#event-listening) to determine when to close the iframe. You can then [retrieve the device or ACS](/core-concepts/connect-webviews/retrieving-devices-or-access-control-systems-connected-through-a-connect-webview) associated with the newly-connected account.

<Info>
  You do not need to delete a Connect Webview once a user completes it. Instead,
  you can simply ignore completed Connect Webviews.
</Info>

***

## Polling

Use the `connect_webview_id` to retrieve the Connect Webview instance. You can check the following properties:

| Property           | Value when connected successfully |
| ------------------ | --------------------------------- |
| `status`           | `authorized`                      |
| `login_successful` | `true`                            |

Also, once the connection is successful, the `connect_webview` object includes a `connected_account_id`.

**Code:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  const updatedConnectWebview = await seam.connectWebviews.get({
    connect_webview_id: connectWebview.connect_webview_id,
  })
  ```

  ```bash cURL theme={null}
  curl -X 'GET' \
    'https://connect.getseam.com/connect_webviews/get' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d "{
    \"connect_webview_id\": \"${connect_webview_id}\"
  }"
  ```

  ```python Python theme={null}
  updated_connect_webview = seam.connect_webviews.get(created_connect_webview.connect_webview_id)
  ```

  ```ruby Ruby theme={null}
  updated_connect_webview = seam.connect_webviews.get(
    connect_webview_id: connect_webview.connect_webview_id
  )
  ```

  ```php PHP theme={null}
  $updated_connect_webview = $seam->connect_webviews->get(
    connect_webview_id: $connect_webview->connect_webview_id
  );
  ```

  ```csharp C# theme={null}
  var updatedConnectWebview = seam.ConnectWebviews.Get(
    connectWebviewId: connectWebview.connectWebviewId
  );
  ```
</CodeGroup>

**Output:**

<CodeGroup>
  ```json JavaScript theme={null}
  {
    connect_webview_id: '12345678-1234-1234-1234-123456789012',
    status: 'authorized',
    login_successful: true,
    connected_account_id: '11111111-1111-1111-1111-222222222222',
    ...
  }
  ```

  ```json cURL theme={null}
  {
    "connect_webview": {
      "connect_webview_id": "12345678-1234-1234-1234-123456789012",
      "status": "authorized",
      "login_successful": true,
      "connected_account_id": "11111111-1111-1111-1111-222222222222",
      ...
    },
    "ok": true
  }
  ```

  ```json Python theme={null}
  ConnectWebview(
    connect_webview_id='12345678-1234-1234-1234-123456789012',
    status='authorized',
    login_successful=True,
    connected_account_id='11111111-1111-1111-1111-222222222222',
    ...
  )
  ```

  ```json Ruby theme={null}
  <
    Seam::ConnectWebview:0x00438
      connect_webview_id="12345678-1234-1234-1234-123456789012"
      status="authorized"
      login_successful=true
      connected_account_id="11111111-1111-1111-1111-222222222222"
      ...
  >
  ```

  ```json PHP theme={null}
  {
    "connect_webview_id": "12345678-1234-1234-1234-123456789012",
    "status": "authorized",
    "login_successful": true,
    "connected_account_id": "11111111-1111-1111-1111-222222222222",
    ...
  }
  ```

  ```json C# theme={null}
  {
    "connect_webview_id": "12345678-1234-1234-1234-123456789012",
    "status": "authorized",
    "login_successful": true,
    "connected_account_id": "11111111-1111-1111-1111-222222222222",
    ...
  }
  ```
</CodeGroup>

***

## **Webhook**

When Seam successfully establishes the connection to the user's device or ACS account, Seam emits a [`connected_account.connected` event](/api/connected_accounts/events#connected_account-connected). This event includes a `connect_webview_id` property.

To avoid polling, use a Seam webhook to monitor for a `connected_account.connected` event with a `connect_webview_id` that matches the `connect_webview_id` of the appropriate Connect Webview instance.

Note that the `connected_account.connected` event also includes a `connected_account_id` property.

For more information, see [Webhooks](../../developer-tools/webhooks).

```json theme={null}
{
  "event_id": "22222222-3333-4444-5555-666666666666",
  "event_type": "connected_account.connected",
  "connected_account_id": "11111111-1111-1111-1111-222222222222",
  "connect_webview_id": "12345678-1234-1234-1234-123456789012",
  "occurred_at": "2024-07-17T05:01:53.157Z",
  ...
}
```

***

## **Event Listening**

When you [host a Connect Webview in an HTML iframe](/core-concepts/connect-webviews/embedding-a-connect-webview-in-your-app#embed-the-connect-webview-in-an-iframe), the [iframe](https://www.w3schools.com/html/html_iframe.asp) uses `window.parent.postMessage` to send messages to the parent window that is hosting the iframe. `window.parent.postMessage` is a cross-origin communication mechanism available in web browsers.

Register an event listener for the parent window containing the iframe to monitor for `message` events. Specifically, listen for a `connect_webview.login_succeeded` event. This event indicates that Seam has successfully established the connection to the user's device or ACS account. A `connect_webview.login_failed` event indicates that the account connection did not complete successfully.

For example:

```javascript theme={null}
window.addEventListener(
  'message',
  (event) => {
    if (event.data?.event?.event_type === 'connect_webview.login_succeeded') {
      // Do something.
    }
  },
  false,
)
```

***

## Additional Connection-Related Events

Once you have received a `connect_webview.login_succeeded` event, you can use webhooks or listen for any of the following useful connection-related events:

| Event                                    | Description                                                                                                                                                                                                                                                                                                                |
| ---------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `connected_account.created`              | A [connected account](/core-concepts/connected-accounts/index) has been imported into your Seam workspace.                                                                                                                                                                                                                 |
| `connected_account.connected`            | Seam has established connection to or is reconnected to a [connected account](/core-concepts/connected-accounts/index).                                                                                                                                                                                                    |
| `connected_account.completed_first_sync` | Seam has finished the first sync of a connected account, and the corresponding devices or systems are now available.                                                                                                                                                                                                       |
| `connected_account.disconnected`         | Seam can no longer reach a [connected account](/core-concepts/connected-accounts/index)—usually because its credentials expired or were revoked. Subscribe to this event to prompt the account owner to [reconnect](/core-concepts/connected-accounts/reconnecting-an-account).                                            |
| `device.added`                           | A device was added to Seam or was re-added to Seam after having been removed.                                                                                                                                                                                                                                              |
| `device.connected`                       | <p>The status of a device changed from offline to online. That is, the <code>device.properties.online</code> property changed from <code>false</code> to <code>true</code>.<br />Note that some devices operate entirely in offline mode, so Seam never emits a <code>device.connected</code> event for these devices.</p> |


# Adding Custom Metadata to a Connected Account
Source: https://docs.seam.co/core-concepts/connected-accounts/adding-custom-metadata-to-a-connected-account

You can add or change custom metadata for a connected account.

You can use custom metadata to store a custom payload or object, tailored to the specific needs of your app. For example, this feature is useful for tracking customer information, internal user IDs, or other internal resources for a [connected account](./). Storing custom metadata in a Seam `connected_account` object enables you to look up an internal resource from directly within your Seam [workspace](/core-concepts/workspaces/index). Then, you can [filter connected accounts by the desired metadata](./filtering-connected-accounts-by-custom-metadata).

<Info>
  You can also use unique resource keys as an easy way to link your resources to
  Seam resources. For details, see [Mapping Your Resources to Seam
  Resources](../mapping-your-resources-to-seam-resources).
</Info>

If the associated [Connect Webview](/core-concepts/connect-webviews/index) contains custom metadata, Seam transfers this custom metadata as the initial value for this property. However, you can use the [Update Connected Account](/api/connected_accounts/update) method with the optional `custom_metadata` property to change or add custom metadata for the connected account. This property accepts up to 50 JSON key:value pairs.

**Request:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  const connectedAccountUpdate = await seam.connectedAccounts.update({
    connected_account_id: '6e1cad57-b244-40ca-b4f3-30a46c8000d4',
    custom_metadata: {
      internal_account_id: 'user-1',
    },
  })

  console.log(connectedAccountUpdate)
  ```

  ```bash cURL theme={null}
  curl -X 'POST' \
    'https://connect.getseam.com/connected_accounts/update' \
    -H 'accept: application/json' \
    -H 'Authorization: Bearer ${API_KEY}' \
    -H 'Content-Type: application/json' \
    -d '{
    "connected_account_id": "6e1cad57-b244-40ca-b4f3-30a46c8000d4",
    "custom_metadata": {
      "internal_account_id": "user-1"
    }
  }'
  ```

  ```python Python theme={null}
  connected_account_update = seam.connected_accounts.update(
      connected_account_id = "6e1cad57-b244-40ca-b4f3-30a46c8000d4",
      custom_metadata = {
          "internal_account_id": "user-1"
      }
  )

  pprint(connected_account_update)
  ```

  ```ruby Ruby theme={null}
  connected_account_update = client.connected_accounts.update(
    connected_account_id: "6e1cad57-b244-40ca-b4f3-30a46c8000d4",
    custom_metadata: {
      "internal_account_id": "user-1"
    }
  )

  puts connected_account_update.inspect
  ```

  ```php PHP theme={null}
  $connected_account_update = $seam->connected_accounts->update(
    connected_account_id: "6e1cad57-b244-40ca-b4f3-30a46c8000d4",
    custom_metadata: array('internal_account_id' => 'user-1')
  )
  echo json_encode($connected_account_update, JSON_PRETTY_PRINT);
  ```

  ```csharp C# theme={null}
  var customMetadata = new Dictionary<string, string>()
  {
    {"internal_account_id", "user-1"}
  };

  var connectedAccountUpdate = seam.ConnectedAccounts.Update(
    connectedAccountId: "6e1cad57-b244-40ca-b4f3-30a46c8000d4",
    customMetadata: customMetadata
  );

  Console.WriteLine(connectedAccountUpdate);
  ```
</CodeGroup>

**Response:**

<CodeGroup>
  ```json JavaScript theme={null}
  { "ok": true }
  ```

  ```json cURL theme={null}
  {
    "ok": true
  }
  ```

  ```json Python theme={null}
  True
  ```

  ```json Ruby theme={null}
  {"ok"=>true}
  ```

  ```json PHP theme={null}
  true
  ```

  ```json C# theme={null}
  {
    "connected_account_id": "6e1cad57-b244-40ca-b4f3-30a46c8000d4",
    "created_at": "2023-12-15T08:03:23.432Z",
    "user_identifier": {
      "email": "jane@example.com"
    },
    ...
    "custom_metadata": {"internal_account_id"=>"user-1"},
    "automatically_manage_new_devices": true
  }
  ```
</CodeGroup>


# Filtering Connected Accounts by Custom Metadata
Source: https://docs.seam.co/core-concepts/connected-accounts/filtering-connected-accounts-by-custom-metadata

When listing connected accounts, you can filter by custom metadata.

When you use [List Connected Accounts](/api/connected_accounts/list), you can filter the list by one or more custom metadata pairs. Include the `custom_metadata_has` parameter with a JSON string that specifies the desired key:value pairs.

<Info>
  If the [Connect Webview](/core-concepts/connect-webviews/index) associated with a connected
  account contains custom metadata, Seam transfers this custom metadata to the
  connected account. However, you can also use the [Update Connected
  Account](/api/connected_accounts/update) method
  with the optional `custom_metadata` property to [change or add custom metadata
  for a connected account](./adding-custom-metadata-to-a-connected-account).
</Info>

**Request:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  const connected_accounts = await seam.connectedAccounts.list({
    custom_metadata_has: {
      internal_account_id: 'user-1',
    },
  })

  console.log(connected_accounts)
  ```

  ```bash cURL theme={null}
  curl -X 'POST' \
    'https://connect.getseam.com/connected_accounts/list' \
    -H 'accept: application/json' \
    -H 'Authorization: Bearer ${API_KEY}' \
    -H 'Content-Type: application/json' \
    -d '{
    "custom_metadata_has": {
      "internal_account_id": "user-1"
    },
  }'
  ```

  ```python Python theme={null}
  connected_accounts = seam.connected_accounts.list(
    custom_metadata_has = {
      "internal_account_id": "user-1"
    }
  )

  pprint(connected_accounts)
  ```

  ```ruby Ruby theme={null}
  connected_accounts = client.connected_accounts.list(
    custom_metadata_has: {
      "internal_account_id": "user-1"
    }
  )

  puts connected_accounts.inspect
  ```

  ```php PHP theme={null}
  $accounts = $seam->connected_accounts->list(
    custom_metadata_has: array('internal_account_id' => 'user-1')
  );

  echo json_encode($accounts);
  ```

  ```csharp C# theme={null}
  var customMetadata = new Dictionary<string, string>()
  {
    {"internal_account_id", "user-1"}
  };

  var connectedAccounts = seam.ConnectedAccounts.List(
    customMetadataHas: customMetadata
  );

  foreach (var connectedAccount in connectedAccounts)
  {
    Console.WriteLine(connectedAccount);
  }
  ```
</CodeGroup>

**Response:**

<CodeGroup>
  ```json JavaScript theme={null}
  [
    {
      connected_account_id: 'c993818b-bf3c-4836-bef4-9a76d89bf1d3',
      created_at: '2024-01-05T07:20:07.692Z',
      user_identifier: { username: 'jane' },
      account_type: 'visionline',
      account_type_display_name: 'Visionline',
      errors: [],
      warnings: [],
      custom_metadata: { internal_account_id: 'user-1' },
      automatically_manage_new_devices: true
    },
    ...
  ]
  ```

  ```json cURL theme={null}
  {
    "connected_accounts": [
      {
        "connected_account_id": "c993818b-bf3c-4836-bef4-9a76d89bf1d3",
        "created_at": "2024-01-05T07:20:07.692Z",
        "user_identifier": {
          "username": "jane"
        },
        "account_type": "visionline",
        "account_type_display_name": "Visionline",
        "errors": [],
        "warnings": [],
        "custom_metadata": {
          "internal_account_id": "user-1"
        },
        "automatically_manage_new_devices": true
      },
      ...
    ],
    "ok": true
  }
  ```

  ```json Python theme={null}
  [ConnectedAccount(connected_account_id='c993818b-bf3c-4836-bef4-9a76d89bf1d3',
                    created_at='2024-01-05T07:20:07.692Z',
                    user_identifier={'username': 'jane'},
                    account_type='visionline',
                    errors=[],
                    custom_metadata={"internal_account_id": "user-1"}),
  ...]
  ```

  ```json Ruby theme={null}
  [<Seam::ConnectedAccount:0x004d8
    connected_account_id="c993818b-bf3c-4836-bef4-9a76d89bf1d3"
    created_at=2024-01-05 07:20:07.692 UTC
    user_identifier={"username"=>"jane"}
    account_type="visionline"
    errors=[]
    warnings=[]
    custom_metadata={"internal_account_id"=>"user-1"}>, ...]
  ```

  ```json PHP theme={null}
  [{"connected_account_id":"c993818b-bf3c-4836-bef4-9a76d89bf1d3","account_type":"visionline","user_identifier":{"username":"jane", "email":null,"phone":null},"errors":[],"warnings":[],"created_at":"2024-01-05T07:20:07.692Z","custom_metadata":{"internal_account_id":"user-1"},"automatically_manage_new_devices":true},...]
  ```

  ```json C# theme={null}
  {
    "connected_account_id": "c993818b-bf3c-4836-bef4-9a76d89bf1d3",
    "created_at": "2024-01-05T07:20:07.692Z",
    "user_identifier": {
      "username": "jane"
    },
    "account_type": "visionline",
    "account_type_display_name": "Visionline",
    "errors": [],
    "warnings": [],
    "custom_metadata": {
      "internal_account_id": "user-1"
    },
    "automatically_manage_new_devices": true
  }
  ...
  ```
</CodeGroup>


# Connected Accounts
Source: https://docs.seam.co/core-concepts/connected-accounts/index

External third-party accounts to which your user has authorized Seam to get access

Once your user uses a [Connect Webview](/core-concepts/connect-webviews/index) to authorize Seam to control their devices, Seam registers this authorized account as a "connected account." For example, a connected account might be an August account with a list of door locks.

A connected account has a unique ID and stores the following data about the user and their account:

* User identifier, such as the username or email address that the user uses to log in to their device account.
* Account type, for example, `schlage`.
* A Boolean `automatically_manage_new_devices` property to indicate whether Seam should import all new devices for the connected account to make these devices available for use and management by the Seam API.\
  Seam sets the initial value for this property based on a [corresponding parameter](/api/connect_webviews/object) in the associated Connect Webview. However, you can use the [Update Connected Account](/api/connected_accounts/update) method to change this value.
* An set of editable custom metadata, such as your own internal ID for the user.\
  This custom metadata is useful for [filtering connected accounts](/core-concepts/connected-accounts/filtering-connected-accounts-by-custom-metadata) using the [List Connected Accounts](/api/connected_accounts/list) method.\
  If the associated Connect Webview contains custom metadata, Seam transfers this custom metadata as the initial value for this property. However, you can use the [Update Connected Account](/api/connected_accounts/update) method to [change or add custom metadata for the connected account](/core-concepts/connected-accounts/adding-custom-metadata-to-a-connected-account).
* The date and time at which Seam created the connected account, that is, when the user completed the Connect Webview to authorize access.
* Any errors or warnings associated with the connected account


# Reconnecting an Account
Source: https://docs.seam.co/core-concepts/connected-accounts/reconnecting-an-account

Learn why an account may become disconnected and how to reconnect it.

An account can become disconnected for many reasons, including the following:

* A user resets their password or clicks **Sign Out of All Devices**, invalidating any access tokens Seam may be using to authenticate to the third-party API.
* The third-party service invalidates access tokens due to excessive usage or as part of a system update.
* An access token used internally by Seam expires.

## Detect a Disconnection

When an account becomes disconnected, Seam emits a `connected_account.disconnected` [event](/api/events/object). Subscribing to this event through a [webhook](/developer-tools/webhooks) is the recommended way to detect a disconnection, because it tells you the moment the account needs attention instead of on your next poll.

<Warning>
  Do not rely on `device.disconnected` for this. That event fires only when a
  device transitions from online to offline, so it does **not** fire when an
  account-level authorization problem is added to a device that was already
  offline. A device can end up in the `account_disconnected` state without any
  further `device.disconnected` event, which means an integration listening only
  for `device.disconnected` will tell the owner "your device is offline" when the
  real problem is "your account needs reconnection." See [Displaying Device
  Health](/core-concepts/devices/displaying-device-health).
</Warning>

Seam also records the disconnection on the `connected_account` itself, so you can inspect the current state at any time. When an account is disconnected, Seam emits an error like the following example on the `connected_account`:

<CodeGroup>
  ```python Python theme={null}
  seam.connected_accounts.get(email_address="jane@example.com")
  # ConnectedAccount(
  #   ...
  #   errors=[
  #     {
  #        error_code: "account_disconnected",
  #        message: "Account Disconnected, you may need to reconnect the account with a new webview..."
  #     }
  #  ]
  # )
  ```
</CodeGroup>

Seam recommends adding error handling logic to you application for this error. Your app should also include a fallback case if it encounters an unknown generic error code.

To resolve this error, create a new Connect Webview that the user can use to log in. You may need to instruct them to use the same email address that they used previously. You can use `connected_account.user_identifier` to learn the user's email address. For more information about creating Connect Webviews, see [Connect Webview Process](../connect-webviews/connect-webview-process).


# Adding Custom Metadata to a Device
Source: https://docs.seam.co/core-concepts/devices/adding-custom-metadata-to-a-device

You can add or change custom metadata for a device.

You can use custom metadata to store a custom payload or object, tailored to the specific needs of your app. For example, this feature is useful for tracking customer information, internal user IDs, or other internal resources for a [device](./). Storing custom metadata in a Seam `device` object enables you to look up an internal resource from directly within your Seam [workspace](/core-concepts/workspaces/index). Then, you can [filter devices by the desired metadata](/core-concepts/devices/filtering-devices-by-custom-metadata).

<Info>
  You can also use unique resource keys as an easy way to link your resources to
  Seam resources. For details, see [Mapping Your Resources to Seam
  Resources](../mapping-your-resources-to-seam-resources).
</Info>

Use the [Update Device](/api/devices/update) method with the optional [`custom_metadata` property](/core-concepts/devices) to change or add custom metadata for the connected account. This property accepts up to 50 JSON key:value pairs.

**Request:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  const deviceUpdate = await seam.devices.update({
    device_id: '30fd243b-3054-4384-a713-5487076a3826',
    custom_metadata: {
      internal_account_id: 'user-1',
    },
  })

  console.log(deviceUpdate)
  ```

  ```bash cURL theme={null}
  curl -X 'POST' \
    'https://connect.getseam.com/devices/update' \
    -H 'accept: application/json' \
    -H 'Authorization: Bearer ${API_KEY}' \
    -H 'Content-Type: application/json' \
    -d '{
    "device_id": "30fd243b-3054-4384-a713-5487076a3826",
    "custom_metadata": {
      "id": "internal_id_1"
    }
  }'
  ```

  ```python Python theme={null}
  device_update = seam.devices.update(
      device = "30fd243b-3054-4384-a713-5487076a3826",
      custom_metadata = {
          "internal_account_id": "user-1"
      }
  )

  pprint(device_update)
  ```

  ```ruby Ruby theme={null}
  device_update = client.devices.update(
    device_id: "30fd243b-3054-4384-a713-5487076a3826",
    custom_metadata: {
      "internal_account_id": "user-1"
    }
  )

  puts device_update.inspect
  ```

  ```php PHP theme={null}
  $device_update = $seam->devices->update(
    device_id: "30fd243b-3054-4384-a713-5487076a3826",
    custom_metadata: array('internal_account_id' => 'user-1')
  )
  echo json_encode($device_update, JSON_PRETTY_PRINT);
  ```

  ```csharp C# theme={null}
  var customMetadata = new Dictionary<string, string>()
  {
    {"internal_account_id", "user-1"}
  };

  var deviceUpdate = seam.Devices.Update(
    deviceId: "30fd243b-3054-4384-a713-5487076a3826",
    customMetadata: customMetadata
  );

  Console.WriteLine(deviceUpdate);
  ```
</CodeGroup>

**Response:**

<CodeGroup>
  ```json JavaScript theme={null}
  { "ok": true }
  ```

  ```json cURL theme={null}
  {
    "ok": true
  }
  ```

  ```json Python theme={null}
  True
  ```

  ```json Ruby theme={null}
  {"ok"=>true}
  ```

  ```json PHP theme={null}
  true
  ```

  ```json C# theme={null}
  {
    "device_id": "30fd243b-3054-4384-a713-5487076a3826",
    "device_type": "schlage_lock",
    ...
    "is_managed": true,
    "custom_metadata": {"internal_account_id"=>"user-1"}
  }
  ```
</CodeGroup>


# Displaying Device Health
Source: https://docs.seam.co/core-concepts/devices/displaying-device-health

You can display the health status of your end users' devices in your app.

<img alt="Display the health status of your end users' devices in your app." />

To display the health—that is, the online/offline status—of your end users' devices in your app, you can use the following Seam mechanisms:

* [Use the `properties.online` property of the `device` object.](#get-device-status-using-device-properties)
* [Use the `device.connected` and `device.disconnected` events.](#get-device-status-using-connection-related-events)

## Get Device Status Using Device Properties

Seam polls connected devices and accounts every ten minutes and updates the Boolean [`device.properties.online`](/core-concepts/devices) property accordingly. Use a [Get Device](/api/devices/get) request to retrieve the current online/offline status of a device. Then, display the device status in your app.

<Info>
  You can also use the prebuilt [device details Seam
  Component](../../ui-components/overview/react-components/device-details),
  which includes a device status display.
</Info>

**Request:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  const device = await seam.devices.get({
    device_id: '36cf1a96-196d-41b0-9804-88154387f1f9',
  })
  console.log('Online:', device.properties.online)
  ```

  ```bash cURL theme={null}
  # 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": "36cf1a96-196d-41b0-9804-88154387f1f9"
  }' | jq -r '"Online: " + (.device.properties.online | tostring)'
  ```

  ```python Python theme={null}
  device = seam.devices.get("36cf1a96-196d-41b0-9804-88154387f1f9")
  pprint("Online: " + str(device.properties.online))
  ```

  ```ruby Ruby theme={null}
  device = client.devices.get(device_id: "36cf1a96-196d-41b0-9804-88154387f1f9")
  puts "Online: " + device.properties.online.to_s
  ```

  ```php PHP theme={null}
  $device = $seam->devices->get(device_id: "36cf1a96-196d-41b0-9804-88154387f1f9");
  if ($device->properties->online === true) {
    echo "Online: true\n";
  } else {
    echo "Online: false\n";
  }
  ```

  ```csharp C# theme={null}
  var device = seam.Devices.Get(deviceId: "36cf1a96-196d-41b0-9804-88154387f1f9");
  Console.WriteLine("Online: " + device.Properties.Online);
  ```
</CodeGroup>

**Response:**

<CodeGroup>
  ```json JavaScript theme={null}
  Online: true
  ```

  ```json cURL theme={null}
  Online: true
  ```

  ```json Python theme={null}
  'Online: True'
  ```

  ```json Ruby theme={null}
  Online: true
  ```

  ```json PHP theme={null}
  Online: true
  ```

  ```json C# theme={null}
  Online: True
  ```
</CodeGroup>

## Get Device Status Using Connection-Related Events

When a device connection or disconnection occurs, Seam generates a [`device.connected`](/api/devices/events#device-connected) or [`device.disconnected`](/api/devices/events#device-disconnected) event, respectively. You can retrieve these events using a [List Events](/api/events/list) request or through [webhooks](../../developer-tools/webhooks) and then display the corresponding status in your app.

<Warning>
  These two events report *transitions*, not the full set of reasons a device
  might be unreachable. `device.disconnected` fires when a device goes from
  online to offline, so it does not fire again when a new problem is added to a
  device that is already offline.

  In particular, if a device is already offline and its connected account then
  loses authorization, Seam adds `account_disconnected` to the device's
  `error_map` without emitting another `device.disconnected` event. An
  integration that treats `device.disconnected` as its only "something is wrong
  with this device" signal will report "your device is offline" when the real
  problem is that the account needs reconnecting.

  To catch account-level problems, also subscribe to
  `connected_account.disconnected`. See [Reconnecting an
  Account](/core-concepts/connected-accounts/reconnecting-an-account).
</Warning>

<Info>
  To help you test your app against events—like device disconnection or
  removal—that are difficult to orchestrate in a QA environment using real
  devices, Seam provides a suite of `simulate` endpoints that you can use in a
  [sandbox workspace](/core-concepts/workspaces/index#sandbox-workspaces). See [Testing Your App
  Against Device Disconnection and
  Removal](/core-concepts/devices/testing-your-app-against-device-disconnection-and-removal).
</Info>

### Get Connection-Related Events Using a List Events Request

When issuing a [List Events](/api/events/list) request to retrieve [`device.connected`](/api/devices/events#device-connected) or [`device.disconnected`](/api/devices/events#device-disconnected) events for a specific device, include the following parameters:

<table>
  <thead>
    <tr>
      <th>Parameter</th>
      <th>Type</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        <code>device\_id</code>
      </td>

      <td>String (UUID)</td>

      <td>
        ID of the device for which you want to retrieve
        <code>device.connected</code> or <code>device.disconnected</code> events
      </td>
    </tr>

    <tr>
      <td>
        <code>event\_type</code>
      </td>

      <td>String</td>

      <td>
        Event type that you want to retrieve, that is,
        <code>device.connected</code> or <code>device.disconnected</code>
      </td>
    </tr>

    <tr>
      <td>
        <code>since</code>
      </td>

      <td>String</td>

      <td>
        Desired starting event generation date and time

        <br />

        You must include <code>since</code> or <code>between</code>.
      </td>
    </tr>

    <tr>
      <td>
        <code>between</code>
      </td>

      <td>Set of two strings</td>

      <td>
        Desired starting and ending event generation dates and times

        <br />

        For example:

        <br />

        <code>\["2024-01-01T00:00:00Z", "2024-02-01T00:00:00Z"]</code>

        <br />

        You must include <code>between</code> or <code>since</code>.
      </td>
    </tr>
  </tbody>
</table>

The following example uses the List Events request to retrieve all `device.connected` events for a specific device since January 1, 2024:

**Request:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  const device_connected_events = await seam.events.list({
    device_id: '36cf1a96-196d-41b0-9804-88154387f1f9',
    event_type: 'device.connected',
    since: '2024-01-01T00:00:00Z',
  })
  console.log(device_connected_events)
  ```

  ```bash cURL theme={null}
  # Use GET or POST.
  curl -X 'GET' \
    'https://connect.getseam.com/events/list' \
    -H 'accept: application/json' \
    -H 'Authorization: Bearer ${API_KEY}' \
    -H 'Content-Type: application/json' \
    -d '{
    "device_id": "36cf1a96-196d-41b0-9804-88154387f1f9",
    "event_type": "device.connected",
    "since": "2024-01-01T00:00:00Z"
  }'
  ```

  ```python Python theme={null}
  device_connected_events = seam.events.list(
      device_id = "36cf1a96-196d-41b0-9804-88154387f1f9",
      event_type = "device.connected",
      since = "2024-01-01T00:00:00Z"
  )
  pprint(device_connected_events)
  ```

  ```ruby Ruby theme={null}
  device_connected_events = client.events.list(
    device_id: "36cf1a96-196d-41b0-9804-88154387f1f9",
    event_type: "device.connected",
    since: "2024-01-01T00:00:00Z"
  )
  puts device_connected_events.inspect
  ```

  ```php PHP theme={null}
  $device_connected_events = $seam->events->list(
    device_id: "36cf1a96-196d-41b0-9804-88154387f1f9",
    event_type: "device.connected",
    since: "2024-01-01T00:00:00Z"
  );
  echo json_encode($device_connected_events), "\n";
  ```

  ```csharp C# theme={null}
  var device_connected_events = seam.Events.List(
      deviceId: "36cf1a96-196d-41b0-9804-88154387f1f9",
      eventType: Seam.Api.Events.ListRequest.EventTypeEnum.DeviceConnected,
      since: "2024-01-01T00:00:00Z"
  );
  foreach (var device_connected_event in device_connected_events)
  {
    Console.WriteLine(device_connected_event);
  }
  ```
</CodeGroup>

**Response:**

<CodeGroup>
  ```json JavaScript theme={null}
  [
    {
      "event_id": "ca3114b2-088d-43f9-bb5e-ded5d19ad053",
      "device_id": "36cf1a96-196d-41b0-9804-88154387f1f9",
      "event_type": "device.connected",
      "workspace_id": "398d80b7-3f96-47c2-b85a-6f8ba21d07be",
      "created_at": "2024-02-04T21:55:09.681Z",
      "occurred_at": "2024-02-04T21:55:09.681Z",
      "connected_account_id": "c1413928-f527-4e12-abf9-d5e18d92dd33"
    },
    {
      "event_id": "39fcb512-82a4-431d-969f-3935eeba8929",
      "device_id": "36cf1a96-196d-41b0-9804-88154387f1f9",
      "event_type": "device.connected",
      "workspace_id": "398d80b7-3f96-47c2-b85a-6f8ba21d07be",
      "created_at": "2024-02-03T04:54:39.744Z",
      "occurred_at": "2024-02-03T04:54:39.744Z",
      "connected_account_id": "c1413928-f527-4e12-abf9-d5e18d92dd33"
    }
  ]
  ```

  ```json cURL theme={null}
  {
    "events": [
      {
        "event_id": "ca3114b2-088d-43f9-bb5e-ded5d19ad053",
        "device_id": "36cf1a96-196d-41b0-9804-88154387f1f9",
        "event_type": "device.connected",
        "workspace_id": "398d80b7-3f96-47c2-b85a-6f8ba21d07be",
        "created_at": "2024-02-04T21:55:09.681Z",
        "occurred_at": "2024-02-04T21:55:09.681Z",
        "connected_account_id": "c1413928-f527-4e12-abf9-d5e18d92dd33"
      },
      {
        "event_id": "39fcb512-82a4-431d-969f-3935eeba8929",
        "device_id": "36cf1a96-196d-41b0-9804-88154387f1f9",
        "event_type": "device.connected",
        "workspace_id": "398d80b7-3f96-47c2-b85a-6f8ba21d07be",
        "created_at": "2024-02-03T04:54:39.744Z",
        "occurred_at": "2024-02-03T04:54:39.744Z",
        "connected_account_id": "c1413928-f527-4e12-abf9-d5e18d92dd33"
      }
    ],
    "ok": true
  }
  ```

  ```json Python theme={null}
  [{'connected_account_id': 'c1413928-f527-4e12-abf9-d5e18d92dd33',
    'created_at': '2024-02-04T21:55:09.681Z',
    'device_id': '36cf1a96-196d-41b0-9804-88154387f1f9',
    'event_id': 'ca3114b2-088d-43f9-bb5e-ded5d19ad053',
    'event_type': 'device.connected',
    'occurred_at': '2024-02-04T21:55:09.681Z',
    'workspace_id': '398d80b7-3f96-47c2-b85a-6f8ba21d07be'},
   {'connected_account_id': 'c1413928-f527-4e12-abf9-d5e18d92dd33',
    'created_at': '2024-02-03T04:54:39.744Z',
    'device_id': '36cf1a96-196d-41b0-9804-88154387f1f9',
    'event_id': '39fcb512-82a4-431d-969f-3935eeba8929',
    'event_type': 'device.connected',
    'occurred_at': '2024-02-03T04:54:39.744Z',
    'workspace_id': '398d80b7-3f96-47c2-b85a-6f8ba21d07be'}]
  ```

  ```json Ruby theme={null}
  [<Seam::Event:0x00438
    event_id="ca3114b2-088d-43f9-bb5e-ded5d19ad053"
    device_id="36cf1a96-196d-41b0-9804-88154387f1f9"
    event_type="device.connected"
    workspace_id="398d80b7-3f96-47c2-b85a-6f8ba21d07be"
    created_at=2024-02-04 21:55:09.681 UTC>, <Seam::Event:0x00460
    event_id="39fcb512-82a4-431d-969f-3935eeba8929"
    device_id="36cf1a96-196d-41b0-9804-88154387f1f9"
    event_type="device.connected"
    workspace_id="398d80b7-3f96-47c2-b85a-6f8ba21d07be"
    created_at=2024-02-03 04:54:39.744 UTC>]
  ```

  ```json PHP theme={null}
  [
    {
      "event_id": "ca3114b2-088d-43f9-bb5e-ded5d19ad053",
      "device_id": "36cf1a96-196d-41b0-9804-88154387f1f9",
      "event_type": "device.connected",
      "workspace_id": "398d80b7-3f96-47c2-b85a-6f8ba21d07be",
      "created_at": "2024-02-04T21:55:09.681Z",
      "occurred_at": "2024-02-04T21:55:09.681Z"
    },
    {
      "event_id": "39fcb512-82a4-431d-969f-3935eeba8929",
      "device_id": "36cf1a96-196d-41b0-9804-88154387f1f9",
      "event_type": "device.connected",
      "workspace_id": "398d80b7-3f96-47c2-b85a-6f8ba21d07be",
      "created_at": "2024-02-03T04:54:39.744Z",
      "occurred_at": "2024-02-03T04:54:39.744Z"
    }
  ]
  ```

  ```json C# theme={null}
  {
    "event_id": "ca3114b2-088d-43f9-bb5e-ded5d19ad053",
    "device_id": "36cf1a96-196d-41b0-9804-88154387f1f9",
    "event_type": "device.connected",
    "workspace_id": "398d80b7-3f96-47c2-b85a-6f8ba21d07be",
    "created_at": "2024-02-04T21:55:09.681Z",
    "occurred_at": "2024-02-04T21:55:09.681Z"
  }
  {
    "event_id": "39fcb512-82a4-431d-969f-3935eeba8929",
    "device_id": "36cf1a96-196d-41b0-9804-88154387f1f9",
    "event_type": "device.connected",
    "workspace_id": "398d80b7-3f96-47c2-b85a-6f8ba21d07be",
    "created_at": "2024-02-03T04:54:39.744Z",
    "occurred_at": "2024-02-03T04:54:39.744Z"
  }
  ```
</CodeGroup>

### Receive Connection-Related Events Using a Webhook

You can set up webhook endpoints to receive `device.connected` and `device.disconnected` events. Then, you can use the receipt of these events to display the corresponding device status in your app. For more information about configuring webhooks, see [Webhooks](../../developer-tools/webhooks).


# Displaying Device Power Status
Source: https://docs.seam.co/core-concepts/devices/displaying-device-power-status

You can display the power status of your end users' devices in your app.

<img alt="Display the power status of your end users' devices in your app." />

You can display the power status of your end users' devices in your app, including whether the device is wired or battery-powered. Further, for battery-powered devices, you can also display information about the battery status, such as the battery charge level and the battery status.

To display this information, use either of the following Seam mechanisms:

* [Use the `properties.has_direct_power`, and `properties.battery` properties of the `device` object.](#get-device-power-status-using-device-properties)
* [Use the `device.low_battery` and `device.battery_status_changed` events.](#get-device-power-status-using-battery-related-events)

## Get Device Power Status Using Device Properties

Seam polls connected devices and accounts every ten minutes and updates the following device properties accordingly:

<table>
  <thead>
    <tr>
      <th>Property</th>
      <th>Type</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        <code>properties.has\_direct\_power</code>
      </td>

      <td>Boolean</td>

      <td>
        Indicates whether the device has direct power, that is, whether the
        device is wired
      </td>
    </tr>

    <tr>
      <td>
        <code>properties.battery</code>
      </td>

      <td>Object</td>

      <td>
        Battery information, including <code>level</code> and
        <code>status</code>

        <br />

        If the device is offline, Seam does not return this property.
      </td>
    </tr>

    <tr>
      <td>
        <code>properties.battery.level</code>
      </td>

      <td>Number (0-1)</td>

      <td>
        Battery level of the device as a decimal value between 0 and 1,
        inclusive

        <br />

        If the device is offline, Seam does not return this property.
      </td>
    </tr>

    <tr>
      <td>
        <code>properties.battery.status</code>
      </td>

      <td>Enum (string)</td>

      <td>
        <p>
          Current status of the battery charge level.

          <br />

          If the device is offline, Seam does not return this property.
        </p>

        <p>Values are:</p>

        <p>
          <code>critical</code>: Indicates an extremely low level, suggesting
          imminent shutdown or an urgent need for charging.
        </p>

        <p>
          <code>low</code>: Signifies that the battery is under the preferred
          threshold and should be charged soon.
        </p>

        <p>
          <code>good</code>: Denotes a satisfactory charge level, adequate for
          normal use without the immediate need for recharging.
        </p>

        <p>
          <code>full</code>: Represents a battery that is fully charged,
          providing the maximum duration of usage.
        </p>
      </td>
    </tr>
  </tbody>
</table>

Use a [Get Device](/api/devices/get) request to retrieve the current power status of a device. First, determine whether the device is wired. If the device is battery-powered (that is, not wired), get the battery level and status. Then, display the retrieved device power status in your app.

<Info>
  You can also use the prebuilt [device details Seam
  Component](../../ui-components/overview/react-components/device-details),
  which includes a device power status display.
</Info>

**Request:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  const device = await seam.devices.get({
    device_id: '36cf1a96-196d-41b0-9804-88154387f1f9',
  })
  if (device.properties.has_direct_power == true) {
    console.log('Power Source: Wired')
  } else {
    console.log('Power Source: Battery-powered')
    console.log('Battery Level: ' + device.properties.battery.level.toString())
    console.log('Battery Status: ' + device.properties.battery.status)
  }
  ```

  ```bash cURL theme={null}
  # 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": "36cf1a96-196d-41b0-9804-88154387f1f9"
  }' | jq -r '"Power Source: " +
    (if .device.properties.has_direct_power == true then "Wired" else "Battery-powered",
    "Battery Level: " + (.device.properties.battery.level | tostring),
    "Battery Status: " + .device.properties.battery.status end)'
  ```

  ```python Python theme={null}
  device = seam.devices.get("36cf1a96-196d-41b0-9804-88154387f1f9")
  if device.properties.has_direct_power == True:
    pprint("Power Source: Wired")
  else:
    pprint("Power Source: Battery-powered")
    pprint("Battery Level: " + str(device.properties.battery.level))
    pprint("Battery Status: " + device.properties.battery.status)
  ```

  ```ruby Ruby theme={null}
  device = client.devices.get(device_id: "36cf1a96-196d-41b0-9804-88154387f1f9")
  if(device.properties.has_direct_power == true)
    puts "Power Source: Wired"
  else
    puts "Power Source: Battery-powered"
    puts "Battery Level: " + device.properties.battery.level.to_s
    puts "Battery Status: " + device.properties.battery.status
  end
  ```

  ```php PHP theme={null}
  $device = $seam->devices->get("36cf1a96-196d-41b0-9804-88154387f1f9");
  if ($device->properties->has_direct_power === true) {
    echo "Power Source: Wired\n";
  } else {
    echo "Power Source: Battery-powered\n";
    // echo "Battery Level: " + $device->properties->battery->level + "\n";
    echo "Battery Level: {$device->properties->battery->level}\n";
    echo "Battery Status: {$device->properties->battery->status}\n";
  }
  ```

  ```csharp C# theme={null}
  var device = seam.Devices.Get(deviceId: "36cf1a96-196d-41b0-9804-88154387f1f9");
  if (device.Properties.HasDirectPower == true)
  {
    Console.WriteLine("Power Source: Wired");
  } else {
    Console.WriteLine("Power Source: Battery-powered");
    if (device.Properties.Battery != null)
    {
      Console.WriteLine("Battery Level: " + device.Properties.Battery.Level);
      Console.WriteLine("Battery Status: " + device.Properties.Battery.Status);
    }
  }
  ```
</CodeGroup>

**Response:**

<CodeGroup>
  ```json JavaScript theme={null}
  Power Source: Battery-powered
  Battery Level: 0.9999532347993827
  Battery Status: full
  ```

  ```json cURL theme={null}
  Power Source: Battery-powered
  Power Source: Battery Level: 0.9999532347993827
  Power Source: Battery Status: full
  ```

  ```json Python theme={null}
  'Power Source: Battery-powered'
  'Battery Level: 0.9999532347993827'
  'Battery Status: full'
  ```

  ```json Ruby theme={null}
  Power Source: Battery-powered
  Battery Level: 0.9999532347993827
  Battery Status: full
  ```

  ```json PHP theme={null}
  Power Source: Battery-powered
  Battery Level: 0.99995323479938
  Battery Status: full
  ```

  ```json C# theme={null}
  Power Source: Battery-powered
  Battery Level: 0.9999532
  Battery Status: Full
  ```
</CodeGroup>

## Get Device Power Status Using Battery-Related Events

Seam generates the following battery-related events:

* `device.low_battery`
* `device.battery_status_changed`

You can retrieve these events using a [List Events](/api/events/list) request or through [webhooks](../../developer-tools/webhooks) and then display the corresponding status in your app.

### Get Battery-Related Events Using a List Events Request

When issuing a [List Events](/api/events/list) request to retrieve [`device.low_battery`](/api/devices/events#device-low_battery) or [`device.battery_status_changed`](/api/devices/events#device-battery_status_changed) events for a specific device, include the following parameters:

<table>
  <thead>
    <tr>
      <th>Parameter</th>
      <th>Type</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        <code>device\_id</code>
      </td>

      <td>String (UUID)</td>

      <td>
        ID of the device for which you want to retrieve
        <code>device.connected</code> or <code>device.disconnected</code> events
      </td>
    </tr>

    <tr>
      <td>
        <code>event\_type</code>
      </td>

      <td>String</td>

      <td>
        Event type that you want to retrieve, that is,
        <code>device.connected</code> or <code>device.disconnected</code>
      </td>
    </tr>

    <tr>
      <td>
        <code>since</code>
      </td>

      <td>String</td>

      <td>
        Desired starting event generation date and time

        <br />

        You must include <code>since</code> or <code>between</code>.
      </td>
    </tr>

    <tr>
      <td>
        <code>between</code>
      </td>

      <td>Set of two strings</td>

      <td>
        Desired starting and ending event generation dates and times

        <br />

        For example:

        <br />

        <code>\["2024-01-01T00:00:00Z", "2024-02-01T00:00:00Z"]</code>

        <br />

        You must include <code>between</code> or <code>since</code>.
      </td>
    </tr>
  </tbody>
</table>

The following example uses the List Events request to retrieve all `device.battery_status_changed` events for a specific device since January 1, 2024:

**Request:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  const device_battery_status_changed_events = await seam.events.list({
    device_id: '36cf1a96-196d-41b0-9804-88154387f1f9',
    event_type: 'device.battery_status_changed',
    since: '2024-01-01T00:00:00Z',
  })
  console.log(device_battery_status_changed_events)
  ```

  ```bash cURL theme={null}
  # Use GET or POST.
  curl -X 'GET' \
    'https://connect.getseam.com/devices/list' \
    -H 'accept: application/json' \
    -H 'Authorization: Bearer ${API_KEY}' \
    -H 'Content-Type: application/json' \
    -d '{
    "device_id": "36cf1a96-196d-41b0-9804-88154387f1f9",
    "event_type": "device.battery_status_changed",
    "since": "2024-01-01T00:00:00Z"
  }'
  ```

  ```python Python theme={null}
  device_battery_status_changed_events = seam.events.list(
      device_id = "36cf1a96-196d-41b0-9804-88154387f1f9",
      event_type = "device.battery_status_changed",
      since = "2024-01-01T00:00:00Z"
  )
  pprint(device_battery_status_changed_events)
  ```

  ```ruby Ruby theme={null}
  device_battery_status_changed_events = client.events.list(
    device_id: "36cf1a96-196d-41b0-9804-88154387f1f9",
    event_type: "device.battery_status_changed",
    since: "2024-01-01T00:00:00Z"
  )
  puts device_battery_status_changed_events.inspect
  ```

  ```php PHP theme={null}
  $device_battery_status_changed_events = $seam->events->list(
    device_id: "36cf1a96-196d-41b0-9804-88154387f1f9",
    event_type: "device.battery_status_changed",
    since: "2024-01-01T00:00:00Z"
  );
  echo json_encode($device_battery_status_changed_events), "\n";
  ```

  ```csharp C# theme={null}
  var device_battery_status_changed_events = seam.Events.List(
      deviceId: "36cf1a96-196d-41b0-9804-88154387f1f9",
      eventType: Seam.Api.Events.ListRequest.EventTypeEnum.DeviceBatteryStatusChanged,
      since: "2024-01-01T00:00:00Z"
  );
  foreach (var device_battery_status_changed_event in device_battery_status_changed_events)
  {
    Console.WriteLine(device_battery_status_changed_event);
  }
  ```
</CodeGroup>

**Response:**

<CodeGroup>
  ```json JavaScript theme={null}
  [
    {
      "event_id": "de4314a2-903d-53e9-bb5e-ded5d19ad074",
      "device_id": "36cf1a96-196d-41b0-9804-88154387f1f9",
      "event_type": "device.battery_status_changed",
      "workspace_id": "398d80b7-3f96-47c2-b85a-6f8ba21d07be",
      "created_at": "2024-01-01T02:25:10.158Z",
      "occurred_at": "2024-01-01T02:25:10.158Z",
      "connected_account_id": "c1413928-f527-4e12-abf9-d5e18d92dd33"
    }
  ]
  ```

  ```json cURL theme={null}
  {
    "events": [
      {
        "event_id": "de4314a2-903d-53e9-bb5e-ded5d19ad074",
        "device_id": "36cf1a96-196d-41b0-9804-88154387f1f9",
        "event_type": "device.battery_status_changed",
        "workspace_id": "398d80b7-3f96-47c2-b85a-6f8ba21d07be",
        "created_at": "2024-01-01T02:25:10.158Z",
        "occurred_at": "2024-01-01T02:25:10.158Z",
        "connected_account_id": "c1413928-f527-4e12-abf9-d5e18d92dd33"
      }
    ],
    "ok": true
  }
  ```

  ```json Python theme={null}
  [{'connected_account_id': 'c1413928-f527-4e12-abf9-d5e18d92dd33',
    'created_at': '2024-01-01T02:25:10.158Z',
    'device_id': '36cf1a96-196d-41b0-9804-88154387f1f9',
    'event_id': 'de4314a2-903d-53e9-bb5e-ded5d19ad074',
    'event_type': 'device.battery_status_changed',
    'occurred_at': '2024-01-01T02:25:10.158Z',
    'workspace_id': '398d80b7-3f96-47c2-b85a-6f8ba21d07be'}]
  ```

  ```json Ruby theme={null}
  [<Seam::Event:0x00438
    event_id="de4314a2-903d-53e9-bb5e-ded5d19ad074"
    device_id="36cf1a96-196d-41b0-9804-88154387f1f9"
    event_type="device.battery_status_changed"
    workspace_id="398d80b7-3f96-47c2-b85a-6f8ba21d07be"
    created_at=2024-01-01 02:25:10.158Z]
  ```

  ```json PHP theme={null}
  [
    {
      "event_id": "de4314a2-903d-53e9-bb5e-ded5d19ad074",
      "device_id": "36cf1a96-196d-41b0-9804-88154387f1f9",
      "event_type": "device.battery_status_changed",
      "workspace_id": "398d80b7-3f96-47c2-b85a-6f8ba21d07be",
      "created_at": "2024-01-01T02:25:10.158Z",
      "occurred_at": "2024-01-01T02:25:10.158Z"
    }
  ]
  ```

  ```json C# theme={null}
  {
    "event_id": "de4314a2-903d-53e9-bb5e-ded5d19ad074",
    "device_id": "36cf1a96-196d-41b0-9804-88154387f1f9",
    "event_type": "device.battery_status_changed",
    "workspace_id": "398d80b7-3f96-47c2-b85a-6f8ba21d07be",
    "created_at": "2024-01-01T02:25:10.158Z",
    "occurred_at": "2024-01-01T02:25:10.158Z"
  }
  ```
</CodeGroup>

### Retrieve Battery-Related Events Using a Webhook

You can set up webhook endpoints to receive `device.battery_status_changed` and `device.low_battery` events. Then, you can use the receipt of these events to display the corresponding device status in your app. For more information about configuring webhooks, see [Webhooks](../../developer-tools/webhooks).


# Filtering Devices by Custom Metadata
Source: https://docs.seam.co/core-concepts/devices/filtering-devices-by-custom-metadata

When listing devices, you can filter by custom metadata.

When you use [List Devices](/api/devices/list), you can filter the list by one or more [custom metadata](/core-concepts/devices) pairs. Include the `custom_metadata_has` parameter with a JSON string that specifies the desired key:value pairs.

<Info>
  You can use the [Update Connected
  Account](/api/connected_accounts/update) method
  with the optional `custom_metadata` property to [add custom metadata for a
  device](/core-concepts/devices/adding-custom-metadata-to-a-device).
</Info>

**Request:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  const devices = await seam.devices.list({
    custom_metadata_has: {
      internal_account_id: 'user-1',
    },
  })

  console.log(devices)
  ```

  ```bash cURL theme={null}
  curl -X 'POST' \
    'https://connect.getseam.com/devices/list' \
    -H 'accept: application/json' \
    -H 'Authorization: Bearer ${API_KEY}' \
    -H 'Content-Type: application/json' \
    -d '{
    "custom_metadata_has": {
      "internal_account_id": "user-1"
    },
  }'
  ```

  ```python Python theme={null}
  devices = seam.devices.list(
    custom_metadata_has = {
      "internal_account_id": "user-1"
    }
  )

  pprint(devices)
  ```

  ```ruby Ruby theme={null}
  devices = client.devices.list(
    custom_metadata_has: {
      "internal_account_id": "user-1"
    }
  )

  puts devices.inspect
  ```

  ```php PHP theme={null}
  $devices = $seam->devices->list(
    custom_metadata_has: array('internal_account_id' => 'user-1')
  );

  echo json_encode($devices);
  ```

  ```csharp C# theme={null}
  var customMetadata = new Dictionary<string, string>()
  {
    {"internal_account_id", "user-1"}
  };

  var devices = seam.Devices.List(
    customMetadataHas: customMetadata
  );

  foreach (var device in devices)
  {
    Console.WriteLine(device);
  }
  ```
</CodeGroup>

**Response:**

<CodeGroup>
  ```json JavaScript theme={null}
  [
    {
      device_id: 'f7a7fb02-9277-4354-8dd1-28e2d016a7a9',
      device_type: 'schlage_lock',
      ...
      is_managed: true,
      custom_metadata: { internal_account_id: 'user-1' }
    },
    ...
  ]
  ```

  ```json cURL theme={null}
  {
    "devices": [
      {
        "device_id": "f7a7fb02-9277-4354-8dd1-28e2d016a7a9",
        "device_type": "schlage_lock",
        ...
        "is_managed": true,
        "custom_metadata": {
          "internal_account_id": "user-1"
        }
      }
    ],
    "ok": true
  }
  ```

  ```json Python theme={null}
  [Device(device_id='f7a7fb02-9277-4354-8dd1-28e2d016a7a9',
          device_type='schlage_lock',
          ...
          is_managed=True,
          custom_metadata={"internal_account_id": "user-1"}),
  ...]
  ```

  ```json Ruby theme={null}
  [<Seam::Device:0x004d8
    device_id="f7a7fb02-9277-4354-8dd1-28e2d016a7a9"
    device_type="schlage_lock"
    ...
    is_managed=true
    custom_metadata={"internal_account_id"=>"user-1"}>, ...]
  ```

  ```json PHP theme={null}
  [{"device_id":"f7a7fb02-9277-4354-8dd1-28e2d016a7a9","device_type":"schlage_lock",..."is_managed":true,"custom_metadata":{"internal_account_id":"user-1"}},...]
  ```

  ```json C# theme={null}
  {
    "device_id": "f7a7fb02-9277-4354-8dd1-28e2d016a7a9",
    "device_type": "schlage_lock",
    ...
    "is_managed": true,
    "custom_metadata": {
      "internal_account_id": "user-1"
    }
  }
  ...
  ```
</CodeGroup>


# Handling Device Errors
Source: https://docs.seam.co/core-concepts/devices/handling-device-errors

Learn the device errors for which you should add handling to your app.

Seam provides both generic and more specific device errors. We recommend that you add error handling logic to your app for each of the following generic errors:

<table>
  <thead>
    <tr>
      <th>Error Type</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        <code>device\_disconnected</code>
      </td>

      <td>Device is disconnected.</td>
    </tr>

    <tr>
      <td>
        <code>device\_removed</code>
      </td>

      <td>
        Device has been removed from the connected account. Seam can no longer
        sync with this device.
      </td>
    </tr>

    <tr>
      <td>
        <code>hub\_disconnected</code>
      </td>

      <td>
        Hub to which the device is connected is offline. Seam is unable to sync
        updates to this device.
      </td>
    </tr>
  </tbody>
</table>

Your app should also include a fallback case if it encounters an unknown generic error code.

When Seam is able to provide more specific information beyond one of the generic errors, your app can display additional context or suggest provider-specific resolutions.

<Info>
  If the connected account associated with a device has an error, it is attached
  to the device alongside any other device errors. Treat these errors as
  specific errors.
</Info>


# Devices
Source: https://docs.seam.co/core-concepts/devices/index

Devices are objects like locks, thermostats, or sensors. In the Seam API, devices have capabilities that describe the functions that they can perform, as well as online and managed status.

Seam decomposes the ensemble of features that a device provides into one or more capabilities, such as the capability to perform a remote unlock or the capability to program online access codes.

For detailed information about capabilities, see [Device and System Capabilities](../../capability-guides/device-and-system-capabilities).

Seam exposes each capability as a set of APIs that are standardized across brands for ease of integration. For example, an unlock action on a door lock always requires the same API call, regardless of the device brand.

<img alt="" />

In addition, Seam provides the following three sets of device-related features:

* **Actions:** Commands that you can issue to the device, such as unlock. For more information, see the [Capability Guides](../../capability-guides/device-and-system-capabilities).
* **Properties:** The current state of the device, such as the locked, online, and managed statuses. For details, see [`device` Properties](/core-concepts/devices).
* **Events:** Notifications related to changes in the state of the device, such as an unlocking operation performed with an access code. For details, see [Events](/api/devices/events).\
  To help you test your app against events—like device disconnection or removal—that are difficult to orchestrate in a QA environment using real devices, Seam provides a suite of `simulate` endpoints that you can use in a [sandbox workspace](/core-concepts/workspaces/index#sandbox-workspaces). See [Testing Your App Against Device Disconnection and Removal](/core-concepts/devices/testing-your-app-against-device-disconnection-and-removal).


# Managed and Unmanaged Devices
Source: https://docs.seam.co/core-concepts/devices/managed-and-unmanaged-devices

You can indicate the devices in your workspace that you intend to control using the Seam API.

To increase billing flexibility, Seam provides the ability to mark devices as `managed` or `unmanaged`.

* **Managed devices:** These devices can be controlled fully through the Seam API and are billed to your Seam account as a regular device.
* **Unmanaged devices:** These devices are not billed and, consequently, cannot be controlled through the Seam API.

Seam makes it possible to switch a device back and forth between the `managed` and `unmanaged` states.

<Info>
  To keep your own tally of managed devices up to date as they are added,
  converted, and deleted, see [Tracking a Device Count from
  Webhooks](/developer-tools/webhooks#tracking-a-device-count-from-webhooks).
</Info>

## Convert a Managed Device to Unmanaged

When you convert a device to an `unmanaged` state (that is, "unamange a device"), Seam pauses billing for the device and converts all the managed device resources (for example, access codes) to unmanaged resources. As a result, Seam no longer monitors the lifecycle of these unmanaged resources.

<CodeGroup>
  ```javascript JavaScript theme={null}
  const deviceId = '77208078-6dd7-44e5-a3e4-a2ed3a34efc9'

  // Take a managed device.
  const device = await seam.devices.get({
    device_id: deviceId,
  })

  // Set the managed status to false.
  const updatedDevice = await seam.devices.update({
    device_id: deviceId,
    is_managed: false,
  })

  // Retrieve the unmanaged device.
  const unmanagedDevice = await seam.devices.unmanaged.get({
    device_id: deviceId,
  })

  console.log(unmanagedDevice)

  /*
  {
    is_managed: false,
    device_id: '77208078-6dd7-44e5-a3e4-a2ed3a34efc9',
    device_type: 'yale_lock',
    connected_account_id: '4e5acceb-2bda-4dc1-814e-39c998431683',
    capabilities_supported: [ 'access_code', 'lock' ],
    workspace_id: '1d2826eb-4a26-4f46-bddb-ef5898baa859',
    created_at: '2023-08-29T04:30:14.914Z',
    errors: [],
    warnings: [],
    properties: {
      name: 'FRONT DOOR',
      online: true,
      manufacturer: 'august',
      image_url: 'https://connect.getseam.com/assets/images/devices/yale_assure-lock-touchscreen-wifi-smart-lock_satin-nickel_front.png',
      image_alt_text: 'Yale Assure Touchscreen Wifi Smart Lock, Satin Nickel, Front',
      model: { display_name: 'Lock', manufacturer_display_name: 'August' }
    }
  }
  */
  ```

  ```python Python theme={null}
  from seam import Seam
  seam = Seam()

  device_id = "aaa5664a-a959-499d-82a7-c25516565788"

  seam.devices.update(
    device=device_id,
    is_managed=False
  )

  unmanaged_device = seam.devices.unmanaged.get(device=device_id)
  print(unmanaged_device)

  # UnmanagedDevice(device_id='aaa5664a-a959-499d-82a7-c25516565788',
  #                 device_type='august_lock',
  #                 properties={'image_alt_text': 'August Wifi Smart Lock 3rd Gen, '
  #                                               'Silver, Front',
  #                             'image_url': 'https://connect.getseam.com/assets/images/devices/august_wifi-smart-lock-3rd-gen_silver_front.png',
  #                             'manufacturer': 'august',
  #                             'model': {'display_name': 'Lock',
  #                                       'manufacturer_display_name': 'August'},
  #                             'name': 'GARAGE',
  #                             'online': True},
  #                 connected_account_id='4fd987a7-21e1-4b01-aa6a-eedfe35c05e3',
  #                 workspace_id='1d2826eb-4a26-4f46-bddb-ef5898baa859',
  #                 created_at='2023-09-16T20:01:58.984Z',
  #                 errors=[],
  #                 warnings=[],
  #                 capabilities_supported=['access_code', 'lock'],
  #                 is_managed=False)
  ```

  ```ruby Ruby theme={null}
  require "seam"

  seam = Seam.new()
  device_id = "aa3958c3-4236-4f71-bd77-3b60f85b3456"

  seam.devices.update(device_id: device_id, is_managed: false)
  unmanaged_device = seam.unmanaged_devices.get(device_id: device_id)
  puts unmanaged_device.inspect

  # <Seam::UnmanagedDevice:0x00438
  #   is_managed=false
  #   device_id="aa3958c3-4236-4f71-bd77-3b60f85b3456"
  #   device_type="yale_lock"
  #   connected_account_id="d2ab9339-d0ad-4594-b9a2-6ce71e4d4521"
  #   capabilities_supported=["access_code", "lock"]
  #   workspace_id="1d2826eb-4a26-4f46-bddb-ef5898baa859"
  #   created_at=2023-08-30 05:33:58.45 UTC
  #   errors=[]
  #   warnings=[]
  #   properties={"name"=>"FRONT DOOR", "online"=>true, "manufacturer"=>"august", "image_url"=>"https://connect.getseam.com/assets/images/devices/yale_assure-lock-touchscreen-wifi-smart-lock_satin-nickel_front.png", "image_alt_text"=>"Yale Assure Touchscreen Wifi Smart Lock, Satin Nickel, Front", "model"=>{"display_name"=>"Lock", "manufacturer_display_name"=>"August"}}>
  ```

  ```php PHP theme={null}
  use Seam\SeamClient;

  $seam = new SeamClient("YOUR_API_KEY");

  $device_id = "0e2e6262-7f91-4970-a58d-47ef30b41e2e";
  $device = $seam->devices->get($device_id);

  $seam->devices->update(
      device_id: $device_id,
      is_managed: false);

  $unmanaged_device = $seam->devices->unmanaged->get(
      device_id: $device_id
  );

  # Inspect this device to confirm it's unmanaged
  echo json_encode($unmanaged_device, JSON_PRETTY_PRINT);

  // {
  //     "device_id": "0e2e6262-7f91-4970-a58d-47ef30b41e2e",
  //     "device_type": "nuki_lock",
  //     "connected_account_id": "5fe50f46-274f-4a03-ba95-3a517464fdc7",
  //     "workspace_id": "1d2826eb-4a26-4f46-bddb-ef5898baa859",
  //     "created_at": "2023-08-30T06:45:59.213Z",
  //     "properties": {
  //         "name": "Office Lock",
  //         "manufacturer": "nuki",
  //         "image_url": "https:\/\/connect.getseam.com\/assets\/images\/devices\/nuki_smart_lock_3_pro_black.png",
  //         "image_alt_text": "Nuki Smart Lock 3.0 Pro Black, Front",
  //         "model": {
  //             "display_name": "Lock",
  //             "manufacturer_display_name": "Nuki"
  //         }
  //     },
  //     "errors": [],
  //     "warnings": []
  // }
  ```
</CodeGroup>

## Convert an Unmanaged Device to Managed

To convert an unmanaged device back to managed (that is, to "manage a device"), retrieve the device using the unmanaged device API and use the `update` function to change the managed state of the device back to `true`. Note that you must also convert unmanaged device resources (for example, access codes) back to managed.

<CodeGroup>
  ```javascript JavaScript theme={null}
  const deviceId = "77208078-6dd7-44e5-a3e4-a2ed3a34efc9"

  // Retrieve the unmanaged device if needed.
  const unmanagedDevice = await seam.devices.unmanaged.get({
  device_id: deviceId
  })

  // Update the device.
  await seam.devices.unmanaged.update({
  device_id: deviceId,
  is_managed: true
  })

  // Retrieve the device again.
  const device = await seam.devices.get({
  device_id: deviceId
  })

  console.log(device)
  /_
  {
  device_id: '77208078-6dd7-44e5-a3e4-a2ed3a34efc9',
  device_type: 'yale_lock',
  capabilities_supported: [ 'access_code', 'lock' ],
  properties: {
  locked: true,
  online: true,
  door_open: false,
  manufacturer: 'august',
  battery_level: 0.9999532347993827,
  serial_number: '00000004-992d-45a0-bea1-9128fdcd8d12',
  august_metadata: {
  lock_id: 'lock-1',
  house_id: 'house-1',
  lock_name: 'FRONT DOOR',
  has_keypad: true,
  house_name: 'My House',
  keypad_battery_level: 'Not Available'
  },
  supported_code_lengths: [ 4, 5, 6, 7, 8 ],
  has_native_entry_events: true,
  name: 'FRONT DOOR',
  model: { display_name: 'Lock', manufacturer_display_name: 'August' },
  battery: { level: 0.9999532347993827, status: 'full' },
  image_url: 'https://connect.getseam.com/assets/images/devices/yale_assure-lock-touchscreen-wifi-smart-lock_satin-nickel_front.png',
  image_alt_text: 'Yale Assure Touchscreen Wifi Smart Lock, Satin Nickel, Front',
  code_constraints: [],
  supports_backup_access_code_pool: true
  },
  location: { timezone: 'America/Los_Angeles', location_name: 'My House' },
  connected_account_id: '4e5acceb-2bda-4dc1-814e-39c998431683',
  workspace_id: '1d2826eb-4a26-4f46-bddb-ef5898baa859',
  created_at: '2023-08-29T04:30:14.914Z',
  errors: [],
  warnings: [],
  is_managed: true
  }
  _/

  ```

  ```python Python theme={null}
  from seam import Seam
  seam = Seam()

  device_id = "0e2e6262-7f91-4970-a58d-47ef30b41e2e"

  # Use the unmanaged update call to update the status of the device.
  seam.devices.unmanaged.update(
    device=device_id,
    is_managed=True
  )

  # Confirm that the device is now managed by retrieving it.
  device = seam.devices.get(device=device_id)
  print(device)

  # Device(device_id='0e2e6262-7f91-4970-a58d-47ef30b41e2e',
  #        device_type='nuki_lock',
  #        location=None,
  #        properties={'battery': {'level': 0.86, 'status': 'full'},
  #                    'battery_level': 0.86,
  #                    'code_constraints': [{'constraint_type': 'cannot_start_with_12'},
  #                                         {'constraint_type': 'no_zeros'},
  #                                         {'constraint_type': 'name_length',
  #                                          'max_length': 20}],
  #                    'has_native_entry_events': True,
  #                    'image_alt_text': 'Nuki Smart Lock 3.0 Pro Black, Front',
  #                    'image_url': 'https://connect.getseam.com/assets/images/devices/nuki_smart_lock_3_pro_black.png',
  #                    'keypad_battery': {'level': 1},
  #                    'locked': False,
  #                    'manufacturer': 'nuki',
  #                    'model': {'display_name': 'Lock',
  #                              'manufacturer_display_name': 'Nuki'},
  #                    'name': 'Office Lock',
  #                    'nuki_metadata': {'device_id': '545636389',
  #                                      'device_name': 'Office Lock',
  #                                      'keypad_battery_critical': False},
  #                    'online': True,
  #                    'supported_code_lengths': [6],
  #                    'supports_backup_access_code_pool': True},
  #        capabilities_supported=['access_code', 'lock'],
  #        errors=[],
  #        warnings=[],
  #        connected_account_id='5fe50f46-274f-4a03-ba95-3a517464fdc7',
  #        workspace_id='1d2826eb-4a26-4f46-bddb-ef5898baa859',
  #        created_at='2023-08-30T06:45:59.213Z')
  ```

  ```ruby Ruby theme={null}
  require "seam"

  seam = Seam.new()
  device_id = "aa3958c3-4236-4f71-bd77-3b60f85b3456"
  seam.unmanaged_devices.update(device_id: device_id, is_managed: true)

  device = seam.devices.get(device_id: device_id)

  puts device.inspect

  # <Seam::Device:0x00438

  # device_id="aa3958c3-4236-4f71-bd77-3b60f85b3456"

  # device_type="yale_lock"

  # capabilities_supported=["access_code", "lock"]

  # properties={"locked"=>true, "online"=>true, "door_open"=>false, "manufacturer"=>"august", "battery_level"=>0.9999532347993827, "serial_number"=>"00000004-992d-45a0-bea1-9128fdcd8d12", "august_metadata"=>{"lock_id"=>"lock-1", "house_id"=>"house-1", "lock_name"=>"FRONT DOOR", "has_keypad"=>true, "house_name"=>"My House", "keypad_battery_level"=>"Not Available"}, "supported_code_lengths"=>[4, 5, 6, 7, 8], "has_native_entry_events"=>true, "name"=>"FRONT DOOR", "model"=>{"display_name"=>"Lock", "manufacturer_display_name"=>"August"}, "battery"=>{"level"=>0.9999532347993827, "status"=>"full"}, "image_url"=>"https://connect.getseam.com/assets/images/devices/yale_assure-lock-touchscreen-wifi-smart-lock_satin-nickel_front.png", "image_alt_text"=>"Yale Assure Touchscreen Wifi Smart Lock, Satin Nickel, Front", "code_constraints"=>[], "supports_backup_access_code_pool"=>true}

  # connected_account_id="d2ab9339-d0ad-4594-b9a2-6ce71e4d4521"

  # workspace_id="1d2826eb-4a26-4f46-bddb-ef5898baa859"

  # created_at=2023-08-30 05:33:58.45 UTC

  # errors=[]

  # warnings=[]

  # is_managed=true>

  ```

  ```php PHP theme={null}
  use Seam\SeamClient;

  $seam = new SeamClient("YOUR_API_KEY");

  $device_id = "0e2e6262-7f91-4970-a58d-47ef30b41e2e";

  $seam->devices->unmanaged->update(
    device_id: $device_id,
    is_managed: true
  );

  $device = $seam->devices->get($device_id);

  # Inspect this device to make sure that it was converted correctly to managed.
  echo json_encode($device, JSON_PRETTY_PRINT);

  // {
  //     "device_id": "0e2e6262-7f91-4970-a58d-47ef30b41e2e",
  //     "workspace_id": "1d2826eb-4a26-4f46-bddb-ef5898baa859",
  //     "connected_account_id": "5fe50f46-274f-4a03-ba95-3a517464fdc7",
  //     "device_type": "nuki_lock",
  //     "properties": {
  //         "online": true,
  //         "locked": false,
  //         "name": "Office Lock",
  //         "battery_level": 0.86,
  //         "battery": {
  //             "level": 0.86,
  //             "status": "full"
  //         },
  //         "manufacturer": "nuki",
  //         "supported_code_lengths": [
  //             6
  //         ],
  //         "code_constraints": [
  //             {
  //                 "constraint_type": "cannot_start_with_12"
  //             },
  //             {
  //                 "constraint_type": "no_zeros"
  //             },
  //             {
  //                 "constraint_type": "name_length",
  //                 "max_length": 20
  //             }
  //         ],
  //         "model": {
  //             "display_name": "Lock",
  //             "manufacturer_display_name": "Nuki"
  //         },
  //         "image_url": "https:\/\/connect.getseam.com\/assets\/images\/devices\/nuki_smart_lock_3_pro_black.png",
  //         "image_alt_text": "Nuki Smart Lock 3.0 Pro Black, Front",
  //         "nuki_metadata": {
  //             "device_id": "545636389",
  //             "device_name": "Office Lock",
  //             "keypad_battery_critical": false
  //         }
  //     },
  //     "location": null,
  //     "created_at": "2023-08-30T06:45:59.213Z",
  //     "capabilities_supported": [
  //         "access_code",
  //         "lock"
  //     ],
  //     "errors": [],
  //     "warnings": []
  // }
  ```
</CodeGroup>

## Automatically Set New Devices to Unmanaged

You can configure a [Connect Webview](/core-concepts/connect-webviews/index) so that it automatically sets all new devices added to the workspace through this Connect Webview to `unmanaged` by default. To do so, when creating a Connect Webview, set `automatically_manage_new_devices` to `false`. Once the Connect Webview is authorized, Seam sets any device added to the workspace to `unmanaged`.

<CodeGroup>
  ```javascript JavaScript theme={null}
  const connectWebview = await seam.connectWebviews.create({
      provider_category: "stable",
      automatically_manage_new_devices: false
  })

  console.log(connectWebview)

  /_
  {
  url: 'https://connect.getseam.com/connect_webviews/view?connect_webview_id=323b4ffa-ce24-4cff-a965-ff532563ec7a&auth_token=JrunXm29x7GCWFrVJsZHLFsD5YAioyaAu',
  status: 'pending',
  workspace_id: '1d2826eb-4a26-4f46-bddb-ef5898baa859',
  custom_metadata: {},
  accepted_devices: [],
  login_successful: false,
  'august', 'avigilon_alta',
  'schlage', 'smartthings',
  'yale', 'nuki',
  'salto', 'controlbyweb',
  'minut', 'my_2n',
  'kwikset', 'ttlock',
  'noiseaware', 'igloohome',
  'ecobee', 'four_suites',
  'wyze'
  ],
  any_device_allowed: false,
  connect_webview_id: '323b4ffa-ce24-4cff-a965-ff532563ec7a',
  custom_redirect_url: null,
  any_provider_allowed: false,
  device_selection_mode: 'none',
  wait_for_device_creation: false,
  custom_redirect_failure_url: null,
  automatically_manage_new_devices: false,
  created_at: '2023-08-29T04:59:13.890Z'
  }
  _/

  ```
</CodeGroup>

```
```


# Testing Your App Against Device Disconnection and Removal
Source: https://docs.seam.co/core-concepts/devices/testing-your-app-against-device-disconnection-and-removal

Learn how to use the Seam suite of simulate endpoints to test your app against events that are difficult to orchestrate in your quality assurance environment.

When developing an app to control IoT devices—before moving to production—it is imperative to test your app against events like device disconnection and removal. However, it can be difficult to orchestrate these events in your quality assurance (QA) environment using real devices. To help you test your app more easily and effectively, Seam provides the following suite of `simulate` endpoints that you can use in a [sandbox workspace](/core-concepts/workspaces/index#sandbox-workspaces):

* [`/devices/simulate/disconnect`](#simulate-disconnecting-a-device)
* [`/devices/simulate/connect`](#simulate-connecting-a-device)
* [`/devices/simulate/remove`](#simulate-removing-a-device)

<Info>
  Currently, Seam supports these endpoints for
  [August](/device-and-system-integration-guides/august-locks/august-locks-sample-data)
  and
  [Yale](/device-and-system-integration-guides/yale-locks/yale-sample-data)
  sandbox devices.
</Info>

***

## Simulation Capability Flags

The Seam API provides the following sandbox-only [capability flags](../../capability-guides/device-and-system-capabilities#capability-flags) that show you which simulate endpoints you can currently use on a device:

* `device.can_simulate_disconnection`
* `device.can_simulate_connection`
* `device.can_simulate_removal`

***

## Simulate Disconnecting a Device

To simulate a device disconnection:

**Code:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  // Get the device.
  const device = await seam.devices.get({
    device_id: '11111111-1111-1111-1111-444444444444',
  })

  // Confirm that Seam supports simulated disconnection for the device.
  if (device.can_simulate_disconnection) {
    // Perform the simulated disconnection.
    await seam.devices.simulate.disconnect({
      device_id: device.device_id,
    })
  }
  ```

  ```bash cURL theme={null}
  # Get the device.
  device=$(
    # Use GET or POST.
    curl -X 'GET' \
      'https://connect.getseam.com/devices/get' \
      -H 'accept: application/json' \
      -H "Authorization: Bearer ${SEAM_API_KEY}" \
      -H 'Content-Type: application/json' \
      -d '{
        "device_id": "11111111-1111-1111-1111-444444444444"
    }')

  # Confirm that Seam supports simulated disconnection for the device.
  if  $(jq -r '.device.can_simulate_disconnection' <<< ${device}); then \
    # Perform the simulated disconnection.
    curl -X 'POST' \
      'https://connect.getseam.com/devices/simulate/disconnect' \
      -H 'accept: application/json' \
      -H "Authorization: Bearer ${SEAM_API_KEY}" \
      -H 'Content-Type: application/json' \
      -d "{
        \"device_id\": \"$(jq -r '.device.device_id' <<< ${device})\"
    }";
  fi
  ```

  ```python Python theme={null}
  # Get the device.
  device = seam.devices.get(
    device_id="11111111-1111-1111-1111-444444444444"
  )

  # Confirm that Seam supports simulated disconnection for the device.
  if device.can_simulate_disconnection:
    # Perform the simulated disconnection.
    seam.devices.simulate.disconnect(device_id=device.device_id)
  ```

  ```ruby Ruby theme={null}
  # Get the device.
  device = client.devices.get(device_id: "11111111-1111-1111-1111-444444444444")

  # Confirm that Seam supports simulated disconnection for the device.
  if (device.can_simulate_disconnection)
    # Perform the simulated disconnection.
    client.devices.simulate.disconnect(device_id: device.device_id)
  end
  ```

  ```php PHP theme={null}
  // Get the device.
  $device = $seam->devices->get(device_id: "11111111-1111-1111-1111-444444444444");

  // Confirm that Seam supports simulated disconnection for the device.
  if ($device->can_simulate_disconnection) {
    // Perform the simulated disconnection.
    $seam->devices->simulate->disconnect(device_id: $device->device_id);
  }
  ```

  ```csharp C# theme={null}
  // Get the device.
  Device device = seam.Devices.Get(deviceId: "11111111-1111-1111-1111-444444444444");

  // Confirm that Seam supports simulated disconnection for the device.
  if (device.CanSimulateDisconnection == true) {
    // Perform the simulated disconnection.
    seam.Devices.Simulate.Disconnect(deviceId: device.DeviceId);
  }
  ```
</CodeGroup>

**Output:**

<CodeGroup>
  ```json JavaScript theme={null}
  void
  ```

  ```json cURL theme={null}
  {
    "ok": true
  }
  ```

  ```json Python theme={null}
  None
  ```

  ```json Ruby theme={null}
  nil
  ```

  ```json PHP theme={null}
  void
  ```

  ```json C# theme={null}
  void
  ```
</CodeGroup>

***

## Simulate Connecting a Device

To simulate a device connection:

**Code:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  // Get the device.
  const device = await seam.devices.get({
    device_id: '11111111-1111-1111-1111-444444444444',
  })

  // Confirm that Seam supports simulated connection for the device.
  if (device.can_simulate_connection) {
    // Perform the simulated connection.
    await seam.devices.simulate.connect({
      device_id: device.device_id,
    })
  }
  ```

  ```bash cURL theme={null}
  # Get the device.
  device=$(
    # Use GET or POST.
    curl -X 'GET' \
      'https://connect.getseam.com/devices/get' \
      -H 'accept: application/json' \
      -H "Authorization: Bearer ${SEAM_API_KEY}" \
      -H 'Content-Type: application/json' \
      -d '{
        "device_id": "11111111-1111-1111-1111-444444444444"
    }')

  # Confirm that Seam supports simulated connection for the device.
  if  $(jq -r '.device.can_simulate_connection' <<< ${device}); then \
    # Perform the simulated connection.
    curl -X 'POST' \
      'https://connect.getseam.com/devices/simulate/connect' \
      -H 'accept: application/json' \
      -H "Authorization: Bearer ${SEAM_API_KEY}" \
      -H 'Content-Type: application/json' \
      -d "{
        \"device_id\": \"$(jq -r '.device.device_id' <<< ${device})\"
    }";
  fi
  ```

  ```python Python theme={null}
  # Get the device.
  device = seam.devices.get(
    device_id="11111111-1111-1111-1111-444444444444"
  )

  # Confirm that Seam supports simulated connection for the device.
  if device.can_simulate_connection:
    # Perform the simulated connection.
    seam.devices.simulate.connect(device_id=device.device_id)
  ```

  ```ruby Ruby theme={null}
  # Get the device.
  device = client.devices.get(device_id: "11111111-1111-1111-1111-444444444444")

  # Confirm that Seam supports simulated connection for the device.
  if (device.can_simulate_connection)
    # Perform the simulated connection.
    client.devices.simulate.connect(device_id: device.device_id)
  end
  ```

  ```php PHP theme={null}
  // Get the device.
  $device = $seam->devices->get(device_id: "11111111-1111-1111-1111-444444444444");

  // Confirm that Seam supports simulated connection for the device.
  if ($device->can_simulate_connection) {
    // Perform the simulated connection.
    $seam->devices->simulate->connect(device_id: $device->device_id);
  }
  ```

  ```csharp C# theme={null}
  // Get the device.
  Device device = seam.Devices.Get(deviceId: "11111111-1111-1111-1111-444444444444");

  // Confirm that Seam supports simulated connection for the device.
  if (device.CanSimulateConnection == true) {
    // Perform the simulated connection.
    seam.Devices.Simulate.Connect(deviceId: device.DeviceId);
  }
  ```
</CodeGroup>

**Output:**

<CodeGroup>
  ```json JavaScript theme={null}
  void
  ```

  ```json cURL theme={null}
  {
    "ok": true
  }
  ```

  ```json Python theme={null}
  None
  ```

  ```json Ruby theme={null}
  nil
  ```

  ```json PHP theme={null}
  void
  ```

  ```json C# theme={null}
  void
  ```
</CodeGroup>

***

## Simulate Removing a Device

To simulate a device removal:

**Code:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  // Get the device.
  const device = await seam.devices.get({
    device_id: '11111111-1111-1111-1111-444444444444',
  })

  // Confirm that Seam supports simulated removal for the device.
  if (device.can_simulate_removal) {
    // Perform the simulated removal.
    await seam.devices.simulate.remove({
      device_id: device.device_id,
    })
  }
  ```

  ```bash cURL theme={null}
  # Get the device.
  device=$(
    # Use GET or POST.
    curl -X 'GET' \
      'https://connect.getseam.com/devices/get' \
      -H 'accept: application/json' \
      -H "Authorization: Bearer ${SEAM_API_KEY}" \
      -H 'Content-Type: application/json' \
      -d '{
        "device_id": "11111111-1111-1111-1111-444444444444"
    }')

  # Confirm that Seam supports simulated removal for the device.
  if  $(jq -r '.device.can_simulate_removal' <<< ${device}); then \
    # Perform the simulated removal.
    curl -X 'POST' \
      'https://connect.getseam.com/devices/simulate/remove' \
      -H 'accept: application/json' \
      -H "Authorization: Bearer ${SEAM_API_KEY}" \
      -H 'Content-Type: application/json' \
      -d "{
        \"device_id\": \"$(jq -r '.device.device_id' <<< ${device})\"
    }";
  fi
  ```

  ```python Python theme={null}
  # Get the device.
  device = seam.devices.get(
    device_id="11111111-1111-1111-1111-444444444444"
  )

  # Confirm that Seam supports simulated removal for the device.
  if device.can_simulate_removal:
    # Perform the simulated removal.
    seam.devices.simulate.remove(device_id=device.device_id)
  ```

  ```ruby Ruby theme={null}
  # Get the device.
  device = client.devices.get(device_id: "11111111-1111-1111-1111-444444444444")

  # Confirm that Seam supports simulated removal for the device.
  if (device.can_simulate_removal)
    # Perform the simulated removal.
    client.devices.simulate.remove(device_id: device.device_id)
  end
  ```

  ```php PHP theme={null}
  // Get the device.
  $device = $seam->devices->get(device_id: "11111111-1111-1111-1111-444444444444");

  // Confirm that Seam supports simulated removal for the device.
  if ($device->can_simulate_removal) {
    // Perform the simulated removal.
    $seam->devices->simulate->remove(device_id: $device->device_id);
  }
  ```

  ```csharp C# theme={null}
  // Get the device.
  Device device = seam.Devices.Get(deviceId: "11111111-1111-1111-1111-444444444444");

  // Confirm that Seam supports simulated removal for the device.
  if (device.CanSimulateRemoval == true) {
    // Perform the simulated removal.
    seam.Devices.Simulate.Remove(deviceId: device.DeviceId);
  }
  ```
</CodeGroup>

**Output:**

<CodeGroup>
  ```json JavaScript theme={null}
  void
  ```

  ```json cURL theme={null}
  {
    "ok": true
  }
  ```

  ```json Python theme={null}
  None
  ```

  ```json Ruby theme={null}
  nil
  ```

  ```json PHP theme={null}
  void
  ```

  ```json C# theme={null}
  void
  ```
</CodeGroup>

***

## Simulate Device Disconnection, Connection, and Removal in the Seam Console

You can also use the [Seam Console](https://console.seam.co/) to simulate disconnecting, connecting, and removing a device.

<Info>
  Currently, Seam supports these actions for
  [August](/device-and-system-integration-guides/august-locks/august-locks-sample-data)
  and
  [Yale](/device-and-system-integration-guides/yale-locks/yale-sample-data)
  sandbox devices.
</Info>

1. In the upper-right corner of the Seam Console, click the down arrow to display the workspace list and select a sandbox workspace.
2. In the left navigation pane of the Seam Console, click **Connected Accounts**.
3. Click the account that contains the device that you want to simulate disconnecting, connecting, or removing.
4. At the right of the row for the desired device, click **...** and select **Simulate Removal**, **Simulate Connection**, or **Simulate Disconnection**.\
   The Seam Console only displays the actions that you can perform based on the current state of the device. For example, if the device is already disconnected, you cannot simulate disconnection.
5. Click **Simulate Removal**, **Simulate Connection**, or **Simulate Disconnection** to confirm the action.


# Mapping Your Resources to Seam Resources
Source: https://docs.seam.co/core-concepts/mapping-your-resources-to-seam-resources

Learn how Seam makes it easy to tag Seam resources with your own internal IDs.

Seam enables you to set a custom unique key on each instance of resources, like Spaces, User Identities, and Access Grants. Use these keys to map your own data—such as rooms, listings, or reservations—to the corresponding Seam resources. In addition, you can link your own customers with the Connect Webviews and resulting Connected Accounts that they use to connect their devices and systems to Seam.

Resource keys make it easier to cross-reference and sync information between your systems and Seam.

Each resource includes a `<resource>_key` property in which you can store your own identifier. For example:

* `space_key` for [Spaces](/api/spaces/object)
* `user_identity_key` for [User Identities](/api/user_identities/object)
* `access_grant_key` for [Access Grants](/api/access_grants/object)
* `customer_key` for [Connect Webviews](/api/connect_webviews/object) and [Connected Accounts](/api/connected_accounts/object)

Resource keys of each type generally need to be unique within your workspace. For example, if you save a Space with the `space_key` `room-101-id`, you cannot create another Space with this key.

The one exception is with `customer_key`, where you can create multiple Connect Webviews using the same `customer_key`.

The guide describes how to add resources keys to Seam resources of various relevant types and also how to retrieve a Seam resource using a resource key.

***

## **Associating Connected Accounts with Your Customers**

[Connected Accounts](/core-concepts/connected-accounts/index) represent connections that your customers set up with their own devices or access systems through your app. You embed a [Connect Webview](/core-concepts/connect-webviews/index) in your app, and your customers establish these connections by authenticating their device or system accounts through the pre-built Connect Webview flow. Each successful connection creates a Connected Account in your Seam workspace. Each Connected Account is linked to a specific customer.

When you create an instance of a Connect Webview, you can tag it with a customer key. When your customer completes the authentication flow through this Connect Webview, Seam automatically copies the `customer_key` to the resulting Connected Account. You can then use the `customer_key` to retrieve the Connected Account consistently.

### Create a Connect Webview for a Specific Customer

**Code:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  await seam.connectWebviews.create({
    customer_key: 'customer-id', // Your unique identifier for the customer
  })
  ```

  ```bash cURL theme={null}
  # Include your unique identifier for the customer.
  curl -X 'POST' \
    'https://connect.getseam.com/connect_webviews/create' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d "{
    \"customer_key\": \"${customer-id}\"
  }"
  ```

  ```python Python theme={null}
  seam.connect_webviews.create(
    customer_key = "customer-id" # Your unique identifier for the customer
  )
  ```

  ```ruby Ruby theme={null}
  client.connect_webviews.create(
    customer_key: "customer-id" # Your unique identifier for the customer
  )
  ```

  ```php PHP theme={null}
  $created_connect_webview = $seam->connect_webviews->create(
    customer_key: "customer-id" // Your unique identifier for the customer
  );
  ```

  ```csharp C# theme={null}
  // Coming soon!
  ```
</CodeGroup>

**Output:**

<CodeGroup>
  ```json JavaScript theme={null}
  {
    connect_webview_id: '12345678-1234-1234-1234-123456789012',
    customer_key: 'customer-id',
    ...
  }
  ```

  ```json cURL theme={null}
  {
    "connect_webview": {
      "connect_webview_id": "12345678-1234-1234-1234-123456789012",
      "customer_key": "customer-id",
      ...
    },
    "ok": true
  }
  ```

  ```json Python theme={null}
  ConnectWebview(
    connect_webview_id='12345678-1234-1234-1234-123456789012',
    customer_key='customer-id',
    ...
  )
  ```

  ```json Ruby theme={null}
  <Seam::ConnectWebview:0x00438
      connect_webview_id="12345678-1234-1234-1234-123456789012"
      customer_key="customer-id"
      ...
  >
  ```

  ```json PHP theme={null}
  {
    "connect_webview_id": "12345678-1234-1234-1234-123456789012",
    "customer_key": "customer-id",
    ...
  }
  ```

  ```json C# theme={null}
  // Coming soon!
  ```
</CodeGroup>

### Retrieve All Connected Accounts for a Specific Customer

Once your customer has completed the Connect Webview authentication flow, and Seam has copied the `customer_key` to the resulting Connected Account, you can list all Connected Accounts associated with a specific `customer_key` tag. Then, you can also list all devices or systems associated with the customer, using the retrieved Connected Account ID.

**Code:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  const connected_accounts = await seam.connected_accounts.list({
    customer_key: 'customer-id',
  })

  let customerSystems = []

  for (const account of connected_accounts) {
    const systems = await seam.acs.systems.list({
      connected_account_id: account.connected_account_id,
    })
    customerSystems.push(...systems)
  }

  console.log(customerSystems)
  ```

  ```bash cURL theme={null}
  connected_accounts=$(curl -X GET \
    'https://connect.getseam.com/connected_accounts/list' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d "{
      \"customer_key\": \"${customer-id}\"
    }")

  account_ids=$(echo $connected_accounts | jq -r '.connected_accounts[].connected_account_id')

  customer_systems="[]"
  for account_id in $account_ids; do
    systems=$(curl -X GET \
    'https://connect.getseam.com/acs/systems/list' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d "{
      \"connected_account_id\": \"${account_id}\"
    }")
    customer_systems=$(jq -s '.[0] + .[1]' <(echo "$customer_systems") <(echo $systems | jq '.systems'))
  done

  echo $customer_systems
  ```

  ```python Python theme={null}
  connected_accounts = seam.connected_accounts.list(
    customer_key="customer-id"
  )

  customer_systems = []

  for account in connected_accounts:
    systems = seam.acs.systems.list(
      connected_account_id=account.connected_account_id
    )

    customer_systems.extend(systems)

  pprint(customer_systems)
  ```

  ```ruby Ruby theme={null}
  connected_accounts = seam.connected_accounts.list(
    customer_key: "customer-id"
  )

  customer_systems = []

  connected_accounts.each do |account|
    systems = seam.acs.systems.list(
      connected_account_id: account.connected_account_id
    )
    customer_systems.concat(systems)
  end

  puts customer_systems.inspect
  ```

  ```php PHP theme={null}
  $connected_accounts = $seam->connected_accounts->list(
    'customer_key' => 'customer-id'
  );

  $customer_systems = [];

  foreach ($connected_accounts as $account) {
    $systems = $seam->acs->systems->list(
      "connected_account_id" : $account->connected_account_id
    );
    $customer_systems = array_merge($customer_systems, $systems);
  }

  echo json_encode($customer_systems);
  ```

  ```csharp C# theme={null}
  // Coming soon!
  ```
</CodeGroup>

**Output:**

<CodeGroup>
  ```json JavaScript theme={null}
  [
    {
      connected_account_id: '11111111-1111-1111-1111-111111111111',
      acs_system_id: '22222222-2222-2222-2222-222222222222',
      name: 'Salto KS Site',
      ...
    },
    {
      connected_account_id: '11111111-1111-1111-1111-111111111111',
      acs_system_id: '33333333-3333-3333-3333-333333333333',
      name: 'Salto Space Site',
      ...
    },
    ...
  ]
  ```

  ```json cURL theme={null}
  {
    "acs_systems": [
      {
        "connected_account_id": "11111111-1111-1111-1111-111111111111",
        "acs_system_id": "22222222-2222-2222-2222-222222222222",
        "name": "Salto KS Site",
        ...
      },
      {
        "connected_account_id": "11111111-1111-1111-1111-111111111111",
        "acs_system_id": "33333333-3333-3333-3333-333333333333",
        "name": "Salto Space Site",
        ...
      },
      ...
    ],
    "ok": true
  }
  ```

  ```json Python theme={null}
  [
    AcsSystem(
      connected_account_id="11111111-1111-1111-1111-111111111111",
      acs_system_id="22222222-2222-2222-2222-222222222222",
      name="Salto KS Site",
      ...
    ),
    AcsSystem(
      connected_account_id="11111111-1111-1111-1111-111111111111",
      acs_system_id="33333333-3333-3333-3333-333333333333",
      name="Salto Space Site",
      ...
    ),
    ...
  ]
  ```

  ```json Ruby theme={null}
  [
    <Seam::AcsSystem:0x00438
      connected_account_id="11111111-1111-1111-1111-111111111111"
      acs_system_id="22222222-2222-2222-2222-222222222222"
      name="Salto KS Site"
      ...
    >,
    <Seam::AcsSystem:0x00438
      connected_account_id="11111111-1111-1111-1111-111111111111"
      acs_system_id="33333333-3333-3333-3333-333333333333"
      name="Salto Space Site"
      ...
    >,
    ...
  ]
  ```

  ```json PHP theme={null}
  [
    {
      "connected_account_id": "11111111-1111-1111-1111-111111111111",
      "acs_system_id": "22222222-2222-2222-2222-222222222222",
      "name": "Salto KS Site",
      ...
    },
    {
      "connected_account_id": "11111111-1111-1111-1111-111111111111",
      "acs_system_id": "33333333-3333-3333-3333-333333333333",
      "name": "Salto Space Site",
      ...
    },
    ...
  ]
  ```

  ```json C# theme={null}
  // Coming soon!
  ```
</CodeGroup>

Any accounts that your customer sets up also carry this `customer_key`, so you can associate their connected systems with their properties, Spaces, and reservations in your own database.

***

## **Associating a Seam Space with Your Own Resource**

When you create a Seam space resource, you can include your own ID as the value for the `space_key`. Some examples of resources that you could tie to a Space include hotel rooms, apartments, or common area amenities.

**Code:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  await seam.spaces.create({
    name: 'Valley Grove - Room 104',
    acs_entrance_ids: [unit104Entrance.acs_entrance_id],
    space_key: 'room-104-id', // Your room ID
  })
  ```

  ```bash cURL theme={null}
  # Include your room ID.
  curl -X 'POST' \
    'https://connect.getseam.com/spaces/create' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d "{
    \"name\": \"Valley Grove - Room 104\",
    \"acs_entrance_ids\": [\"$(jq -r '.acs_entrance.acs_entrance_id' <<< ${unit_104_entrance})\"],
    \"space_key\": \"room-104-id\"
  }"
  ```

  ```python Python theme={null}
  seam.spaces.create(
    name = "Valley Grove - Room 104",
    acs_entrance_ids = [unit_104_entrance.acs_entrance_id],
    space_key = "room-104-id" # Your room ID
  )
  ```

  ```ruby Ruby theme={null}
  client.spaces.create(
    name: "Valley Grove - Room 104",
    acs_entrance_ids: [unit_104_entrance.acs_entrance_id],
    space_key: "room-104-id" # Your room ID
  )
  ```

  ```php PHP theme={null}
  $seam->spaces->create(
    name: "Valley Grove - Room 104",
    acs_entrance_ids: [$unit_104_entrance->acs_entrance_id],
    space_key: "room-104-id" // Your room ID
  );
  ```

  ```csharp C# theme={null}
  // Coming soon!
  ```
</CodeGroup>

**Output:**

<CodeGroup>
  ```json JavaScript theme={null}
  {
    space_id: '44444444-4444-4444-4444-444444444444',
    name: 'Valley Grove - Room 104',
    space_key: 'room-104-id',
    ...
  }
  ```

  ```json cURL theme={null}
  {
    "space": {
      "space_id": "44444444-4444-4444-4444-444444444444",
      "name": "Valley Grove - Room 104",
      "space_key": "room-104-id",
      ...
    },
    "ok": true
  }
  ```

  ```json Python theme={null}
  Space(
    space_id='44444444-4444-4444-4444-444444444444',
    name='Valley Grove - Room 104',
    space_key='room-104-id',
    ...
  )
  ```

  ```json Ruby theme={null}
  <Seam::Space:0x00438
      space_id="44444444-4444-4444-4444-444444444444"
      name="Valley Grove - Room 104"
      space_key="room-104-id"
      ...
  >
  ```

  ```json PHP theme={null}
  {
    "space_id": "44444444-4444-4444-4444-444444444444",
    "name": "Valley Grove - Room 104",
    "space_key": "room-104-id",
    ...
  }
  ```

  ```json C# theme={null}
  // Coming soon!
  ```
</CodeGroup>

***

## Associating a Seam User Identity with Your User

You can use the `user_identity_key` to link a Seam User Identity with your ID for a user, such as a hotel guest, resident, and so on.

**Code:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  await seam.userIdentities.create({
    full_name: 'Jane Doe',
    user_identity_key: 'user-123-id', // Your end user ID
  })
  ```

  ```bash cURL theme={null}
  # Include your end user ID.
  curl -X 'POST' \
    'https://connect.getseam.com/user_identities/create' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d '{
    "full_name": "Jane Doe",
    "user_identity_key": "user-123-id"
  }'
  ```

  ```python Python theme={null}
  seam.user_identities.create(
    full_name = "Jane Doe",
    user_identity_key = "user-123-id" # Your end user ID
  )
  ```

  ```ruby Ruby theme={null}
  client.user_identities.create(
    full_name: "Jane Doe",
    user_identity_key: "user-123-id" # Your end user ID
  )
  ```

  ```php PHP theme={null}
  $seam->user_identities->create(
    full_name: "Jane Doe",
    user_identity_key: "user-123-id" // Your end user ID
  );
  ```

  ```csharp C# theme={null}
  // Coming soon!
  ```
</CodeGroup>

**Output:**

<CodeGroup>
  ```json JavaScript theme={null}
  {
    user_identity_id: '55555555-5555-5555-5555-555555555555',
    full_name: 'Jane Doe',
    user_identity_key: 'user-123-id',
    ...
  }
  ```

  ```json cURL theme={null}
  {
    "space": {
      "user_identity_id": "55555555-5555-5555-5555-555555555555",
      "full_name": "Jane Doe",
      "user_identity_key": "user-123-id",
      ...
    },
    "ok": true
  }
  ```

  ```json Python theme={null}
  UserIdentity(
    user_identity_id='55555555-5555-5555-5555-555555555555',
    full_name='Jane Doe',
    user_identity_key='user-123-id',
    ...
  )
  ```

  ```json Ruby theme={null}
  <Seam::UserIdentity:0x00438
      user_identity_id="55555555-5555-5555-5555-555555555555"
      full_name="Jane Doe"
      user_identity_key="user-123-id"
      ...
  >
  ```

  ```json PHP theme={null}
  {
    "user_identity_id": "55555555-5555-5555-5555-555555555555",
    "full_name": "Jane Doe",
    "user_identity_key": "user-123-id",
    ...
  }
  ```

  ```json C# theme={null}
  // Coming soon!
  ```
</CodeGroup>

***

## **Associating a Seam Access Grant with Your Own Resource**

You can add your own booking or lease reference to a Seam Access Grant as an `access_grant_key`. Some examples of resources that you could tie to an Access Grant include a guest booking, apartment lease, or gym day pass.

**Code:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  await seam.accessGrants.create({
    user_identity_id: userIdentity.user_identity_id,
    starts_at: '2025-08-13T15:00:00.000Z',
    ends_at: '2025-08-16T11:00:00.000Z',
    requested_access_methods: [{ mode: 'mobile_key' }],
    space_ids: [room104Id],
    access_grant_key: 'booking-789-id', // Your booking or lease reference
  })
  ```

  ```curl cURL theme={null}
  # Include your booking or lease reference.
  curl -X 'POST' \
    'https://connect.getseam.com/access_grants/create' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d "{
      \"user_identity_id\": \"$(jq -r '.user_identity.user_identity_id' <<< ${user_identity})\",
      \"starts_at\": \"2025-08-13T15:00:00.000Z\",
      \"ends_at\": \"2025-08-16T11:00:00.000Z\",
      \"requested_access_methods\": [
        {\"mode\": \"mobile_key\"}
      ],
      \"space_ids\": [\"${room_104_id}\"],
      \"access_grant_key\": \"booking-789-id\"
  }"
  ```

  ```python Python theme={null}
  seam.access_grants.create(
    user_identity_id=user_identity.user_identity_id,
    starts_at="2025-08-13T15:00:00.000Z",
    ends_at="2025-08-16T11:00:00.000Z",
    requested_access_methods=[
      {"mode": "mobile_key"}
    ],
    space_ids=[room_104_id],
    access_grant_key="booking-789-id" # Your booking or lease reference
  )
  ```

  ```ruby Ruby theme={null}
  seam.access_grants.create(
    user_identity_id: user_identity.user_identity_id,
    starts_at: "2025-08-13T15:00:00.000Z",
    ends_at: "2025-08-16T11:00:00.000Z",
    requested_access_methods: [
      {"mode": "mobile_key"}
    ],
    space_ids: %w[ room_104_id ],
    access_grant_key: "booking-789-id" # Your booking or lease reference
  )
  ```

  ```php PHP theme={null}
  $seam->access_grants->create(
    user_identity_id: $user_identity->user_identity_id,
    starts_at: "2025-08-13T15:00:00.000Z",
    ends_at: "2025-08-16T11:00:00.000Z",
    requested_access_methods: [
      ["mode" => "mobile_key"]
    ],
    space_ids: [ room_104_id ],
    access_grant_key: "booking-789-id" // Your booking or lease reference
  );
  ```

  ```csharp C# theme={null}
  // Coming Soon!
  ```
</CodeGroup>

**Output:**

<CodeGroup>
  ```json JavaScript theme={null}
  {
    "access_grant_id": "66666666-6666-6666-6666-666666666666",
    "access_grant_key": "booking-789-id",
    "starts_at": "2025-08-13T15:00:00.000Z",
    "ends_at": "2025-08-16T11:00:00.000Z",
    "user_identity_id": "55555555-5555-5555-5555-555555555555",
    "space_ids": [ "44444444-4444-4444-4444-444444444444" ],
    "requested_access_methods": [
      {
        "display_name": "Mobile Key",
        "mode": "mobile_key",
        "created_access_method_ids": ["77777777-7777-7777-7777-777777777777"],
        ...
      }
    ],
    "instant_key_url": "https://ik.seam.co/ABCXYZ",
    ...
  }
  ```

  ```json cURL theme={null}
  {
    "access_grant": {
      "access_grant_id": "66666666-6666-6666-6666-666666666666",
      "access_grant_key": "booking-789-id",
      "starts_at": "2025-08-13T15:00:00.000Z",
      "ends_at": "2025-08-16T11:00:00.000Z",
      "user_identity_id": "55555555-5555-5555-5555-555555555555",
      "space_ids": [ "44444444-4444-4444-4444-444444444444" ],
      "requested_access_methods": [
        {
          "display_name": "Mobile Key Credential",
          "mode": "mobile_key",
          "created_access_method_ids": ["77777777-7777-7777-7777-777777777777"],
          ...
        }
      ],
      "instant_key_url": "https://ik.seam.co/ABCXYZ",
      ...
    }
  }
  ```

  ```python Python theme={null}
  AccessGrant(
    access_grant_id="66666666-6666-6666-6666-666666666666",
    access_grant_key="booking-789-id",
    starts_at="2025-08-13T15:00:00.000Z",
    ends_at="2025-08-16T11:00:00.000Z",
    user_identity_id="55555555-5555-5555-5555-555555555555",
    space_ids=[ "44444444-4444-4444-4444-444444444444" ],
    requested_access_methods=[
      {
        "display_name": "Mobile Key",
        "mode": "mobile_key",
        "created_access_method_ids": ["77777777-7777-7777-7777-777777777777"],
        ...
      }
    ],
    instant_key_url="https://ik.seam.co/ABCXYZ",
    ...
  )
  ```

  ```ruby Ruby theme={null}
  <Seam::AccessGrant:0x00438
    access_grant_id="66666666-6666-6666-6666-666666666666"
    access_grant_key="booking-789-id"
    starts_at="2025-08-13T15:00:00.000Z"
    ends_at="2025-08-16T11:00:00.000Z"
    user_identity_id="55555555-5555-5555-5555-555555555555"
    space_ids: [ "44444444-4444-4444-4444-444444444444" ]
    requested_access_methods: [
      {
        "display_name": "Mobile Key",
        "mode": "mobile_key",
        "created_access_method_ids": ["77777777-7777-7777-7777-777777777777"],
        ...
      }
    ]
    instant_key_url: "https://ik.seam.co/ABCXYZ"
    ...
  >
  ```

  ```php PHP theme={null}
  {
    "access_grant_id": "66666666-6666-6666-6666-666666666666",
    "access_grant_key": "booking-789-id",
    "starts_at": "2025-08-13T15:00:00.000Z",
    "ends_at": "2025-08-16T11:00:00.000Z",
    "user_identity_id": "55555555-5555-5555-5555-555555555555",
    "space_ids": [ "44444444-4444-4444-4444-444444444444" ],
    "requested_access_methods": [
      {
        "display_name": "Mobile Key Credential",
        "mode": "mobile_key",
        "created_access_method_ids": ["77777777-7777-7777-7777-777777777777"],
        ...
      }
    ],
    "instant_key_url": "https://ik.seam.co/ABCXYZ",
    ...
  }
  ```

  ```json C# theme={null}
  // Coming Soon!
  ```
</CodeGroup>

***

## Retrieving a Resource Using the `<resource>_key`

Once you have linked your resources to Seam resources using resource keys, you can retrieve a Seam resource using your custom unique identifier for it.

The following example retrieves a Seam Space using a `space_key`:

**Code:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  await seam.spaces.get({
    space_key: 'room-104-id',
  })
  ```

  ```bash cURL theme={null}
  curl -X 'POST' \
    'https://connect.getseam.com/spaces/get' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d '{
    "space_key": "room-104-id"
  }'
  ```

  ```python Python theme={null}
  seam.spaces.get(
    space_key = "room-104-id"
  )
  ```

  ```ruby Ruby theme={null}
  client.spaces.get(
    space_key: "room-104-id"
  )
  ```

  ```php PHP theme={null}
  $seam->spaces->get(
    space_key: "room-104-id"
  );
  ```

  ```csharp C# theme={null}
  // Coming soon!
  ```
</CodeGroup>

**Output:**

<CodeGroup>
  ```json JavaScript theme={null}
  {
    space_id: '44444444-4444-4444-4444-444444444444',
    name: 'Valley Grove - Room 104',
    space_key: 'room-104-id',
    ...
  }
  ```

  ```json cURL theme={null}
  {
    "space": {
      "space_id": "44444444-4444-4444-4444-444444444444",
      "name": "Valley Grove - Room 104",
      "space_key": "room-104-id",
      ...
    },
    "ok": true
  }
  ```

  ```json Python theme={null}
  Space(
    space_id='44444444-4444-4444-4444-444444444444',
    name='Valley Grove - Room 104',
    space_key='room-104-id',
    ...
  )
  ```

  ```json Ruby theme={null}
  <Seam::Space:0x00438
      space_id="44444444-4444-4444-4444-444444444444"
      name="Valley Grove - Room 104"
      space_key="room-104-id"
      ...
  >
  ```

  ```json PHP theme={null}
  {
    "space_id": "44444444-4444-4444-4444-444444444444",
    "name": "Valley Grove - Room 104",
    "space_key": "room-104-id",
    ...
  }
  ```

  ```json C# theme={null}
  // Coming soon!
  ```
</CodeGroup>

The following example retrieves a Seam Access Grant using an `access_grant_key`:

**Code:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  await seam.accessGrants.get({
    access_grant_key: 'booking-789-id',
  })
  ```

  ```bash cURL theme={null}
  curl -X 'POST' \
    'https://connect.getseam.com/access_grants/get' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d '{
    "access_grant_key": "booking-789-id"
  }'
  ```

  ```python Python theme={null}
  seam.access_grants.get(
    access_grant_key = "booking-789-id"
  )
  ```

  ```ruby Ruby theme={null}
  client.access_grants.get(
    access_grant_key: "booking-789-id"
  )
  ```

  ```php PHP theme={null}
  $seam->access_grants->get(
    access_grant_key: "booking-789-id"
  );
  ```

  ```csharp C# theme={null}
  // Coming soon!
  ```
</CodeGroup>

**Output:**

<CodeGroup>
  ```json JavaScript theme={null}
  {
    "access_grant_id": "66666666-6666-6666-6666-666666666666",
    "access_grant_key": "booking-789-id",
    "starts_at": "2025-08-13T15:00:00.000Z",
    "ends_at": "2025-08-16T11:00:00.000Z",
    "user_identity_id": "55555555-5555-5555-5555-555555555555",
    "space_ids": [ "44444444-4444-4444-4444-444444444444" ],
    "requested_access_methods": [
      {
        "display_name": "Mobile Key",
        "mode": "mobile_key",
        "created_access_method_ids": ["77777777-7777-7777-7777-777777777777"],
        ...
      }
    ],
    "instant_key_url": "https://ik.seam.co/ABCXYZ",
    ...
  }
  ```

  ```json cURL theme={null}
  {
    "access_grant": {
      "access_grant_id": "66666666-6666-6666-6666-666666666666",
      "access_grant_key": "booking-789-id",
      "starts_at": "2025-08-13T15:00:00.000Z",
      "ends_at": "2025-08-16T11:00:00.000Z",
      "user_identity_id": "55555555-5555-5555-5555-555555555555",
      "space_ids": [ "44444444-4444-4444-4444-444444444444" ],
      "requested_access_methods": [
        {
          "display_name": "Mobile Key Credential",
          "mode": "mobile_key",
          "created_access_method_ids": ["77777777-7777-7777-7777-777777777777"],
          ...
        }
      ],
      "instant_key_url": "https://ik.seam.co/ABCXYZ",
      ...
    }
  }
  ```

  ```json Python theme={null}
  AccessGrant(
    access_grant_id="66666666-6666-6666-6666-666666666666",
    access_grant_key="booking-789-id",
    starts_at="2025-08-13T15:00:00.000Z",
    ends_at="2025-08-16T11:00:00.000Z",
    user_identity_id="55555555-5555-5555-5555-555555555555",
    space_ids=[ "44444444-4444-4444-4444-444444444444" ],
    requested_access_methods=[
      {
        "display_name": "Mobile Key",
        "mode": "mobile_key",
        "created_access_method_ids": ["77777777-7777-7777-7777-777777777777"],
        ...
      }
    ],
    instant_key_url="https://ik.seam.co/ABCXYZ",
    ...
  )
  ```

  ```json Ruby theme={null}
  <Seam::AccessGrant:0x00438
    access_grant_id="66666666-6666-6666-6666-666666666666"
    access_grant_key="booking-789-id"
    starts_at="2025-08-13T15:00:00.000Z"
    ends_at="2025-08-16T11:00:00.000Z"
    user_identity_id="55555555-5555-5555-5555-555555555555"
    space_ids: [ "44444444-4444-4444-4444-444444444444" ]
    requested_access_methods: [
      {
        "display_name": "Mobile Key",
        "mode": "mobile_key",
        "created_access_method_ids": ["77777777-7777-7777-7777-777777777777"],
        ...
      }
    ]
    instant_key_url: "https://ik.seam.co/ABCXYZ"
    ...
  >
  ```

  ```json PHP theme={null}
  {
    "access_grant_id": "66666666-6666-6666-6666-666666666666",
    "access_grant_key": "booking-789-id",
    "starts_at": "2025-08-13T15:00:00.000Z",
    "ends_at": "2025-08-16T11:00:00.000Z",
    "user_identity_id": "55555555-5555-5555-5555-555555555555",
    "space_ids": [ "44444444-4444-4444-4444-444444444444" ],
    "requested_access_methods": [
      {
        "display_name": "Mobile Key Credential",
        "mode": "mobile_key",
        "created_access_method_ids": ["77777777-7777-7777-7777-777777777777"],
        ...
      }
    ],
    "instant_key_url": "https://ik.seam.co/ABCXYZ",
    ...
  }
  ```

  ```json C# theme={null}
  // Coming soon!
  ```
</CodeGroup>


# Overview
Source: https://docs.seam.co/core-concepts/overview

Learn the core concepts behind Seam, including workspaces, Connect Webviews, device capabilities, and the Seam Console used to manage them.

Seam enables you to connect to, operate, and manage different brands of devices using the following basic concepts:

1. Your Seam account has one or more [workspaces](/core-concepts/workspaces/index) that encapsulate all resources.
2. You use [Connect Webviews](/core-concepts/connect-webviews/index) to connect devices to your workspace.
3. You control those devices according to their [capabilities](../capability-guides/device-and-system-capabilities).
4. You use [Seam Console](/core-concepts/seam-console/index) to manage your Seam workspaces, Connect Webviews, devices, and systems; [create API keys](/core-concepts/authentication/api-keys#create-an-api-key); and perform other tasks.


# Providers
Source: https://docs.seam.co/core-concepts/providers/index

Learn how to find out information about the providers that Seam supports.

Seam maintains a list of supported providers that you can access using the [List Device Providers](/api/devices/list_device_providers) endpoint. For a provider, this endpoint returns a subset of the following information, depending on the capabilities of the provider's devices:

<table>
  <thead>
    <tr>
      <th>Property</th>
      <th>Type</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        <code>device\_provider\_name</code>
      </td>

      <td>String</td>

      <td>
        <p>Name of the device provider.</p>

        <p>
          For example: <code>august</code>
        </p>
      </td>
    </tr>

    <tr>
      <td>
        <code>display\_name</code>
      </td>

      <td>String</td>

      <td>
        <p>
          Formatted version of the <code>device\_provider\_name</code>.
        </p>

        <p>
          For example: <code>August</code>
        </p>
      </td>
    </tr>

    <tr>
      <td>
        <code>image\_url</code>
      </td>

      <td>String</td>
      <td>Image URL for the provider logo.</td>
    </tr>

    <tr>
      <td>
        <code>provider\_categories</code>
      </td>

      <td>Array</td>

      <td>
        <p>Array of associated categories for the provider.</p>
        <p>Supported categories:</p>

        <ul>
          <li>
            <code>stable</code>
          </li>

          <li>
            <code>consumer\_smartlocks</code>
          </li>

          <li>
            <code>thermostats</code>
          </li>

          <li>
            <code>noise\_sensors</code>
          </li>
        </ul>
      </td>
    </tr>

    <tr>
      <td>
        <code>can\_remotely\_unlock</code>
      </td>

      <td>Boolean</td>

      <td>
        Indicates whether at least one supported device from the provider can
        perform a

        <a href="/low-level-apis/smart-locks/lock-and-unlock">
          remote unlock operation
        </a>

        . See

        <a href="../../capability-guides/device-and-system-capabilities#capability-flags">
          Capability Flags
        </a>

        .
      </td>
    </tr>

    <tr>
      <td>
        <code>can\_remotely\_lock</code>
      </td>

      <td>Boolean</td>

      <td>
        Indicates whether at least one supported device from the provider can
        perform a

        <a href="/low-level-apis/smart-locks/lock-and-unlock">
          remote lock operation
        </a>

        . See

        <a href="../../capability-guides/device-and-system-capabilities#capability-flags">
          Capability Flags
        </a>

        .
      </td>
    </tr>

    <tr>
      <td>
        <code>can\_program\_online\_access\_codes</code>
      </td>

      <td>Boolean</td>

      <td>
        Indicates whether at least one supported device from the provider can

        <a href="/low-level-apis/smart-locks/access-codes">
          program online access codes
        </a>

        . See

        <a href="../../capability-guides/device-and-system-capabilities#capability-flags">
          Capability Flags
        </a>

        .
      </td>
    </tr>

    <tr>
      <td>
        <code>can\_program\_offline\_access\_codes</code>
      </td>

      <td>Boolean</td>

      <td>
        Indicates whether at least one supported device from the provider can

        <a href="/low-level-apis/smart-locks/access-codes/offline-access-codes">
          program offline access codes
        </a>

        . See

        <a href="../../capability-guides/device-and-system-capabilities#capability-flags">
          Capability Flags
        </a>

        .
      </td>
    </tr>

    <tr>
      <td>
        <code>can\_simulate\_connection</code>
      </td>

      <td>Boolean</td>

      <td>
        Indicates whether at least one supported device from the provider can

        <a href="/core-concepts/devices/testing-your-app-against-device-disconnection-and-removal">
          simulate device connection
        </a>

        . See

        <a href="../../capability-guides/device-and-system-capabilities#capability-flags">
          Capability Flags
        </a>

        .
      </td>
    </tr>

    <tr>
      <td>
        <code>can\_simulate\_disconnection</code>
      </td>

      <td>Boolean</td>

      <td>
        Indicates whether at least one supported device from the provider can

        <a href="/core-concepts/devices/testing-your-app-against-device-disconnection-and-removal">
          simulate device disconnection
        </a>

        . See

        <a href="../../capability-guides/device-and-system-capabilities#capability-flags">
          Capability Flags
        </a>

        .
      </td>
    </tr>

    <tr>
      <td>
        <code>can\_simulate\_removal</code>
      </td>

      <td>Boolean</td>

      <td>
        Indicates whether at least one supported device from the provider can

        <a href="/core-concepts/devices/testing-your-app-against-device-disconnection-and-removal">
          simulate device removal
        </a>

        . See

        <a href="../../capability-guides/device-and-system-capabilities#capability-flags">
          Capability Flags
        </a>

        .
      </td>
    </tr>

    <tr>
      <td>
        <code>can\_hvac\_cool</code>
      </td>

      <td>Boolean</td>

      <td>
        Indicates whether at least one supported device from the provider can be

        <a href="/capability-guides/thermostats/configure-current-climate-settings">
          set to cool mode
        </a>

        . See

        <a href="../../capability-guides/device-and-system-capabilities#capability-flags">
          Capability Flags
        </a>

        .
      </td>
    </tr>

    <tr>
      <td>
        <code>can\_hvac\_heat</code>
      </td>

      <td>Boolean</td>

      <td>
        Indicates whether at least one supported device from the provider can be

        <a href="/capability-guides/thermostats/configure-current-climate-settings">
          set to heat mode
        </a>

        . See

        <a href="../../capability-guides/device-and-system-capabilities#capability-flags">
          Capability Flags
        </a>

        .
      </td>
    </tr>

    <tr>
      <td>
        <code>can\_hvac\_heat\_cool</code>
      </td>

      <td>Boolean</td>

      <td>
        Indicates whether at least one supported device from the provider can be

        <a href="/capability-guides/thermostats/configure-current-climate-settings">
          set to heat-cool mode
        </a>

        . See

        <a href="../../capability-guides/device-and-system-capabilities#capability-flags">
          Capability Flags
        </a>

        .
      </td>
    </tr>

    <tr>
      <td>
        <code>can\_turn\_off\_hvac</code>
      </td>

      <td>Boolean</td>

      <td>
        Indicates whether at least one supported device from the provider can be

        <a href="/capability-guides/thermostats/configure-current-climate-settings">
          set to off mode
        </a>

        . See

        <a href="../../capability-guides/device-and-system-capabilities#capability-flags">
          Capability Flags
        </a>

        .
      </td>
    </tr>
  </tbody>
</table>

The following example shows a `device_provider`:

```json theme={null}
{
  "device_provider_name": "august",
  "display_name": "August",
  "image_url": "https://connect.getseam.com/_next/image?url=https://connect.getseam.com/assets/images/logos/august_logo_square.png&q=75&w=128",
  "provider_categories": ["stable", "consumer_smartlocks"],
  "can_remotely_lock": true,
  "can_remotely_unlock": true,
  "can_program_online_access_codes": true,
  "can_simulate_connection": true,
  "can_simulate_disconnection": true,
  "can_simulate_removal": true
}
```


# Provider Metadata
Source: https://docs.seam.co/core-concepts/providers/provider-metadata

Learn about provider metadata that is used to provide data about a device that can't be or hasn't yet been standardized across all providers.

When integrating with a provider, Seam adds any information that doesn't fit nicely into a cross-provider standard field into the provider metadata for a device or system. Provider metadata is an object named as follows on a device or system:

`[device or acs_system].properties.[provider]_metadata`

Examples of provider metadata include `august_metadata`, `schlage_metadata`, and `visionline_metadata`.

Sometimes provider metadata contains fields where Seam is still coming up with a standard representation, so you can use these fields to "get ahead" of Seam's standardized implementation.

<Danger>
  Do not use `[provider]_metadata.model` because it is being deprecated and is
  likely to be changed or removed in the future.
</Danger>

## Getting Provider Metadata

To access provider metadata, make any call that returns device properties, such as [`/devices/get`](/api/devices/get) or [`/devices/list`](/api/devices/list).

<Info>
  Provider metadata is also available in [sandbox
  workspaces](/core-concepts/workspaces/index#sandbox-workspaces), so if you want to see typical
  examples of provider metadata, you can just create a webview and connect
  devices in a sandbox workspace to read the properties.
</Info>

For example, to get SmartThings metadata:

<CodeGroup>
  ```javascript JavaScript theme={null}
  const devices = await seam.devices.list()

  console.log(devices[0].properties.smartthings_metadata)
  /*
  {
    "model": "0129-8002-0600",
    "device_id": "750ed15f-93f2-4ff1-8944-47e93b10f7d6",
    "device_name": "Yale Door Lock"
  }
  */
  ```

  ```bash HTTP theme={null}
  curl \
    -H 'Authorization: Bearer MY_API_KEY' \
    https://connect.getseam.com/devices/list

  #{
  #  "devices": [
  #    {
  #      "device_id": "3c196474-d2eb-4e07-b1d0-e2996eeb40d0",
  #      "device_type": "smartthings_lock",
  #      "properties": {
  #        "smartthings_metadata": {
  #          "model": "0129-8002-0600",
  #          "device_id": "750ed15f-93f2-4ff1-8944-47e93b10f7d6",
  #          "device_name": "Yale Door Lock"
  #        },
  # ...
  ```
</CodeGroup>

## Provider Metadata Definitions

### August Metadata

August metadata is stored in `device.properties.august_metadata`.

<table>
  <thead>
    <tr>
      <th>Property</th>
      <th>Description</th>
      <th>Typical Value</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>lock\_id</td>
      <td>Identifier for lock as stored by August</td>
      <td>"348350520F06446Q940E2F67E21D351A"</td>
    </tr>

    <tr>
      <td>lock\_name</td>
      <td>Name for lock, typically named by host</td>
      <td>"Front Door"</td>
    </tr>

    <tr>
      <td>house\_name</td>

      <td>
        House name that the host placed the lock in from the August App or Yale
        Access App
      </td>

      <td>"123 Amy Lane"</td>
    </tr>

    <tr>
      <td>has\_keypad</td>

      <td>
        Boolean indicating whether or not a keypad is paired to the lock, or the
        lock has a keypad on it
      </td>

      <td>true</td>
    </tr>
  </tbody>
</table>

### Schlage Metadata

Schlage metadata is stored on `device.properties.schlage_metadata`.

| Property             | Description                                              | Typical Value                          |
| -------------------- | -------------------------------------------------------- | -------------------------------------- |
| device\_id           | Id for device as stored by Schlage                       | "c7dd9f62-2b3f-4135-b092-160fc1b4179b" |
| device\_name         | Name given to Schlage device, usually via the host's app | "My Door"                              |
| access\_code\_length | Length of access codes supported on device.              | 4                                      |

### SmartThings Metadata

SmartThings metadata is stored on `device.properties.smartthings_metadata`.

| Property     | Description                                                                 | Typical Value                          |
| ------------ | --------------------------------------------------------------------------- | -------------------------------------- |
| device\_id   | Id for device as stored by Smartthings                                      | "750ed15f-93f2-4ff1-8944-47e93b10f7d6" |
| device\_name | Name for device, set in the Smartthings app or from a Smartthings dashboard | "Front Door"                           |

### Lockly Metadata

Lockly metadata is stored on `device.properties.lockly_metadata`.

| Property     | Description                    | Typical Value               |
| ------------ | ------------------------------ | --------------------------- |
| device\_id   | Device Id as stored by Lockly  | "750ed15f93f24ff1894447e93" |
| device\_name | Device name as given by Lockly | "Front Door"                |

### Salto Metadata

Salto metadata is stored on `device.properties.salto_metadata`.

| Property            | Description                                               | Typical Value  |
| ------------------- | --------------------------------------------------------- | -------------- |
| lock\_id            | Identifier for lock as stored by Salto                    |                |
| customer\_reference | Name of the device as given by Installer or User in Salto | "BACK DOOR"    |
| lock\_type          | Lock type as given by Salto                               | "wall\_reader" |
| battery\_level      | Battery level enums as provided by Salto.                 | "fresh"        |
| locked\_state       | Locked state as given Salto                               | "locked"       |

### Genie Metadata

Genie metadata is stored on `device.properties.genie_metadata`.

| Property     | Description | Typical Value |
| ------------ | ----------- | ------------- |
| device\_name |             | "Model 3155D" |
| door\_name   |             | "Front Door"  |

### Brivo Metadata

Brivo metadata is stored on `device.properties.brivo_metadata`.

| Property     | Description                  | Typical Value |
| ------------ | ---------------------------- | ------------- |
| device\_name | Name as set by user in Brivo | "Front Door"  |

### Igloo Metadata

Igloo metadata is stored on `device.properties.igloo_metadata`.

| Property   | Description                         | Typical Value |
| ---------- | ----------------------------------- | ------------- |
| device\_id | Device Id as stored by Igloo        |               |
| bridge\_id | Id of Bridge device stored by Igloo |               |


# Seam Console
Source: https://docs.seam.co/core-concepts/seam-console/index

Use Seam Console to manage your Seam workspaces, Connect Webviews, devices, and systems; generate API keys; use the Seam Online CLI; and perform other tasks.

Seam Console enables you to manage all resources associated with your Seam account. First, create a Seam account or, if you have already created an account, log in to Seam Console. Then, use Seam Console to perform a variety of tasks, including the the following:

* Create and manage [workspaces](/core-concepts/workspaces/index).
* Create and manage [API keys](../authentication/api-keys).
* Add and manage [devices](/core-concepts/devices/index).
* Add and manage [access control systems](/low-level-apis/access-systems/index).
* Create, customize, and manage [Connect Webviews](/core-concepts/connect-webviews/index).
* Add and manage [webhooks](../../developer-tools/webhooks).
* Use the [Seam Online CLI](/core-concepts/seam-console/seam-online-cli).

## Create a Seam Account

1. In a web browser, navigate to [https://console.seam.co/signup](https://console.seam.co/signup).
2. Type your first name, last name, and email address, as well as the desired password, and then click **Continue**.\
   Alternately, click **Continue with Google**.

Once you have created your Seam account, Seam Console displays the **Devices** page.

## Log in to Seam Console Using an Email Address

1. In a web browser, navigate to [https://console.seam.co](https://console.seam.co).
2. Type your email address and click **Continue**.\
   Seam sends a verification email to the email address that you have specified.
3. Open the verification email and click **Sign in**.

Once you have logged in to your Seam account, Seam Console displays the **Devices** page.

## Log in to Seam Console Using Google

1. In a web browser, navigate to [https://console.seam.co](https://console.seam.co).
2. Click **Continue with Google**.
3. Log in to your Google account if you have not done so already.

Once you have logged in to your Google account, Seam Console displays the **Devices** page.

## Reset Your Seam Password

1. In a web browser, navigate to [https://console.seam.co](https://console.seam.co).
2. Click **Reset password**.
3. Type your email address and click **Send reset link**.\
   Seam sends a reset email to the email address that you have specified.
4. Open the reset email and click **Sign in**.
5. Return to the original web browser tab or click **click here** in the newly-opened tab.\
   Seam Console displays the **Set Password** page.
6. Type and confirm a new password for your Seam account and then click **Continue**.

Seam Console resets your password to the new password that you have specified.


# Seam Online CLI
Source: https://docs.seam.co/core-concepts/seam-console/seam-online-cli

Use the interactive Seam Online CLI as a user-friendly and efficient way to explore and test the Seam API from within Seam Console.

<img alt="Use the interactive Seam CLI to explore and test the Seam API." />

The Seam Online Command Line Interface (CLI) is a fully interactive CLI version of the Seam API. You access the Seam Online CLI from within [Seam Console](./). Quick, intuitive, and easy to use, the Seam Online CLI enables you to perform a variety of useful tasks, including the following:

* Explore and test all the available methods in the Seam API interactively.
* View resources or test API functions easily and quickly.
* Inspect the results of your API commands.
* Access Seam API functionality that is not currently available in Seam Console.

<Info>
  In addition to using the Seam Online CLI within Seam Console, you can also
  [install and use the Seam CLI locally](../../developer-tools/seam-cli).
</Info>

<CardGroup>
  <Card title="Seam Online CLI Demo" href="https://youtu.be/GGmQQ57jBn0" />
</CardGroup>

## Access the Seam Online CLI

1. In the upper-left corner of [Seam Console](https://console.seam.co/), click the workspace switcher.<img alt="Use the Seam Console workspace switcher to switch between workspaces and create new workspaces." />
2. Click the workspace for which you want to use the Seam Online CLI.
3. In the top navigation pane, click **Developer**.
4. In the left navigation pane, click **Online CLI**.

The Seam Online CLI opens in a new browser tab or window. It initializes and then displays the following message:

`👋 try running 'seam' to get started!`

Each instance of the Seam Online CLI begins within the workspace from which you opened the CLI. However, you can use `seam select workspace` to switch to a different workspace or `seam login` to use a Personal Access Token for multi-workspace access.

## Use the Seam CLI

Interact with the Seam CLI using any combination of interactive and typed commands. You "construct" the full command, including any desired parameters, and then run the command.

1. Click within the Seam CLI pane to activate this pane.

2. Enter a command stub, such as `seam`, `seam devices`, or `seam devices list`.\
   Some commonly-used command stubs include the following:

   * `seam`
   * `seam access-codes`
   * `seam acs`
   * `seam action-attempts`
   * `seam client-sessions`
   * `seam connect-webviews`
   * `seam devices`
   * `seam locks`
   * `seam login`
   * `seam noise-sensors`
   * `seam select`
   * `seam thermostats`
   * `seam user-identities`

   For a full list of command stubs, see [Seam CLI Command Stubs](#seam-cli-command-stubs).

3. Use the up and down arrows and press **Enter** to select the desired command and parameters.

   You can also type the beginning of a command or parameter name to filter the list of interactive options.

4. Enter or select any desired parameter values.\
   You can specify values for multiple parameters and edit any parameter values that you have already specified. You can also [copy and paste](#copying-and-pasting-in-the-seam-cli) values.

   For example, if you have chosen to use `seam devices get`, and have selected the `device_id` parameter, the Seam CLI displays a list of the names and IDs of all devices to which you have access. Use the arrow keys to select the desired device and then press **Enter**.

5. Once you have constructed the full command to run, use the up and down arrows to select `Make API Call` and then press **Enter**.\
   The Seam CLI runs the specified command and displays the output.

6. If you have chosen to run a command that returns an [action attempt](../action-attempts), use the left and right arrows to select `yes` or `no` and then press **Enter** to indicate whether to poll the action attempt until it completes.

## Seam CLI Command Stubs

The Seam CLI supports the following command stubs:

<table>
  <thead>
    <tr>
      <th>Command Stub</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        <code>seam</code>
      </td>

      <td>Access all Seam CLI commands in an interactive manner.</td>
    </tr>

    <tr>
      <td>
        <code>seam access-codes</code>
      </td>

      <td>
        Manage

        <a href="/low-level-apis/smart-locks/access-codes">
          access codes
        </a>

        .
      </td>
    </tr>

    <tr>
      <td>
        <code>seam acs</code>
      </td>

      <td>
        Manage

        <a href="/low-level-apis/access-systems">
          Access Control Systems
        </a>

        (ACSs), including associated objects, such as systems, users, access
        groups, and credentials.
      </td>
    </tr>

    <tr>
      <td>
        <code>seam action-attempts</code>
      </td>

      <td>
        List and get <a href="/core-concepts/action-attempts">action attempts</a> to poll
        the status of attempted actions, such as

        <a href="/low-level-apis/smart-locks/lock-and-unlock">
          unlock
        </a>

        and

        <a href="/low-level-apis/smart-locks/access-codes/creating-access-codes">
          create access code
        </a>

        .
      </td>
    </tr>

    <tr>
      <td>
        <code>seam client-sessions</code>
      </td>

      <td>
        Manage

        <a href="../../ui-components/overview/getting-started-with-seam-components/get-started-with-react-components-and-client-session-tokens#what-is-a-client-session-token">
          client sessions
        </a>

        that enable you to restrict users' interactions to include only the
        devices that they own.
      </td>
    </tr>

    <tr>
      <td>
        <code>seam connect-webviews</code>
      </td>

      <td>
        Manage <a href="/core-concepts/connect-webviews">Connect Webviews</a> that enable
        users to connect their devices to Seam.
      </td>
    </tr>

    <tr>
      <td>
        <code>seam connected-accounts</code>
      </td>

      <td>
        Manage

        <a href="/api/connected_accounts/object">
          connected accounts
        </a>

        that represent external, third-party accounts to which users have
        authorized Seam to access.
      </td>
    </tr>

    <tr>
      <td>
        <code>seam devices</code>
      </td>

      <td>
        Manage devices, including both

        <a href="/core-concepts/devices/managed-and-unmanaged-devices">
          "managed" and "unmanaged" devices
        </a>

        .
      </td>
    </tr>

    <tr>
      <td>
        <code>seam events</code>
      </td>

      <td>
        Retrieve <a href="/api/events/object">events</a>.
      </td>
    </tr>

    <tr>
      <td>
        <code>seam locks</code>
      </td>

      <td>
        Retrieve, lock, and unlock
        <a href="/low-level-apis/smart-locks">smart locks</a>.
      </td>
    </tr>

    <tr>
      <td>
        <code>seam login</code>
      </td>

      <td>
        Log back in to the Seam CLI or change your authorization to use a
        different <a href="/core-concepts/authentication/api-keys">API key</a> or

        <a href="/core-concepts/authentication/personal-access-tokens">
          Personal Access Token
        </a>

        .
      </td>
    </tr>

    <tr>
      <td>
        <code>seam logout</code>
      </td>

      <td>Log out of the Seam CLI.</td>
    </tr>

    <tr>
      <td>
        <code>seam noise-sensors</code>
      </td>

      <td>
        Manage

        <a href="/capability-guides/noise-sensors#what-is-a-threshold">
          noise thresholds
        </a>

        for <a href="/capability-guides/noise-sensors">noise sensors</a>
        and simulate triggering noise threshold alerts.
      </td>
    </tr>

    <tr>
      <td>
        <code>seam select</code>
      </td>

      <td>
        Select the desired <a href="/core-concepts/workspaces">workspace</a> or server.
      </td>
    </tr>

    <tr>
      <td>
        <code>seam thermostats</code>
      </td>

      <td>
        Manage <a href="/capability-guides/thermostats">thermostats</a>,
        including

        <a href="/capability-guides/thermostats/configure-current-climate-settings">
          current climate settings
        </a>

        .
      </td>
    </tr>

    <tr>
      <td>
        <code>seam user-identities</code>
      </td>

      <td>
        Manage

        <a href="../../capability-guides/mobile-access/managing-mobile-app-user-accounts-with-user-identities#what-is-a-user-identity">
          user identities
        </a>

        that enable you to issue and manage mobile credentials and access
        permissions for users.
      </td>
    </tr>

    <tr>
      <td>
        <code>seam webhooks</code>
      </td>

      <td>
        Manage <a href="/developer-tools/webhooks">webhook</a> endpoints
        that enable you to receive notifications of Seam-related events.
      </td>
    </tr>

    <tr>
      <td>
        <code>seam workspaces</code>
      </td>

      <td>
        Manage your <a href="/core-concepts/workspaces">workspaces</a>, including creating
        new workspaces, retrieving existing workspaces, and resetting your
        sandbox workspaces.
      </td>
    </tr>
  </tbody>
</table>

## Copying and Pasting in the Seam CLI

To copy and paste values in the Seam CLI, right-click and select the desired option or use the following keyboard shortcuts:

| Operation | Windows/Linux                        | Mac           |
| --------- | ------------------------------------ | ------------- |
| Copy      | **Ctrl-Insert**                      | **Command-C** |
| Paste     | **Shift-Insert** or **Ctrl-Shift-V** | **Command-V** |


# Workspaces
Source: https://docs.seam.co/core-concepts/workspaces/index

Workspaces are the top-level resource in the Seam ecosystem. They encapsulate all other resources, such as devices, events, and connected third-party accounts.

## What is a Workspace?

A workspace is conceptually like a project or environment. It encapsulate all other Seam resources, such as devices and connected third-party accounts. You access resources within a workspace using an [API key](../authentication/api-keys), a [Personal Access Token](../authentication/personal-access-tokens) (PAT), or [client session tokens](/core-concepts/authentication/client-session-tokens/index), and you can receive events from a workspace using [webhooks](../../developer-tools/webhooks).

There is no limit to the number of workspaces that you can create, but most Seam customers only have the following two workspaces:

* One [sandbox workspace](#sandbox-workspaces) in which they connect virtual devices to test their apps
* One [production workspace](#production-workspaces) in which they connect real devices

<img alt="Workspaces encapsulate resources, such as devices and connected accounts. An API key for the workspace is required to interact with these resources. You can configure webhook endpoints to receive notifications from devices inside a workspace." />

***

## Production Workspaces

Production workspaces enable you to connect and control real devices from brands, such as August, Schlage, Ecobee, Google Nest, and more.

### Create a Production Workspace

1. In the upper-left corner of [Seam Console](https://console.seam.co/), click the workspace switcher to display the workspace list.

   <img alt="Use the Seam Console workspace switcher to switch between workspaces and create new workspaces." />

2. Click **New Workspace**.

3. In the **Add a Workspace** dialog, type a name for your new workspace and your company name.

4. Disable **Sandbox mode**.

   <img alt="To create a production workspace, disable sandbox mode." />

5. Click **Create Workspace**.

### Connecting Devices

You can use either of the following two ways to connect devices to a production workspace:

* Use [Seam Console](#connect-devices-using-seam-console).
* Use [Connect Webviews](#connect-devices-using-connect-webviews).

#### Connect Devices Using Seam Console

1. In the top navigation pane of [Seam Console](https://console.seam.co/), click **Devices**.
2. In the upper-right corner of the **Devices** page, click **Add Devices**.\
   Seam Console displays a [Connect Webview](/core-concepts/connect-webviews/index) (that is, an authorization flow) that enables you to connect a device account to Seam.
3. In the Connect Webview, click **Continue**.
4. In the manufacturer list, select the manufacturer of the devices that you want to connect.
5. Follow the login instructions to authorize these devices.

Once authorized, the devices associated with this test account appear in the **Devices** table in your production workspace.

#### Connect Devices Using Connect Webviews

If you are creating an application (app) to control your users' devices, use [Connect Webviews](/core-concepts/connect-webviews/index). Connect Webviews are fully-embedded client-side components that you add to your app. Your users interact with your embedded Connect Webviews to link their device accounts to Seam through your app. Seam handles all the authentication steps. Once your user has completed the authorization through your app, your users' devices are linked with your production workspace, and you can access and control their devices using the Seam API.

<img alt="Use Connect Webviews to enable your users to authorize your app to control their devices." />

### Single Workspace Setup (More Common)

Most Seam customers use a single production workspace to connect all their devices, regardless of whether these devices are ones that they own or they are controlling thousands of end customers' devices. For example, a property management app with thousands of customers could still use a single production workspace to connect all customers' devices.

<img alt="Most Seam customers use a single production workspace to connect all their devices." />

### Per-Customer Workspace Setup (Less Common)

Some Seam customers may be developing multiple apps, each of which needs to interact with devices. In this type of scenario, it may be useful to set up a different production workspace for each application.

For example, an information technology (IT) firm that builds custom apps for its customers will most likely want to create a separate workspace for each customer. This model can simplify security, support, and billing.

Occasionally, an app may also be using multiple Seam workspaces. For example, a restaurant chain providing a management dashboard for its franchisees may want to use a different Seam workspace for each franchisee to simplify billing and support. See App 3 in the following diagram:

<img alt="Some development scenarios may warrant using multiple production workspaces." />

<Info>
  Note that when you use multiple workspaces, you either need to create an [API
  key](../authentication/api-keys) for each workspace or create a single
  [Personal Access Token](../authentication/personal-access-tokens) (PAT) for
  use with all workspaces and then specify the ID of the workspace that you want
  to access.
</Info>

***

## Sandbox Workspaces

Sandbox workspaces are a special type of workspace designed for testing code. Sandbox workspaces offer test device accounts and virtual devices that you can connect and control. This ability to work with virtual devices is quite handy because it removes the need to own physical devices from multiple brands.

Importantly, virtual devices behave identically to the corresponding real devices. That is, if your app works with a virtual device in a sandbox workspace, it will also work with a real device in a production workspace.

<Info>
  You can only connect virtual devices in a sandbox workspace. To connect a real
  device, switch to a production workspace.
</Info>

### Create a Sandbox Workspace

1. In the upper-left corner of [Seam Console](https://console.seam.co/), click the workspace switcher to display the workspace list.

   <img alt="Use the Seam Console workspace switcher to switch between workspaces and create new workspaces." />

2. Click **New Workspace**.

3. In the **Add a Workspace** dialog, type a name for your new workspace and your company name.

4. Enable **Sandbox mode**.

5. Click **Create Workspace**.

### Connecting Virtual Devices

To connect virtual devices, specify the login credentials for test device accounts in the [Seam Console](#connect-devices-using-seam-console) or in [Connect Webviews](#connect-devices-using-connect-webviews) within your apps. All manufacturers and devices that Seam supports have one or more sandbox test accounts with pre-seeded devices. For login credentials for all test device accounts, see [Test Accounts](/developer-tools/test-accounts).

### Interacting with a Virtual Device

You can trigger test events for some virtual devices. This capability is useful for testing code that depends on receiving event notifications from the Seam API. For example, virtual noise sensor devices, such as Minut, provide the ability to trigger a "noise event" that emits an event to your webhook endpoint. Once you have triggered an event, you can view this even on the **Events** tab for the virtual device.

1. In the top navigation pane of the [Seam Console](https://console.seam.co/), click **Devices**.
2. In the **Devices** table, click the device with which you want to interact.
3. Click the **Actions** tab.\
   The **Actions** tab lists the actions that you can perform on this virtual device.
4. Click the desired action, as applicable for that action.\
   For example:
   * For a virtual door lock, click **Locked** to lock or unlock the lock.
   * For a virtual thermostat, click **Edit** and then modify the climate or fan setting.
   * For a virtual noise sensor, click **Trigger** to trigger a noise threshold alert.
5. Click the **Events** tab for the device.\
   The **Events** tab displays events for the device.

### Testing Your App

To help you test your app against events—like device disconnection or removal—that are difficult to orchestrate in a QA environment using real devices, Seam provides a suite of `simulate` endpoints that you can use in a [sandbox workspace](#sandbox-workspaces). See [Testing Your App Against Device Disconnection and Removal](../devices/testing-your-app-against-device-disconnection-and-removal).

### Resetting Sandbox Workspaces

Sandbox workspace are unique in that you can reset them to the original starting state. For example, if you need to run complex continuous integration (CI) testing for an app, you can reset the sandbox workspace after each individual test run.

You can reset a sandbox workspace either manually through [Seam Console](#reset-a-sandbox-workspace-using-seam-console) or programmatically using the [Seam API](#reset-a-sandbox-workspace-using-the-seam-api). For detailed information about resetting a sandbox workspace through the Seam API, see the [Reset a Sandbox Workspace](/api/workspaces/reset_sandbox) API reference.

#### Reset a Sandbox Workspace Using Seam Console

1. In the upper-left corner of [Seam Console](https://console.seam.co/), click the workspace switcher to display the workspace list.

   <img alt="Use the Seam Console workspace switcher to switch between workspaces and create new workspaces." />

2. Select the name of the sandbox workspace that you want to reset.\
   Seam Console switches to the selected sandbox workspace.

3. In the top navigation pane of [Seam Console](https://console.seam.co/), click **Settings**.

4. At the upper-right corner of the **Workspace Settings** page, click <img alt="Seam Console three-dot menu button" /> and then select **Reset Sandbox**.

5. Click **Reset Workspace** to confirm the reset.

#### Reset a Sandbox Workspace Using the Seam API

<CodeGroup>
  ```javascript JavaScript theme={null}
  // Reset the sandbox workspace associated with your API key.
  await seam.workspaces.resetSandbox()
  ```

  ```php PHP theme={null}
  // Reset the sandbox workspace associated with your API key.
  $seam->workspaces->reset_sandbox();
  ```
</CodeGroup>

***

## Sharing Workspaces

You can add teammates to your workspace.

1. In the upper-left corner of [Seam Console](https://console.seam.co/), click the workspace switcher to display the workspace list.

   <img alt="Use the Seam Console workspace switcher to switch between workspaces and create new workspaces." />

2. Select the name of the workspace that you want to share.\
   Seam Console switches to the selected workspace.

3. In the left navigation pane, click **Team**.

4. In the upper-right corner of the **Team** page, click **Add member**.

5. In the **Add Organization Member** dialog, type the email address of the teammate that you want to add to this workspace.

6. Click **Add to Team**.

Seam Console sends an email invitation to the specified teammate.


# Seam CLI
Source: https://docs.seam.co/developer-tools/seam-cli

Use the interactive Seam CLI as a user-friendly and efficient way to explore and test the Seam API.

<img alt="The Seam CLI is a great way to to explore and test the Seam API." />

The Seam Command Line Interface (CLI) is a fully interactive CLI version of the Seam API. You can [install the Seam CLI locally](#installing-the-seam-cli) or use the [Seam Online CLI](../core-concepts/seam-console/seam-online-cli) within the [Seam Console](/core-concepts/seam-console/index). Quick, intuitive, and easy to use, the Seam CLI enables you to perform a variety of useful tasks, including the following:

* Explore and test all the available methods in the Seam API interactively.
* View resources or test API functions easily and quickly.
* Inspect the results of your API commands.
* Access Seam API functionality that is not currently available in the Seam Console.

<img alt="Use the interactive Seam CLI to explore and test the Seam API." />

## Installing the Seam CLI

Install the Seam CLI using your preferred package manager, or download a standalone binary for your platform.

<Tabs>
  <Tab title="npm">
    Install the [`seam`](https://www.npmjs.com/package/seam) package globally:

    ```bash theme={null}
    npm install -g seam
    ```

    This package includes both the Seam CLI and the JavaScript SDK. To install just the CLI, use [`@seamapi/cli`](https://www.npmjs.com/package/@seamapi/cli) instead.

    <Info>
      The CLI requires Node.js 22.11.0 or later.
    </Info>
  </Tab>

  <Tab title="Homebrew">
    Tap the Seam formula repository, then install the `seam` formula:

    ```bash theme={null}
    brew tap seamapi/homebrew-seam
    brew install seam
    ```
  </Tab>

  <Tab title="Arch Linux">
    The CLI is published to the AUR as [`seam-bin`](https://aur.archlinux.org/packages/seam-bin). Install it with the AUR helper of your choice:

    ```bash theme={null}
    # Using aura
    aura -A seam-bin

    # Using paru
    paru -S seam-bin

    # Using yay
    yay -S seam-bin
    ```

    Alternatively, build and install the package manually with [`makepkg`](https://wiki.archlinux.org/title/Makepkg):

    ```bash theme={null}
    git clone https://aur.archlinux.org/seam-bin.git
    cd seam-bin
    makepkg -si
    ```
  </Tab>

  <Tab title="Standalone Binary">
    Standalone binaries for macOS, Linux, and Windows on both x64 and arm64 are attached to the [latest Seam CLI release](https://github.com/seamapi/cli/releases/latest). Use these if your platform has no package available.

    Download the asset that matches your platform. Then, on macOS or Linux, make it executable and move it somewhere on your `PATH`:

    ```bash theme={null}
    chmod +x seam-*
    sudo mv seam-* /usr/local/bin/seam
    ```

    <Info>
      Each release also includes a `checksums.txt` file so that you can verify the binary that you downloaded.
    </Info>
  </Tab>
</Tabs>

To confirm your installation, display the installed version:

```bash theme={null}
seam --version
```

## Using the Seam CLI

Interact with the Seam CLI using any combination of interactive and typed commands. You "construct" the full command, including any desired parameters, and then run the command.

For details, see [Use the Seam CLI](../core-concepts/seam-console/seam-online-cli#use-the-seam-cli) and [Seam CLI Command Stubs](../core-concepts/seam-console/seam-online-cli#seam-cli-command-stubs).


# Seam MCP Server
Source: https://docs.seam.co/developer-tools/seam-mcp

Connect your AI coding assistant to Seam documentation in under a minute — no API keys or authentication required.

The Seam MCP server gives your AI coding assistant direct access to the entire Seam documentation. It can search docs semantically, fetch full pages, and browse the doc tree — so your assistant always has accurate, up-to-date context about the Seam API.

<Check>
  **No API keys or authentication required.** The server is free and public —
  just add the URL and start coding.
</Check>

## Server URL

```
https://mcp.seam.co/mcp
```

Use this URL in any MCP-compatible client. Editor-specific instructions are below.

## One-Click Install

[**Install in Cursor**](cursor://anysphere.cursor-deeplink/mcp/install?name=seam\&config=eyJ1cmwiOiJodHRwczovL21jcC5zZWFtLmNvL21jcCJ9)

For other editors, follow the manual setup below.

## Setup

<Tabs>
  <Tab title="Claude Code">
    Run this command in your terminal:

    ```bash theme={null}
    claude mcp add --transport http seam https://mcp.seam.co/mcp
    ```
  </Tab>

  <Tab title="Cursor">
    Add to `.cursor/mcp.json` in your project:

    ```json theme={null}
    {
      "mcpServers": {
        "seam": {
          "url": "https://mcp.seam.co/mcp"
        }
      }
    }
    ```
  </Tab>

  <Tab title="Windsurf">
    Add to `~/.codeium/windsurf/mcp_config.json`:

    ```json theme={null}
    {
      "mcpServers": {
        "seam": {
          "serverUrl": "https://mcp.seam.co/mcp"
        }
      }
    }
    ```
  </Tab>

  <Tab title="VS Code">
    Add to `.vscode/mcp.json` in your project:

    ```json theme={null}
    {
      "servers": {
        "seam": {
          "type": "http",
          "url": "https://mcp.seam.co/mcp"
        }
      }
    }
    ```
  </Tab>

  <Tab title="Codex">
    Run this command in your terminal:

    ```bash theme={null}
    codex mcp add seam --url https://mcp.seam.co/mcp
    ```

    Or add to `~/.codex/config.toml`:

    ```toml theme={null}
    [mcp_servers.seam]
    url = "https://mcp.seam.co/mcp"
    ```
  </Tab>

  <Tab title="ChatGPT">
    1. Open ChatGPT Desktop 2. Go to **Settings** → **Apps & Connectors** →
       **Advanced settings** and enable **Developer Mode** 3. Go to **Settings** →
       **Connectors** and click **Create** 4. Enter a name (e.g., "Seam") and the
       URL: `https://mcp.seam.co/mcp`
  </Tab>

  <Tab title="Claude Desktop">
    1. Open Claude Desktop
    2. Go to **Settings** → **Connectors**
    3. Click **Add custom connector**
    4. Enter: `https://mcp.seam.co/mcp`
  </Tab>
</Tabs>

## Available Tools

| Tool                | Description                                                                                   |
| ------------------- | --------------------------------------------------------------------------------------------- |
| `search_docs`       | Semantic search across all Seam documentation. Returns ranked results with confidence scores. |
| `get_doc`           | Fetch the full content of a specific documentation page by path.                              |
| `list_doc_sections` | Browse the documentation tree structure to discover available pages.                          |

## Try It Out

After setup, try asking your AI assistant:

* "How do I create an API key in Seam?"
* "Show me how to unlock a door with the Seam API"
* "What access control systems does Seam support?"

## Troubleshooting

* **Tools not showing up?** Restart your editor or reload the window after adding the MCP configuration.
* **Connection errors?** Make sure you're using `https://mcp.seam.co/mcp` — the `/mcp` path is required.
* **Slow first response?** The first query may take a few seconds while the server warms up. Subsequent queries are fast.


# Test Accounts
Source: https://docs.seam.co/developer-tools/test-accounts

Log in to shared sandbox test accounts to connect virtual devices from any manufacturer, so you can build and test without physical hardware.

Seam provides shared **test accounts** for every manufacturer it supports, so you can connect virtual devices in a [sandbox workspace](/core-concepts/workspaces#sandbox-workspaces) and build your integration without any physical hardware.

When you connect a device—in the [Seam Console](https://console.seam.co) or through a [Connect Webview](/core-concepts/connect-webviews)—enter the test-account credentials below instead of real manufacturer credentials.

## The standard sandbox login

Most manufacturers accept the same test-account login:

| Field                              | Value                                                            |
| ---------------------------------- | ---------------------------------------------------------------- |
| **Email**                          | `jane@example.com`                                               |
| **Password**                       | `1234`                                                           |
| **Two-factor / verification code** | `123456`—only [a few brands prompt for one](#two-factor-prompts) |

Use `jane@example.com` exactly. Some providers accept any address in the `example.com` domain and create an account on the fly, but many only accept a specific seeded address, so an arbitrary address is not a safe default. A few providers seed a different address instead—Genie, for example, expects `john@example.com`.

If a sandbox login is rejected, check that brand's [sandbox guide](#per-brand-details) for the exact accounts it accepts.

### Two-factor prompts

Most providers never ask for a verification code. The ones that do accept `123456`:

* **August**
* **Yale Home**
* **Latch**
* **Avigilon Alta**—only for its MFA-enabled test account.

<Info>
  These are shared, non-secret sandbox fixtures. They work only in [sandbox
  workspaces](/core-concepts/workspaces#sandbox-workspaces) and grant no access
  to real accounts or devices, so they are safe to commit to code and share with
  your team.
</Info>

## Brands that need extra credentials

The following integrations require something beyond the standard login—an API key, an additional field, or extra setup steps. See each brand's sandbox guide for the exact values to enter.

| Brand                                                                                                                                                                    | What's different                                                                                                                                        |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [2N Intercoms](/device-and-system-integration-guides/2n-intercom-systems/2n-intercoms-sample-data)                                                                       | Standard login, plus separate per-device credentials for each intercom.                                                                                 |
| [ASSA ABLOY Vingcard Credential Services](/device-and-system-integration-guides/assa-abloy-vingcard-credential-services/sandbox-assa-abloy-vingcard-credential-services) | Username and password, plus a Credential Services URL.                                                                                                  |
| [ASSA ABLOY Visionline](/device-and-system-integration-guides/assa-abloy-visionline-access-control-system/assa-abloy-visionline-access-management-system-sample-data)    | Connects through [Seam Bridge](/capability-guides/seam-bridge); needs extra mobile-key setup and a Credential Services connection to issue mobile keys. |
| [ASSA ABLOY Vostio](/device-and-system-integration-guides/assa-abloy-vostio-access-control-system/sandbox-assa-abloy-vostio-access-control-system)                       | Username and password, plus a Client ID and User Pool ID; needs a Credential Services connection to issue mobile keys.                                  |
| [August Locks](/device-and-system-integration-guides/august-locks/august-locks-sample-data)                                                                              | Standard login; also choose a Device Region (for "Others," select **Email** as the 2FA method).                                                         |
| [Brivo Access](/device-and-system-integration-guides/brivo-access/brivo-access-sample-data)                                                                              | Standard login, plus a Brivo Access API key.                                                                                                            |
| [Dormakaba Ambiance](/device-and-system-integration-guides/dormakaba-ambiance-access-control-system/sandbox-dormakaba-ambiance-access-control-system)                    | Connect Webview with a PMS operator login and API client credentials; needs LEGIC Connect to issue mobile keys.                                         |
| [Dormakaba Community](/device-and-system-integration-guides/dormakaba-community-access-control-system/sandbox-dormakaba-community-access-control-system)                 | Connect Webview with a PMS operator login and Community API client credentials; needs LEGIC Connect to issue mobile keys.                               |
| [Dormakaba Oracode](/device-and-system-integration-guides/dormakaba-oracode-locks/dormakaba-oracode-sample-data)                                                         | No email or password; a username, site, and time zone.                                                                                                  |
| [Hotek](/device-and-system-integration-guides/hotek-access-control-system/sandbox-hotek-access-control-system)                                                           | No credentials; complete the Connect Webview (site name and TCP port).                                                                                  |
| [Latch](/device-and-system-integration-guides/latch-access-control-system/sandbox-latch-access-control-system)                                                           | No credentials; complete the Connect Webview and select Latch.                                                                                          |
| [Lockly Locks](/device-and-system-integration-guides/lockly-locks/lockly-lock-sample-data)                                                                               | API-key style: an email plus Team/Client ID, Access Key, and Token values. No password.                                                                 |
| [Omnitec Locks](/device-and-system-integration-guides/omnitec-locks/sandbox-omnitec-locks)                                                                               | Standard login; also select any time zone in the Connect Webview.                                                                                       |
| [PTI Storlogix Cloud](/device-and-system-integration-guides/pti-storlogix-cloud/pti-storlogix-cloud-sample-data)                                                         | Standard login, plus a Site Key, Site Code, and a dashboard URL.                                                                                        |
| [Salto Space](/device-and-system-integration-guides/salto-proaccess-space-access-system/sandbox-salto-space-access-control-system)                                       | Connects through Seam Bridge; uses a username and password over a LAN URL.                                                                              |
| [Wyze Locks](/device-and-system-integration-guides/wyze-locks/wyze-sample-data)                                                                                          | Standard login, plus a Wyze API Key ID and API Key.                                                                                                     |

## Per-brand details

Each manufacturer's [sandbox guide](/device-and-system-integration-guides) lists its exact accepted accounts and the virtual devices pre-seeded with each one. To trigger test events on a virtual device or reset a sandbox workspace, see [Sandbox Workspaces](/core-concepts/workspaces#sandbox-workspaces).


# Webhooks
Source: https://docs.seam.co/developer-tools/webhooks

Learn about using webhooks to receive notifications of events.

## Configuring Webhooks

You can configure endpoints in each workspace for an app to receive webhook [event](/api/events/object) notifications for resources, such as devices and connected accounts.

To configure webhook endpoints:

1. In the left navigation pane of the [Seam Console](https://console.seam.co/), click **Webhooks**.
2. Click **+ Add Webhook**.
3. In the **Create Webhook** dialog, type your webhook URL and select the [event types](/api/events/object) for which you want to receive events.
4. Click **Create**.
5. Copy your webhook secret and store it somewhere secure. You use this webhook secret to validate the payloads that you receive on your webhook.

You can add webhooks through the Seam Console or programmatically. Let's start by looking at how to add and test a webhook using the Seam Console.

<img alt="Click + Add Webhook to create a webhook for your device events." />

You can specify any public URL endpoint to receive webhook events by pasting the URL into the **Create Webhook** dialog.

<img alt="You can specify any internet-accessible URL as your webhook URL." />

Webhook endpoints can receive many different types of events, such as `device.connected` or `device.low_battery`. It's a good idea when getting started with webhooks to review the list of webhook [event types](/api/events/object) and test your endpoint using the Svix sandbox environment.

<img alt="The Svix sandbox environment enables you to test sending requests to an endpoint." />

You can view all the event types and the included fields in the **Event Catalog** tab.

<img alt="Go to the &#x22;Event Catalog&#x22; tab to view all available events." />

We use webhooks from Svix. For more information about consuming events, such as testing or verifying webhooks, see the [Svix docs](https://docs.svix.com/receiving/introduction).

## Testing Events

Use the webhooks playground in Seam Console to see the payload for each event and test these events against your own endpoints.

<img alt="Use the webhooks playground to test events." />

## Tracking a Device Count from Webhooks

If you maintain your own count of the devices in a Seam workspace—for example, to display a total in your dashboard or to reconcile against your billing—process these four events:

| Event                                   | Effect on your count            |
| --------------------------------------- | ------------------------------- |
| `device.added`                          | Device is present and managed   |
| `device.unmanaged.converted_to_managed` | Device is present and managed   |
| `device.converted_to_unmanaged`         | Device is no longer managed     |
| `device.deleted`                        | Device no longer exists in Seam |

<Warning>
  **Track device IDs, not a bare integer.** `device.added` fires both when a
  device first syncs *and* when a previously removed device is re-added, so a
  counter that blindly increments on every `device.added` will drift upward over
  time. Keep a set of `device_id` values and add or remove members as events
  arrive; your count is then the size of the set, and a repeated event is
  harmless.
</Warning>

Two related events deliberately do **not** change the count:

* **`device.removed`** means the device was removed externally from the connected account. Seam keeps the device and flags it, so it still exists in your workspace. If it reappears, Seam clears the flag and emits `device.added`—which is exactly the case the warning above describes.
* **`device.connected`** and **`device.disconnected`** report reachability, not existence. An offline device is still a device.

Because webhook delivery is retried and can arrive out of order, treat this as an eventually-consistent cache rather than the source of truth. Reconcile periodically with [List Devices](/api/devices/list), which is authoritative.

For more about what "managed" means and why it matters for billing, see [Managed and Unmanaged Devices](/core-concepts/devices/managed-and-unmanaged-devices).

## Retry Schedule for Webhooks

Seam delivers each webhook event based on a retry schedule with exponential backoff. Each message is attempted based on the following schedule, where each period is started following the failure of the preceding attempt:

* Immediately
* 5 seconds
* 5 minutes
* 30 minutes
* 2 hours
* 5 hours
* 10 hours
* 10 hours (in addition to the previous)

For example, an attempt that fails three times before eventually succeeding will be delivered roughly 35 minutes and 5 seconds following the first attempt.

If you remove or disable a webhook, delivery attempts to the endpoint are disabled as well.


# Sandbox 2N Intercoms
Source: https://docs.seam.co/device-and-system-integration-guides/2n-intercom-systems/2n-intercoms-sample-data

Add virtual 2N intercoms to your Seam sandbox workspace using these sample account and device credentials to test your integration.

Use the following sets of account and then device credentials to add virtual [2N intercoms](/device-and-system-integration-guides/2n-intercom-systems) to your Seam [sandbox workspace](/core-concepts/workspaces#sandbox-workspaces):

## Account Credentials

| Email Address                                                                              | Password |
| ------------------------------------------------------------------------------------------ | -------- |
| [jane@example.com](mailto:jane@example.com) or any email address in the example.com domain | 1234     |

## Device Credentials

| Device   | Username | Password |
| -------- | -------- | -------- |
| Device 0 | jane     | 1234     |
| Device 1 | jane     | 1234     |
| Device 2 | jane     | 1234     |


# 2N System Set Up Instructions
Source: https://docs.seam.co/device-and-system-integration-guides/2n-intercom-systems/2n-system-set-up-instructions

Connect your 2N intercoms to Seam by preparing a My2N Company Admin account, adding your devices, and enabling Remote API Access.

## Prepare My2N Account for Seam Integration

<Warning>
  To connect 2N devices to Seam, you must use a Company Admin account with multi-factor authentication (MFA) disabled.

  If MFA is required for your admin account, create a separate account without MFA for dedicated API communication.
</Warning>

***

### Set up steps

1. **Create a My2N account**\
   [Sign up for a My2N account](https://my2n.com/2n-remote-configuration) if you don't already have one.
2. **Add your 2N devices**\
   In My2N, add your 2N IP devices to the account.
3. **Enable Remote API Access (RAA)**\
   Make sure Remote API Access (RAA) is enabled for your company. If it's not, contact [integrations@2n.com](mailto:integrations@2n.com) to activate it. Provide the company ID, which is located in the URL.

***

### Enable HTTP API for each Device

Repeat the following steps for each 2N device you want to control through Seam.

1. **Open device configuration**
   * In My2N, go to **Devices** in the left sidebar.
   * Click the **three-dot icon** next to your device and choose **Open configuration**.\\
   * When prompted, log in with the device’s credentials:
     * Default username: `Admin`
     * Default password: `2n`
     * (Use custom credentials if they were changed during installation.)

2. **Enable HTTP API services**
   * In the device dashboard, click **Services**.
   * From the sidebar, select **HTTP API**.
   * On the **Services** tab, make sure all of the APIs are enabled, with

     **Connection Type** set to **Secure (TLS)** and **Authentication** set to **Digest.**

3. **Create API credentials**
   * In the top toolbar, click on **Account 1**, or another available account.
   * Enable the account.
   * Create a **Username** and **Password**.
   * In the **User Privileges** section, ensure both **Monitoring** and **Control** boxes are checked for all listed options.
   * Click the Save (💾) icon in the bottom-right corner to confirm.

<Info>
  **Note**: the **Username** and **Password** created in this step will be used
  when connecting your device to Seam, please log and remember them.
</Info>

***

## Connect Webview Instructions

The Seam Connect Webview is where you securely link your My2N account to Seam.

This connection lets Seam manage and update your 2N intercom devices.

1. **Select My2N**\
   In the Seam Connect Webview, select **My2N** from the list of brands available.

2. **Enter your Company Admin credentials**
   * Enter the Company Admin My2N email and password for your property’s My2N account, then click **Submit**.
   * **Note:** Use an account with multi-factor authentication (MFA) turned off. If your main admin account requires MFA, create a separate account without MFA for this connection.

3. **Choose which devices to connect**\
   The Webview will show all 2N devices under your My2N company.

   If a device doesn’t appear, check that it’s been added and that the HTTP API is enabled.

   Select the devices you want to link to Seam, then click **Submit**.

4. **Authorize device access**\
   For each selected device, enter the **Username** and **Password** you created in the [Enable HTTP API for Each Device](#enable-http-api-for-each-device) section.

   This step confirms that Seam can securely communicate with your 2N devices to perform actions like unlocking doors or managing access codes.


# Get started with 2N Intercoms
Source: https://docs.seam.co/device-and-system-integration-guides/2n-intercom-systems/get-started-with-2n-intercoms

Learn how to connect and control your 2N intercom with the Seam API. Connect devices like 2N Verso, Solo, or IP Style, and use Seam to unlock the door, edit residents, list events & more.

## Overview

Seam provides a universal API to connect and control many brands of smart devices. This guide provides a rapid introduction to connecting and controlling your [2N](https://www.seam.co/manufacturers/2n) intercom using the Seam API. To learn more about other smart device brands supported by Seam such as Yale, Schlage, and August, head over to our [integration page](https://www.seam.co/supported-devices-and-systems).

<Warning>
  2N devices are currently required to be connected to the My2N cloud service to
  be controlled via Seam. If you are unable or do not wish to connect your 2N
  device to My2N, please [contact us](https://www.seam.co/contact-us) to discuss
  alternative options.
</Warning>

## 1 — Install Seam SDK

Seam provides client libraries for many languages, such as JavaScript, Python, Ruby, PHP, and others, as well as a Postman collection and [OpenAPI](https://connect.getseam.com/openapi.json) spec.

* JavaScript / TypeScript ([npm](https://www.npmjs.com/package/seam), [GitHub](https://github.com/seamapi/javascript))
* Python ([pip](https://pypi.org/project/seam/), [GitHub](https://github.com/seamapi/python))
* Ruby Gem ([rubygem](https://rubygems.org/gems/seam), [GitHub](https://github.com/seamapi/ruby))
* PHP ([packagist](https://packagist.org/packages/seamapi/seam), [GitHub](https://github.com/seamapi/php))
* C# ([nuget](https://www.nuget.org/packages/Seam), [GitHub](https://github.com/seamapi/csharp))

<Tabs>
  <Tab title="JavaScript">
    ```bash theme={null}
    npm i seam
    ```
  </Tab>

  <Tab title="Python">
    ```bash theme={null}
    pip install seam
    # For some development environments, use pip3 in this command instead of pip.
    ```
  </Tab>

  <Tab title="Ruby">
    ```bash theme={null}
    bundle add seam
    ```
  </Tab>

  <Tab title="PHP">
    ```bash theme={null}
    composer require seamapi/seam
    ```
  </Tab>

  <Tab title="C#">
    Install using [nuget](https://www.nuget.org/packages/Seam).
  </Tab>
</Tabs>

Once installed, [sign-up for Seam](https://console.seam.co/) to get your API key, and export it as an environment variable:

```
$ export SEAM_API_KEY=seam_test2ZTo_0mEYQW2TvNDCxG5Atpj85Ffw
```

<Info>
  This guide uses a Sandbox Workspace. Only virtual devices can be connected. If
  you need to connect a real device, use a non-sandbox workspace and API key.
</Info>

## 2 — Link My2N Account with Seam

To control your 2N intercom via the Seam API, you must first authorize your Seam workspace against your My2N account. To do so, Seam provides [Connect Webviews](/core-concepts/connect-webviews): pre-built UX flows that walk you through authorizing your application to control your 2N intercom.

#### Request a Connect Webview

<CodeGroup>
  ```javascript JavaScript theme={null}
  import { Seam } from 'seam'

  const seam = new Seam()

  const connectWebview = await seam.connectWebviews.create()

  console.log(connectWebview.login_successful) // false

  // Send the webview URL to your user
  console.log(connectWebview.url)

  ```

  ```python Python theme={null}
  from seam import Seam

  seam = Seam()

  webview = seam.connect_webviews.create()

  assert webview.login_successful is False

  # Send the webview URL to your user
  print(webview.url)
  ```

  ```ruby Ruby theme={null}
  require "seam"

  seam = Seam.new(api_key: "MY_API_KEY")

  webview = seam.connect_webviews.create()

  puts webview.login_successful # false

  # Send the webview URL to your user

  puts webview.url

  ```

  ```php PHP theme={null}
  use Seam\SeamClient;

  $seam = new SeamClient("YOUR_API_KEY");

  $webview = $seam->connect_webviews->create();

  echo json_encode($webview)
  ```
</CodeGroup>

#### Authorize Your Workspace

Navigate to the URL returned by the Webview object. Since you are using a sandbox workspace, complete the login flow by entering the My2N [sandbox test account](./2n-intercoms-sample-data) credentials below:

* **email:** [jane@example.com](mailto:jane@example.com)
* **password:** 1234

After entering the credentials for My2N, you'll have to enter the credentials of an existing HTTP user on each device you want to connect. All sandbox devices have a single HTTP user with the credentials:

* **username:** jane
* **password:** 1234

Confirm the Connect Webview was successful by querying its status:

<CodeGroup>
  ```javascript JavaScript theme={null}
  const updatedWebview = await seam.connectWebviews.get(
    connectWebview.connect_webview_id,
  )

  console.log(updatedWebview.login_successful) // true

  ```

  ```python Python theme={null}
  updated_webview = seam.connect_webviews.get(connect_webview_id: webview.connect_webview_id)

  assert updated_webview.login_successful # true
  ```

  ```ruby Ruby theme={null}
  updated_webview = seam.connect_webviews.get(connect_webview_id: webview.connect_webview_id)

  puts updated_webview.login_successful # true

  ```

  ```php PHP theme={null}
  $webview = $seam->connect_webviews->get($webview->id);
  echo json_encode($webview);
  ```
</CodeGroup>

## 3 — Retrieve My2N Devices

After a My2N account is linked with Seam, you can retrieve devices for this My2N account. 2N devices are represented as locks.

<CodeGroup>
  ```javascript JavaScript theme={null}
  const allLocks = await seam.locks.list()

  const someLock = allLocks[0]

  console.log(someLock.properties.online) // true
  console.log(someLock.properties.locked) // true

  console.log(someLock)
  /_
  {
  device_id: 'f0c074d6-34d0-4910-a16a-dfe078d5d178',
  device_type: 'two_n_intercom',
  capabilities_supported: [ 'access_code', 'lock' ],
  properties: {
  locked: true,
  online: true,
  manufacturer: 'two_n',
  serial_number: '4c0e6e72-81da-48af-8825-ed92a6fb8186',
  two_n_metadata: { device_id: 1, device_name: 'Device 0' },
  supported_code_lengths: [ 4, 5, 6, 7, 8 ],
  name: 'Device 0',
  image_url: 'http://localhost:3020/assets/images/devices/unknown-lock.png',
  image_alt_text: 'Placeholder Lock Image'
  },
  location: null,
  connected_account_id: '273b8072-c2c0-48ba-be17-2ec112276fca',
  workspace_id: 'e13ac83b-7150-4bf7-9229-6affd885c1d9',
  created_at: '2023-05-03T20:58:28.520Z',
  errors: [],
  warnings: []
  }
  _/

  ```

  ```python Python theme={null}
  all_locks = seam.locks.list()

  some_lock = all_locks[0]

  assert some_lock.properties["online"] is True
  assert some_lock.properties["locked"] is True

  print(some_lock)
  # Device(
  #   device_id='f0c074d6-34d0-4910-a16a-dfe078d5d178',
  #   device_type='two_n_intercom',
  #   location=None,
  #   properties={
  #     'locked': True,
  #     'online': True,
  #     'manufacturer': 'two_n',
  #     'serial_number': '4c0e6e72-81da-48af-8825-ed92a6fb8186',
  #     'two_n_metadata': {
  #       'device_id': 1,
  #       'device_name': 'Device 0'
  #     },
  #     'supported_code_lengths': [4, 5, 6, 7, 8],
  #     'name': 'Device 0',
  #     'image_url': 'http://localhost:3020/assets/images/devices/unknown-lock.png',
  #     'image_alt_text': 'Placeholder Lock Image'
  #   },
  #   capabilities_supported=['access_code', 'lock'],
  #   errors=[]
  # )
  ```

  ```ruby Ruby theme={null}
  some_lock = seam.locks.list.first

  puts some_lock.properties.online # true
  puts some_lock.properties.locked # true

  puts some_lock.inspect

  # <Seam::Device:0x00c8bb8

  # device_id="580365be-4f0f-42d9-9336-07f0bba09e28"

  # device_type="two_n_intercom"

  # properties={

  # "online"=>true,

  # "locked"=>true,

  # "manufacturer"=>"two_n",

  # "serial_number"=>"ef730e77-8cc0-4290-a818-14388e9fe84f",

  # "two_n_metadata"=>{

  # "device_id"=>1,

  # "device_name"=>"Device 0"

  # },

  # "supported_code_lengths"=>[4, 5, 6, 7, 8],

  # "name"=>"Device 0",

  # "image_url"=>"https://connect.getseam.com/assets/images/devices/unknown-lock.png",

  # "image_alt_text"=>"Placeholder Lock Image"

  # }

  # created_at=2023-05-03 18:01:16.965 UTC

  # errors=[]

  # warnings=[]

  ```

  ```php PHP theme={null}
  use Seam\SeamClient;

  $seam = new SeamClient('YOUR_API_KEY');

  $locks = $seam->locks->list();

  echo json_encode($locks);
  ```
</CodeGroup>

#### 4 — Locking & Unlocking a Door

Next, you can perform the basic action of locking and unlocking the door.

> **`POST`** `/locks/lock_door`
>
> See the [API Reference](/api/locks/lock_door) for details.

#### Unlock a door

<mark>`POST`</mark>
`https://connect.getseam.com/locks/unlock_door`

**Request Body**

| Name       | Type   | Description |
| ---------- | ------ | ----------- |
| device\_id | String |             |

<CodeGroup>
  ```javascript JavaScript theme={null}
  // lock the door
  await seam.locks.lockDoor(someLock.device_id)
  const updatedLock = await seam.locks.get(someLock.device_id)
  console.log(updatedLock.properties.locked) // true

  // unlock the door
  await seam.locks.unlockDoor(someLock.device_id)
  updatedLock = await seam.locks.get(someLock.device_id)
  console.log(updatedLock.properties.locked) // false

  ```

  ```python Python theme={null}
  # lock the door
  seam.locks.lock_door(device_id: some_lock.device_id)
  updated_lock = seam.locks.get(device_id: some_lock.device_id)
  assert updated_lock.properties["locked"] is True

  # Now unlock the door
  seam.locks.unlock_door(device_id: some_lock.device_id)
  updated_lock = seam.locks.get(device_id: some_lock.device_id)
  assert updated_lock.properties["locked"] is False
  ```

  ```ruby Ruby theme={null}
  # lock the door
  seam.locks.lock_door(device_id: some_lock.device_id)
  updated_lock = seam.locks.get(device_id: some_lock.device_id)
  puts updated_lock.properties.locked # true

  # unlock the door

  seam.locks.unlock_door(device_id: some_lock.device_id)
  updated_lock = seam.locks.get(device_id: some_lock.device_id)
  puts updated_lock.properties.locked # false

  ```

  ```php PHP theme={null}
  use Seam\SeamClient;

  $seam = new SeamClient('YOUR_API_KEY');

  $some_lock = $seam->locks->list()[0];

  # unlock the door
  $seam->locks->unlock_door($lock->device_id);
  # lock the door
  $seam->locks->lock_door($lock->device_id);
  ```
</CodeGroup>

#### 5 — Creating Access Codes on 2N Intercoms

2N devices have a directory with residents. These residents can be assigned PIN codes to unlock the door.

Seam maps these residents to [access codes](/low-level-apis/smart-locks/access-codes) and allows you to create and manage them through the Seam API.

<CodeGroup>
  ```javascript JavaScript theme={null}
  // create an ongoing code
  await seam.accessCodes.create({
    device_id: someLock.device_id,
    code: '123456',
    name: 'Personal Access Code',
  })

  // create a timebound code
  await seam.accessCodes.create({
  device_id: someLock.device_id,
  code: '888888',
  name: 'My Temp Access Code',
  starts_at: '2028-11-12T19:23:42+0000',
  ends_at: '2028-11-13T19:23:42+0000',
  })

  // use a device_id as the "device_id" parameter
  await seam.accessCodes.list({
  device_id: someLock.device_id,
  })

  /_
  [
  {
  code: '1988',
  type: 'ongoing',
  status: 'setting',
  created_at: '2022-08-26T12:50:17.858Z',
  access_code_id: '26d6138c-6524-4f3c-ac96-43cc3bea0a8d'
  },
  {
  type: 'timebound',
  code: '888888',
  starts_at: '2028-08-12T19:24:00.000Z',
  ends_at: '2028-08-13T19:24:00.000Z',
  access_code_id: '8c2db4da-b137-4c08-a2c3-d611e6ff91b3',
  }
  ]
  _/

  ```

  ```python Python theme={null}
  # create an ongoing code
  seam.access_codes.create(
      device=some_lock, code="123456", name="Personal Access Code"
  )

  # create a timebound code
  seam.access_codes.create(
      device=some_lock,
      code="888888",
      name="My Temp Access Code",
      starts_at="2028-08-12T19:23:42+0000",
      ends_at="2028-08-13T19:23:42+0000"
  )

  # you can use a device or a device_id as the "device" parameter
  seam.access_codes.list(device=some_lock)
  # [
  #   AccessCode(
  #     access_code_id='af5272b1-2a49-4eb5-9388-2447fc7b5bd1',
  #     type='ongoing',
  #     code='123459'
  #   ),
  #   AccessCode(
  #     access_code_id='8c2db4da-b137-4c08-a2c3-d611e6ff91b3',
  #     type='timebound',
  #     code='888888',
  #     starts_at='2028-08-12T19:24:00.000Z',
  #     ends_at='2028-08-13T19:24:00.000Z',
  #   )
  # ]

  ```

  ```ruby Ruby theme={null}
  # create an ongoing code
  seam.access_codes.create(
    device_id: some_lock.device_id, code: '123456', name: 'Personal Access Code'
  )

  # create a timebound code

  seam.access_codes.create(
  device_id: some_lock.device_id,
  code: '888888',
  name: 'My Temp Access Code',
  starts_at: '2028-08-12T19:23:42+0000',
  ends_at: '2028-08-13T19:23:42+0000'
  )

  seam.access_codes.list(device_id: some_lock.device_id)

  # [<Seam::AccessCode:0x00730

  # code="888888"

  # name="My Temp Access Code"

  # type="time_bound"

  # errors=[]

  # warnings=[]

  # access_code_id="ce2c298c-364f-4b13-aa12-712f3976288e"

  # ends_at=2028-08-13 19:24:00 UTC

  # starts_at=2028-08-12 19:24:00 UTC>, <Seam::AccessCode:0x00758

  # code="123456"

  # name="Personal Access Code"

  # type="ongoing"

  # errors=[]

  # warnings=[]

  # access_code_id="75f49550-fc9b-481a-a158-5bc53ac9bb34">, <Seam::AccessCode:0x00780

  # code="086355"

  # name="some-code2"

  # type="ongoing"

  # errors=[]

  # warnings=[]

  # access_code_id="5243e5f3-528a-4378-ba3c-21447bf844a8">, <Seam::AccessCode:0x007a8

  # code="376525"

  # name="some-code"

  # type="ongoing"

  # errors=[]

  # warnings=[]

  # access_code_id="91a08a3d-a0bb-4ff0-bfb4-ced164353988">]

  ```

  ```php PHP theme={null}

  php
  use Seam\SeamClient;

  $seam = new SeamClient("YOUR_API_KEY");

  $some_lock = $seam->locks->list()[0];
  $seam->access_codes->create(
  device_id: $some_lock->device_id, code: '123456', name: 'Personal Access Code'
  );

  $seam->access_codes->create(
  device_id: $some_lock->device_id,
  name: 'My Temp Access Code',
  code: '888888',
  starts_at: '2028-08-12T19:23:42+0000',
  ends_at: '2028-08-13T19:23:42+0000'
  );

  ```
</CodeGroup>

## Next Steps

Now that you've completed this guide, you can try to connect a real 2N device. To do so, make sure to switch to a non-sandbox workspace and API key as real devices cannot be connected to sandbox workspaces.

In addition, if you'd like to explore other aspects of Seam, here is a list of helpful resources:

* [Yale Getting Started Guide](../yale-locks/get-started-with-yale-locks)
* [August Getting Started Guide](../august-locks/get-started-with-august-locks)
* [Schlage Getting Started Guide](../schlage-locks/get-started-with-schlage-locks)
* [SmartThings Getting Started Guide](../smartthings-hubs-+-devices/get-started-with-smartthings-hubs-+-smart-locks)
* [Minut Getting Started Guide](../minut-sensors/get-started-with-minut-sensors)
* [Receiving webhook](/developer-tools/webhooks) for [device events](/api/events/list)
* [Core Concepts](/core-concepts/overview)

If you have any questions or want to report an issue, email us at [support@seam.co](mailto:support@seam.co).

```
```


# 2N Intercom Systems
Source: https://docs.seam.co/device-and-system-integration-guides/2n-intercom-systems/index

Guide for using 2N® intercom systems with Seam

<img alt="2N logo" />

## Overview

2N produces Internet Protocol (IP) access control systems and elevator communications. Seam integrates with 2N IP intercoms that combine secure audio and video intercoms with an access reader. These standalone devices support direct Session Initiation Protocol (SIP) calls.

2N produces Internet Protocol (IP) intercoms used for access control and communication in residential and commercial properties.

Seam integrates directly with 2N IP-enabled devices to support:

* Secure door lock and unlock actions through Seam’s API
* PIN code programming on devices with keypads

***

## Supported Devices

<DeviceList />

This integration supports all [2N IP intercoms](https://wiki.2n.com/is/en).

For a complete compatibility list, see [2N Supported Devices](https://www.seam.co/manufacturers/2n).

***

## Setup and Integration

Follow the step-by-step [System Setup Instructions](./2n-system-set-up-instructions) to connect your My2N company and devices to Seam.

The setup guide covers:

* Preparing your My2N account
* Enabling HTTP API for each device
* Creating API credentials
* Connecting to Seam through the Connect Webview

<CardGroup>
  <Card title="System Set Up Guide" href="/device-and-system-integration-guides/2n-intercom-systems/2n-system-set-up-instructions" />
</CardGroup>

***

### Device Provider Key

Seam identifies these devices with the `my_2n` device provider key. By default, a [Connect Webview](/core-concepts/connect-webviews) displays all of the stable providers that Seam supports, so your users can connect their 2N devices without you specifying a provider list.

For more details, see [Customize Brands in Connect Webviews](/core-concepts/connect-webviews/customizing-connect-webviews#customize-the-brands-to-display-in-your-connect-webviews).

***

## Where to Order

Find your local 2N distributor using the following page:

<table>
  <thead>
    <tr>
      <th />

      <th />

      <th />

      <th />

      <th />
    </tr>
  </thead>

  <tbody>
    <tr>
      <td />

      <td>
        <strong>Locate Your 2N Distributor</strong>
      </td>

      <td />

      <td>
        <a href="https://www.2n.com/en_GB/how-to-buy/where-to-buy">
          [https://www.2n.com/en\_GB/how-to-buy/where-to-buy](https://www.2n.com/en_GB/how-to-buy/where-to-buy)
        </a>
      </td>

      <td>
        <a href="/images/2n-logo.png">2n-logo.png</a>
      </td>
    </tr>
  </tbody>
</table>


# 33 Lock Setup Guide
Source: https://docs.seam.co/device-and-system-integration-guides/33-lock-devices/33-lock-setup-guide

Connect your 33 Lock smart locks to Seam.

## Overview

This guide walks you through connecting your 33 Lock smart locks to Seam. Your locks must already be physically installed before proceeding.

You need a 33 Lock account, the 33 Lock mobile app, and a compatible 33 Lock Gateway to connect your locks to Seam.

***

## Step 1: Set Up a 33 Lock Account

1. Download the 33 Lock app for [iOS](https://apps.apple.com/us/app/ttlock/id1033046018) or [Android](https://play.google.com/store/apps/details?id=com.tongtongsuo.app\&hl=en_CA).
2. Create an account in the 33 Lock app.

   For details, see the [33 Lock Account Registration guide](https://33lock.notion.site/Account-Registration-13050a6ca1ac81788991ecb923a2cb04#13050a6ca1ac8008b3ece7ed6bbbd094).

***

## Step 2: Add Your Lock and Gateway to the 33 Lock App

1. Add your 33 Lock device to the 33 Lock app.

   For details, see the [33 Lock Lock Management guide](https://33lock.notion.site/Lock-Management-13050a6ca1ac81449b3cf68f8b463267#13650a6ca1ac80ecaf8de356da907a9d).

2. Add the 33 Lock Gateway to the 33 Lock app.

   For details, see the [33 Lock Gateway Management guide](https://33lock.notion.site/Gateway-Management-13050a6ca1ac811f9962fe949fefcc7a).

   33 Lock devices automatically pair with the gateway. Confirm the gateway-to-lock connection strength. For details, see the [33 Lock Gateway Settings guide](https://33lock.notion.site/Gateway-Settings-13550a6ca1ac80f59574f9df40463431#13750a6ca1ac80758293cf85026ef835).

3. In the 33 Lock app, go to the lock settings and enable the **Remote Unlock** feature.

<Info>
  If Seam detects that the Remote Unlock feature is disabled, a warning is added to the device.
</Info>

***

## Step 3: Transfer Ownership (If Applicable)

If an installer set up the 33 Lock device and needs to transfer ownership to another user, see the following 33 Lock guides:

* [Administrators](https://33lock.notion.site/Administrators-13050a6ca1ac81de9c9cdaab35f98002)
* [Transferring Locks](https://33lock.notion.site/Lock-Management-13050a6ca1ac81449b3cf68f8b463267#13650a6ca1ac80c8b96ef07012bc0457)
* [Transferring Gateways](https://33lock.notion.site/Gateway-Management-13050a6ca1ac811f9962fe949fefcc7a#13050a6ca1ac806885c7f44966275cd0)

***

## Step 4: Connect to Seam

Use your 33 Lock account credentials to log in to the [Connect Webview](/core-concepts/connect-webviews) to add your 33 Lock devices to Seam.

<Info>
  The Connect Webview displays the provider as **33 Lock**.
</Info>

***

## Step 5: Verify the Connection

After connecting, verify that your 33 Lock devices appear in your Seam workspace and that each device shows an **online** status.

***

## Troubleshooting

For errors and warnings related to 33 Lock devices, see [Troubleshooting](/device-and-system-integration-guides/ttlock-locks/index#troubleshooting) in the TTLock-compatible device integration guide.

### Devices not appearing after connecting

* Verify that your 33 Lock devices are added to the 33 Lock app and connected to a 33 Lock Gateway.
* Confirm the gateway is online and paired with the lock.

### Remote Unlock warning on device

* Open the 33 Lock app, go to the lock settings, and enable the **Remote Unlock** feature.


# Get started with 33 Lock devices
Source: https://docs.seam.co/device-and-system-integration-guides/33-lock-devices/get-started-with-33-lock-devices

Learn how to connect and control 33 Lock smart locks with the Seam API.

## Overview

Seam provides a universal API to connect and control many brands of IoT devices and systems, including smart locks, access control systems (ACSs), thermostats, and noise sensors.

This guide gives you a rapid introduction to connecting and controlling your [33 Lock device](./) using the Seam API. For application developers, you can use the Seam API in your app, and your users can authorize your app to control their devices using Seam.

For detailed information about the 33 Lock devices that Seam supports, see our [33 Lock Supported Devices page](https://www.seam.co/manufacturers/33-lock).

To learn more about other IoT device and system brands that Seam supports—such as Yale, Schlage, Google Nest, and many more—visit our [integration page](https://www.seam.co/supported-devices-and-systems).

<Check>
  This guide shows you how to install a Seam SDK and then control your 33 Lock device using the Seam API.

  Another easy way to learn about what you can do with the Seam API is to explore the [interactive Seam CLI](/core-concepts/seam-console/seam-online-cli), which you can access from directly within the [Seam Console](/core-concepts/seam-console).

  :arrow\_forward: [Go to the Seam Console!](https://console.seam.co/)
</Check>

***

## Step 1: Install a Seam SDK

Seam provides client libraries for many languages, including JavaScript, Python, Ruby, PHP, and others, as well as a Postman collection and an [OpenAPI](https://connect.getseam.com/openapi.json) spec.

* JavaScript / TypeScript ([npm](https://www.npmjs.com/package/seam), [GitHub](https://github.com/seamapi/javascript))
* Python ([pip](https://pypi.org/project/seam/), [GitHub](https://github.com/seamapi/python))
* Ruby Gem ([rubygem](https://rubygems.org/gems/seam), [GitHub](https://github.com/seamapi/ruby))
* PHP ([packagist](https://packagist.org/packages/seamapi/seam), [GitHub](https://github.com/seamapi/php))
* C# ([nuget](https://www.nuget.org/packages/Seam), [GitHub](https://github.com/seamapi/csharp))

First, install a Seam SDK, as follows:

<Tabs>
  <Tab title="JavaScript">
    ```bash theme={null}
    npm i seam
    ```
  </Tab>

  <Tab title="Python">
    ```bash theme={null}
    pip install seam
    # For some development environments, use pip3 in this command instead of pip.
    ```
  </Tab>

  <Tab title="Ruby">
    ```bash theme={null}
    bundle add seam
    ```
  </Tab>

  <Tab title="PHP">
    ```bash theme={null}
    composer require seamapi/seam
    ```
  </Tab>

  <Tab title="C#">
    Install using [nuget](https://www.nuget.org/packages/Seam).
  </Tab>
</Tabs>

Next, go to [https://console.seam.co/](https://console.seam.co/) and [sign up for Seam](/core-concepts/seam-console#create-a-seam-account) to get your [API key](/core-concepts/authentication/api-keys).

Then, export your API key as an environment variable.

```bash theme={null}
$ export SEAM_API_KEY=seam_test2bMS_94SrGUXuNR2JmJkjtvBQDg5c
```

<Info>
  This guide uses a [sandbox
  workspace](/core-concepts/workspaces#sandbox-workspaces).
  You can only connect virtual devices and systems in this type of workspace. If
  you want to connect a real 33 Lock device, use a [non-sandbox
  workspace](/core-concepts/workspaces#production-workspaces)
  and API key.
</Info>

***

## Step 2: Link your 33 Lock with Seam

To control your 33 Lock device using the Seam API, you must first authorize your Seam workspace to connect to your associated TTLock account. If your application needs to connect to your users' TTLock accounts, Seam provides fully-embedded, [customizable](/core-concepts/connect-webviews/customizing-connect-webviews) client-side [Connect Webviews](/core-concepts/connect-webviews) to collect their authorization securely. These user-friendly pre-built authorization flows walk your users through the process of granting your Seam workspace permission to control their 33 Lock devices. The Connect Webview presents a flow that prompts your users to enter their credentials for their TTLock account.

In this guide, you create a Connect Webview object. Then, you display the graphical component of the created Connect Webview and enter a set of sample credentials to connect a sandbox TTLock account.

<Check>
  This guide shows you how to create a Connect Webview programmatically using the Seam API.

  The [Seam Console](/core-concepts/seam-console) provides another easy way to connect devices to your Seam workspace.

  Go to [https://console.seam.co/](https://console.seam.co/). On the **Devices** page, click **+ Add Devices**. Then, see [Authorize your workspace](#authorize-your-workspace) in this guide to complete the Connect Webview authorization flow.
</Check>

### Create a Connect Webview

Create a `connect_webview` object and then note the returned URL.

**Code:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  import { Seam } from 'seam'

  const seam = new Seam() // Seam automatically uses your exported SEAM_API_KEY.

  const connectWebview = await seam.connectWebviews.create()

  console.log(connectWebview.login_successful) // false

  // Use the returned Connect Webview URL to display
  // the Connect Webview authorization flow to your user.
  console.log(connectWebview.url)
  ```

  ```bash cURL theme={null}
  curl -X 'POST' \
    'https://connect.getseam.com/connect_webviews/create' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d '{}' | jq -r '"Login Successful (false): " + (.connect_webview.login_successful | tostring),
    "URL: " + .connect_webview.url'
    # Use the returned Connect Webview URL to display
    # the Connect Webview authorization flow to your user.
  ```

  ```python Python theme={null}
  from seam import Seam

  seam = Seam()  # Seam automatically uses your exported SEAM_API_KEY.

  connect_webview = seam.connect_webviews.create()

  assert connect_webview.login_successful is False

  # Use the returned Connect Webview URL to display
  # the Connect Webview authorization flow to your user.
  print(connect_webview.url)
  ```

  ```ruby Ruby theme={null}
  require "seam"

  seam = Seam.new() # Seam automatically uses your exported SEAM_API_KEY.

  connect_webview = seam.connect_webviews.create()

  puts connect_webview.login_successful # false

  # Use the returned Connect Webview URL to display
  # the Connect Webview authorization flow to your user.
  puts connect_webview.url
  ```

  ```php PHP theme={null}
  <?php
  require 'vendor/autoload.php';

  $seam = new Seam\SeamClient(); // Seam automatically uses your exported SEAM_API_KEY.

  $connect_webview = $seam->connect_webviews->create();

  echo $connect_webview->login_successful ? 'true' : 'false', "\n"; // false

  // Use the returned Connect Webview URL to display
  // the Connect Webview authorization flow to your user.
  echo $connect_webview->url;
  ```

  ```csharp C# theme={null}
  using Seam.Client;

  var seam = new SeamClient(apiToken: SEAM_API_KEY);

  var connectWebview = seam.ConnectWebviews.Create();

  Console.WriteLine(connectWebview.LoginSuccessful); // False

  // Use the returned Connect Webview URL to display
  // the Connect Webview authorization flow to your user.
  Console.WriteLine(connectWebview.Url);
  ```
</CodeGroup>

**Output:**

<CodeGroup>
  ```json JavaScript theme={null}
  false
  https://connect.getseam.com/connect_webviews/view?connect_webview_id=12345678-1234-1234-1234-123456789012&auth_token=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
  ```

  ```json cURL theme={null}
  Login Successful (false): false
  https://connect.getseam.com/connect_webviews/view?connect_webview_id=12345678-1234-1234-1234-123456789012&auth_token=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
  ```

  ```json Python theme={null}
  https://connect.getseam.com/connect_webviews/view?connect_webview_id=12345678-1234-1234-1234-123456789012&auth_token=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
  ```

  ```json Ruby theme={null}
  false
  https://connect.getseam.com/connect_webviews/view?connect_webview_id=12345678-1234-1234-1234-123456789012&auth_token=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
  ```

  ```json PHP theme={null}
  false
  https://connect.getseam.com/connect_webviews/view?connect_webview_id=12345678-1234-1234-1234-123456789012&auth_token=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
  ```

  ```json C# theme={null}
  False
  https://connect.getseam.com/connect_webviews/view?connect_webview_id=12345678-1234-1234-1234-123456789012&auth_token=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
  ```
</CodeGroup>

***

### Authorize your workspace

In a web browser, go to the URL that the Connect Webview object returned.

For application developers, you can redirect your user to this Connect Webview URL so that they can authorize your app to control their devices using Seam. We even provide a prebuilt [Connect Account Button](/ui-components/overview/react-components/connect-account-button) within our suite of [Seam Components](/ui-components/overview) that help you build your device management flow.

<Check>
  Because you're using a sandbox workspace, you can connect Seam's test TTLock
  account. We provide [virtual devices](../ttlock-locks/ttlock-sample-data)
  for each of the brands that we support. These sandbox devices and systems
  enable you to test your app with devices from multiple brands without the need
  to own all the corresponding physical devices.
</Check>

Complete the Connect Webview authorization flow by entering the following [TTLock sandbox account](../ttlock-locks/ttlock-sample-data) credentials:

* **Email:** [jane@example.com](mailto:jane@example.com)
* **Password:** 1234

Confirm that authorization through the Connect Webview was successful by querying its status.

**Code:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  const updatedConnectWebview = await seam.connectWebviews.get({
    connect_webview_id: connectWebview.connect_webview_id,
  })

  console.log(updatedConnectWebview.login_successful) // true
  ```

  ```bash cURL theme={null}
  curl -X 'POST' \
    'https://connect.getseam.com/connect_webviews/get' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d "{
    \"connect_webview_id\": \"${connect_webview_id}\"
  }" | jq -r '"Login Successful (true): " + (.connect_webview.login_successful | tostring)'
  ```

  ```python Python theme={null}
  updated_connect_webview = seam.connect_webviews.get(connect_webview.connect_webview_id)

  assert updated_connect_webview.login_successful is True # True
  ```

  ```ruby Ruby theme={null}
  updated_connect_webview = seam.connect_webviews.get(
    connect_webview_id: connect_webview.connect_webview_id
  )

  puts updated_connect_webview.login_successful # true
  ```

  ```php PHP theme={null}
  $updated_connect_webview = $seam->connect_webviews->get(
    connect_webview_id: $connect_webview->connect_webview_id
  );

  echo $updated_connect_webview->login_successful ? 'true' : 'false', "\n"; // true
  ```

  ```csharp C# theme={null}
  var updatedConnectWebview = seam.ConnectWebviews.Get(
    connectWebviewId: connectWebview.connectWebviewId
  );

  Console.WriteLine(updatedConnectWebview.LoginSuccessful); // True
  ```
</CodeGroup>

**Output:**

<CodeGroup>
  ```json JavaScript theme={null}
  true
  ```

  ```json cURL theme={null}
  Login Successful (true): true
  ```

  ```json Python theme={null}
  True
  ```

  ```json Ruby theme={null}
  true
  ```

  ```json PHP theme={null}
  true
  ```

  ```json C# theme={null}
  True
  ```
</CodeGroup>

***

## Step 3: Retrieve 33 Lock devices

When you link a TTLock account (for your 33 Lock devices) with Seam, we create a `device` object to represent each 33 Lock lock in your account. You can then retrieve these 33 Lock devices using the [List Devices](/api/devices/list) and [Get Device](/api/devices/get) endpoints.

The Seam API exposes each device's properties, such as the door lock status, power status, capabilities, and so on.

**Code:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  // Retrieve all devices, filtered by manufacturer,
  // which is one of several filters that list() supports.
  const allTtlockLocks = await seam.devices.list({ manufacturer: 'ttlock' })

  // Select the first device as an example.
  const frontDoor = allTtlockLocks[0]

  // Inspect specific properties.
  console.log(frontDoor.properties.online) // true
  console.log(frontDoor.properties.locked) // true

  // View the entire returned device object.
  console.log(frontDoor)
  ```

  ```bash cURL theme={null}
  # Retrieve all devices, filtered by manufacturer, which is
  # one of several filters that the list endpoint supports.
  all_ttlock_locks=$(
    # Use GET or POST.
    curl -X 'GET' \
      'https://connect.getseam.com/devices/list' \
      -H 'accept: application/json' \
      -H "Authorization: Bearer ${SEAM_API_KEY}" \
      -H 'Content-Type: application/json' \
      -d '{
      "manufacturer": "ttlock"
    }')

  # Select the first device as an example.
  front_door=$(jq -r '.devices[0]' <<< ${all_ttlock_locks})

  # Inspect specific properties.
  echo $(jq -r '"Online (true): " + (.properties.online | tostring)' <<< ${front_door})
  echo $(jq -r '"Locked (true): " + (.properties.locked | tostring)' <<< ${front_door})

  # View the entire returned device object.
  echo ${front_door}
  ```

  ```python Python theme={null}
  # Retrieve all devices, filtered by manufacturer,
  # which is one of several filters that list() supports.
  all_ttlock_locks = seam.devices.list(manufacturer="ttlock")

  # Select the first device as an example.
  front_door = all_ttlock_locks[0]

  # Inspect specific properties.
  assert front_door.properties["online"] is True # True
  assert front_door.properties["locked"] is True # True

  # View the entire returned device object.
  pprint(front_door)
  ```

  ```ruby Ruby theme={null}
  # Retrieve all devices, filtered by manufacturer,
  # which is one of several filters that list() supports.
  all_ttlock_locks = seam.devices.list(manufacturer: "ttlock")

  # Select the first device as an example.
  front_door = all_ttlock_locks[0]

  # Inspect specific properties.
  puts front_door.properties.online # true
  puts front_door.properties.locked # true

  # View the entire returned device object.
  puts front_door.inspect
  ```

  ```php PHP theme={null}
  // Retrieve all devices, filtered by manufacturer,
  // which is one of several filters that list() supports.
  $all_ttlock_locks = $seam->devices->list(manufacturer: "ttlock");

  // Select the first device as an example.
  $front_door = $all_ttlock_locks[0];

  // Inspect specific properties.
  echo $front_door->properties->online ? 'true' : 'false', "\n"; // true
  echo $front_door->properties->locked ? 'true' : 'false', "\n"; // true

  // View the entire returned device object.
  echo json_encode($front_door, JSON_PRETTY_PRINT);
  ```

  ```csharp C# theme={null}
  // Retrieve all devices, filtered by manufacturer,
  // which is one of several filters that list() supports.
  var allTtlockLocks = seam.Devices.List(
    manufacturer: Seam.Api.Devices.ListRequest.ManufacturerEnum.Ttlock
  );

  // Select the first device as an example.
  Device frontDoor = allTtlockLocks[0];

  // Inspect specific properties.
  Console.WriteLine(frontDoor.Properties.Online); // true
  Console.WriteLine(frontDoor.Properties.Locked); // true

  // View the entire returned device object.
  Console.WriteLine(frontDoor);
  ```
</CodeGroup>

**Output:**

<CodeGroup>
  ```json JavaScript theme={null}
  true
  true
  {
    device_id: '11111111-1111-1111-1111-444444444444',
    display_name: 'Lock 1',
    workspace_id: '00000000-0000-0000-0000-000000000000',
    connected_account_id: '11111111-1111-1111-1111-222222222222',
    created_at: '2024-05-29T20:08:48.878Z',
    properties: {
      manufacturer: 'ttlock',
      online: true,
      locked: true,
      battery: {
        level: 0.9999532347993827,
        status: 'full'
      },
      ...
    },
    can_remotely_unlock: true,
    ...
  }
  ```

  ```json cURL theme={null}
  Online (true): true
  Locked (true): true
  {
    "device_id": "11111111-1111-1111-1111-444444444444",
    "display_name": "Lock 1",
    "workspace_id": "00000000-0000-0000-0000-000000000000",
    "connected_account_id": "11111111-1111-1111-1111-222222222222",
    "created_at": "2024-05-29T20:08:48.878Z",
    "properties": {
      "manufacturer": "ttlock",
      "locked": true,
      "online": true,
      "battery": {
        "level": 0.9999532347993827,
        "status": "full"
      },
      ...
    },
    "can_remotely_unlock": true,
    ...
  }
  ```

  ```json Python theme={null}
  Device(
    device_id='11111111-1111-1111-1111-444444444444',
    display_name='Lock 1',
    workspace_id='00000000-0000-0000-0000-000000000000'
    connected_account_id='11111111-1111-1111-1111-222222222222',
    created_at='2024-05-29T20:08:48.878Z',
    properties={
      'manufacturer': 'ttlock',
      'online': True,
      'locked': True,
      'battery': {
        'level': 0.9999532347993827,
        'status': 'full'
      },
      ...
    }
    can_remotely_unlock=True,
    ...
  )
  ```

  ```json Ruby theme={null}
  true
  true
  <
    Seam::Device:0x00438
      device_id="11111111-1111-1111-1111-444444444444"
      display_name="Lock 1"
      workspace_id="00000000-0000-0000-0000-000000000000"
      connected_account_id="11111111-1111-1111-1111-222222222222"
      created_at=2024-05-29 20:08:48.878 UTC
      properties={
        "manufacturer"=>"ttlock",
        "online"=>true,
        "locked"=>true,
        "battery"=>{
          "level"=>0.9999532347993827,
          "status"=>"full"
        },
        ...
      }
      can_remotely_unlock=true
      ...
  >
  ```

  ```json PHP theme={null}
  true
  true
  {
    "device_id": "11111111-1111-1111-1111-444444444444",
    "display_name": "Lock 1",
    "workspace_id": "00000000-0000-0000-0000-000000000000"
    "connected_account_id": "11111111-1111-1111-1111-222222222222",
    "created_at": "2024-05-29T20:08:48.878Z",
    "properties": {
      "manufacturer": "ttlock",
      "online": true,
      "locked": true,
      "battery": {
        "level": 0.9999532347993827,
        "status": "full"
      },
      ...
    },
    "can_remotely_unlock": true,
    ...
  }
  ```

  ```json C# theme={null}
  True
  True
  {
    "device_id": "11111111-1111-1111-1111-444444444444",
    "display_name": "Lock 1",
    "workspace_id": "00000000-0000-0000-0000-000000000000",
    "connected_account_id": "11111111-1111-1111-1111-222222222222",
    "created_at": "2024-05-29T20:08:48.878Z",
    "properties": {
      "manufacturer": "ttlock",
      "online": true,
      "locked": true,
      "battery": {
        "level": 0.9999532,
        "status": "full"
      },
      ...
    },
    "can_remotely_unlock": true,
    ...
  }
  ```
</CodeGroup>

***

## Step 4: Control your 33 Lock device

Next, you can use the Seam API to control your lock.

Each device that you connect to Seam has a specific set of capabilities. These capabilities define the Seam API actions that you can use, such as [remote unlock actions](/low-level-apis/smart-locks/lock-and-unlock), [programming access codes](/low-level-apis/smart-locks/access-codes), and so on. Seam's intuitive and granular [capability flags](/capability-guides/device-and-system-capabilities#capability-flags) inform your application about what features and behaviors each device supports. Notice the capability flags within the code samples in this guide.

Try out the following actions on your 33 Lock device:

* [ ] [Unlock your lock](#unlock-your-lock)
* [ ] [Program access codes on your lock](#program-access-codes-on-your-lock)

### Unlock your lock

To unlock a door, use the [Unlock Door](/api/locks/unlock_door) endpoint. Specify the device that you want to unlock by including the `device_id` in the request body. This endpoint returns an [action attempt](/core-concepts/action-attempts) to track the progress of the unlock operation.

**Code:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  // Confirm that the device can remotely unlock.
  // You're using a capability flag here!
  if (frontDoor.can_remotely_unlock) {
    // Perform the unlock operation
    // and return an action attempt.
    const actionAttempt = await seam.locks.unlockDoor({
      device_id: frontDoor.device_id,
    })
  }
  ```

  ```bash cURL theme={null}
  # Confirm that the device can remotely unlock.
  # You're using a capability flag here!
  if  $(jq -r '.can_remotely_lock' <<< ${front_door}); then \
    # Perform the unlock operation
    # and return an action attempt.
    curl -X 'POST' \
      'https://connect.getseam.com/locks/unlock_door' \
      -H 'accept: application/json' \
      -H "Authorization: Bearer ${SEAM_API_KEY}" \
      -H 'Content-Type: application/json' \
      -d "{
        \"device_id\": \"$(jq -r '.device_id' <<< ${front_door})\"
    }";
  fi
  ```

  ```python Python theme={null}
  # Confirm that the device can remotely unlock.
  # You're using a capability flag here!
  if front_door.can_remotely_unlock:
    # Perform the unlock operation
    # and return an action attempt.
    action_attempt=seam.locks.unlock_door(device_id=front_door.device_id)
  ```

  ```ruby Ruby theme={null}
  # Confirm that the device can remotely unlock.
  # You're using a capability flag here!
  if (front_door.can_remotely_unlock)
    # Perform the unlock operation
    # and return an action attempt.
    action_attempt = seam.locks.unlock_door(device_id: front_door.device_id)
  end
  ```

  ```php PHP theme={null}
  // Confirm that the device can remotely unlock.
  // You're using a capability flag here!
  if ($front_door->can_remotely_unlock) {
    // Perform the unlock operation
    // and return an action attempt.
    $action_attempt = $seam->locks->unlock_door(device_id: $front_door->device_id);
  }
  ```

  ```csharp C# theme={null}
  // Confirm that the device can remotely unlock.
  // You're using a capability flag here!
  if (frontDoor.CanRemotelyUnlock == true) {
    // Perform the unlock operation
    // and return an action attempt.
    ActionAttempt actionAttempt = seam.Locks.UnlockDoor(deviceId: frontDoor.DeviceId);
  }
  ```
</CodeGroup>

**Output:**

<CodeGroup>
  ```json JavaScript theme={null}
  {
    "actionAttempt": {
      "status": "success",
      "action_attempt_id": "11111111-2222-3333-4444-555555555555",
      "action_type": "UNLOCK_DOOR",
      "result": {},
      "error": null
    }
  }
  ```

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

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

  ```json Ruby theme={null}
  <Seam::ActionAttempt:0x00438
    status="pending"
    action_type="UNLOCK_DOOR"
    action_attempt_id="11111111-2222-3333-4444-555555555555"
    result=nil>
  ```

  ```json PHP theme={null}
  {
    "action_attempt_id": "11111111-2222-3333-4444-555555555555",
    "action_type": "UNLOCK_DOOR",
    "error": null,
    "result": {},
    "status": "success"
  }
  ```

  ```json C# theme={null}
  {
    "status": "pending",
    "action_type": "UNLOCK_DOOR",
    "action_attempt_id": "11111111-2222-3333-4444-555555555555"
  }
  ```
</CodeGroup>

You can track the status of the unlock operation to confirm that the device unlocked successfully. Query the `locked` status of the device, [retrieve the action attempt](/api/action_attempts/get) by ID, or look for a [`lock.unlocked` event](/api/locks/events#lock-unlocked).

To query the `locked` status of the device:

**Code:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  // Get the device by ID.
  const updatedFrontDoor = await seam.devices.get({
    device_id: frontDoor.device_id,
  })

  // Inspect the locked property to confirm
  // that the unlock operation was successful.
  console.log(updatedFrontDoor.properties.locked) // false
  ```

  ```bash cURL theme={null}
  # Get the device by ID.
  updated_front_door=$(
    # Use GET or POST.
    curl -X 'GET' \
      'https://connect.getseam.com/devices/get' \
      -H 'accept: application/json' \
      -H "Authorization: Bearer ${SEAM_API_KEY}" \
      -H 'Content-Type: application/json' \
      -d "{
        \"device_id\": \"$(jq -r '.device_id' <<< ${front_door})\"
    }")

  # Inspect the locked property to confirm
  # that the unlock operation was successful.
  echo $(jq -r '"Locked (false): " + (.device.properties.locked | tostring)' <<< ${updated_front_door})
  ```

  ```python Python theme={null}
  # Get the device by ID.
  updated_front_door = seam.devices.get(device_id=front_door.device_id)

  # Inspect the locked property to confirm
  # that the unlock operation was successful.
  assert updated_front_door.properties["locked"] is False # False
  ```

  ```ruby Ruby theme={null}
  # Get the device by ID.
  updated_front_door = seam.devices.get(device_id: front_door.device_id)

  # Inspect the locked property to confirm
  # that the unlock operation was successful.
  puts updated_front_door.properties.locked # false
  ```

  ```php PHP theme={null}
  // Get the device by ID.
  $updated_front_door = $seam->devices->get(device_id: $front_door->device_id);

  // Inspect the locked property to confirm
  // that the unlock operation was successful.
  echo $updated_front_door->properties->locked ? 'true' : 'false', "\n"; // false
  ```

  ```csharp C# theme={null}
  // Get the device by ID.
  Device updatedFrontDoor = seam.Devices.Get(
    deviceId: frontDoor.DeviceId
  );

  // Inspect the locked property to confirm
  // that the unlock operation was successful.
  Console.WriteLine(updatedFrontDoor.Properties.Locked); // false
  ```
</CodeGroup>

**Output:**

<CodeGroup>
  ```json JavaScript theme={null}
  false
  ```

  ```json cURL theme={null}
  Locked (false): false
  ```

  ```json Python theme={null}
  False
  ```

  ```json Ruby theme={null}
  false
  ```

  ```json PHP theme={null}
  false
  ```

  ```json C# theme={null}
  False
  ```
</CodeGroup>

<Check>
  Now that you have successfully unlocked your lock, you can use the [Lock
  Door](/api/locks/lock_door) endpoint to lock it
  again.
</Check>

***

### Program access codes on your lock

You can use the Seam API to program [online access codes](/low-level-apis/smart-locks/access-codes) on 33 Lock devices. These devices have an integrated keypad. Lock users can then enter these access codes using the keypad to unlock the lock.

The Seam API makes it easy to program both [ongoing](/low-level-apis/smart-locks/access-codes#ongoing-access-codes) and [time-bound](/low-level-apis/smart-locks/access-codes#time-bound-access-codes) online access codes.

**Code:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  // Confirm that the device supports online access codes.
  // Here's another capability flag!
  if (updatedFrontDoor.can_program_online_access_codes) {
    // Create an ongoing online access code.
    await seam.accessCodes.create({
      device_id: updatedFrontDoor.device_id,
      name: 'my ongoing code',
      code: '1234',
    })
    // Create a time-bound online access code.
    await seam.accessCodes.create({
      device_id: updatedFrontDoor.device_id,
      name: 'my time-bound code',
      starts_at: '2025-01-01T16:00:00Z',
      ends_at: '2025-01-22T12:00:00Z',
      code: '2345',
    })
    // List all access codes for this device.
    const accessCodes = await seam.accessCodes.list({
      device_id: updatedFrontDoor.device_id,
    })
    console.log(accessCodes)
  }
  ```

  ```bash cURL theme={null}
  # Confirm that the device supports online access codes.
  # Here's another capability flag!
  if  $(jq -r '.device.can_program_online_access_codes' <<< ${updated_front_door}); then \
    # Create an ongoing online access code.
    curl -X 'POST' \
      'https://connect.getseam.com/access_codes/create' \
      -H 'accept: application/json' \
      -H "Authorization: Bearer ${SEAM_API_KEY}" \
      -H 'Content-Type: application/json' \
      -d "{
        \"device_id\": \"$(jq -r '.device.device_id' <<< ${updated_front_door})\",
        \"name\": \"my ongoing code\",
        \"code\": \"1234\"
    }"
    # Create a time-bound online access code.
    curl -X 'POST' \
      'https://connect.getseam.com/access_codes/create' \
      -H 'accept: application/json' \
      -H "Authorization: Bearer ${SEAM_API_KEY}" \
      -H 'Content-Type: application/json' \
      -d "{
        \"device_id\": \"$(jq -r '.device.device_id' <<< ${updated_front_door})\",
        \"name\": \"my time-bound code\",
        \"starts_at\": \"2025-01-01T16:00:00Z\",
        \"ends_at\": \"2025-01-22T12:00:00Z\",
        \"code\": \"2345\"
    }"
    # List all access codes for this device.
    access_codes=$(
    # Use GET or POST.
    curl -X 'GET' \
      'https://connect.getseam.com/access_codes/list' \
      -H 'accept: application/json' \
      -H "Authorization: Bearer ${SEAM_API_KEY}" \
      -H 'Content-Type: application/json' \
      -d "{
        \"device_id\": \"$(jq -r '.device.device_id' <<< ${updated_front_door})\"
    }")
    echo ${access_codes};
  fi
  ```

  ```python Python theme={null}
  # Confirm that the device supports online access codes.
  # Here's another capability flag!
  if updated_front_door.can_program_online_access_codes:
    # Create an ongoing online access code.
    seam.access_codes.create(
      device_id = updated_front_door.device_id,
      name = "my ongoing code",
      code = "1234"
    )
    # Create a time-bound online access code.
    seam.access_codes.create(
      device_id = updated_front_door.device_id,
      name = "my time-bound code",
      starts_at = "2025-01-01T16:00:00Z",
      ends_at = "2025-01-22T12:00:00Z",
      code = "2345"
    )
    # List all access codes for this device.
    access_codes = seam.access_codes.list(
      device_id = updated_front_door.device_id
    )
    pprint(access_codes)
  ```

  ```ruby Ruby theme={null}
  # Confirm that the device supports online access codes.
  # Here's another capability flag!
  if (updated_front_door.can_program_online_access_codes)
    # Create an ongoing online access code.
    seam.access_codes.create(
      device_id: updated_front_door.device_id,
      name: "my ongoing code",
      code: "1234"
    )
    # Create a time-bound online access code.
    seam.access_codes.create(
      device_id: updated_front_door.device_id,
      name: "my time-bound code",
      starts_at: "2025-01-01T16:00:00Z",
      ends_at: "2025-01-22T12:00:00Z",
      code: "2345"
    )
    # List all access codes for this device.
    access_codes = seam.access_codes.list(
      device_id: updated_front_door.device_id
    )
    puts access_codes.inspect
  end
  ```

  ```php PHP theme={null}
  // Confirm that the device supports online access codes.
  // Here's another capability flag!
  if ($updated_front_door->can_program_online_access_codes) {
    // Create an ongoing online access code.
    $seam->access_codes->create(
      device_id: $updated_front_door->device_id,
      name: "my ongoing code",
      code: "1234"
    );
    // Create a time-bound online access code.
    $seam->access_codes->create(
      device_id: $updated_front_door->device_id,
      name: "my time-bound code",
      starts_at:  "2025-01-01T16:00:00Z",
      ends_at: "2025-01-22T12:00:00Z",
      code: "2345"
    );
    // List all access codes for this device.
    $access_codes = $seam->access_codes->list(
      device_id: $updated_front_door->device_id
    );
    echo json_encode($access_codes, JSON_PRETTY_PRINT);
  }
  ```

  ```csharp C# theme={null}
  // Confirm that the device supports online access codes.
  // Here's another capability flag!
  if (updatedFrontDoor.CanProgramOnlineAccessCodes == true) {
    // Create an ongoing online access code.
    seam.AccessCodes.Create(
      deviceId: updatedFrontDoor.DeviceId,
      name: "my ongoing code",
      code: "1234"
    );
    // Create a time-bound online access code.
    seam.AccessCodes.Create(
      deviceId: updatedFrontDoor.DeviceId,
      name: "my time-bound code",
      startsAt: "2025-01-01T16:00:00Z",
      endsAt: "2025-01-22T12:00:00Z",
      code: "2345"
    );
    // List all access codes for this device.
    var accessCodes = seam.AccessCodes.List(
      deviceId: updatedFrontDoor.DeviceId
    );
    foreach (var accessCode in accessCodes)
    {
      Console.WriteLine(accessCode);
    }
  }
  ```
</CodeGroup>

**Output:**

<CodeGroup>
  ```json JavaScript theme={null}
  [
    {
      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-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',
      ...
    }
  ]
  ```

  ```json cURL theme={null}
  {
    "access_codes": [
      {
        "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-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
  }
  ```

  ```json Python theme={null}
  [
    AccessCode(
      access_code_id='11111111-1111-1111-1111-555555555555',
      device_id='11111111-1111-1111-1111-444444444444',
      type='ongoing',
      code='1234',
      name='my ongoing code',
      ...
    )
    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',
      ...
    )
  ]
  ```

  ```json Ruby theme={null}
  [
    <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"
      ...
    >,
    <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
      ...
    >
  ]
  ```

  ```json PHP theme={null}
  [
    {
      "access_code_id": "11111111-1111-1111-1111-555555555555",
      "device_id": "11111111-1111-1111-1111-444444444444",
      "name": "my ongoing code",
      "type": "ongoing",
      "code": "1234",
      ...
    },
    {
      "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",
    }
  ]
  ```

  ```json C# theme={null}
  {
    "type": "ongoing",
    "access_code_id": "11111111-1111-1111-1111-555555555555",
    "device_id": "11111111-1111-1111-1111-444444444444",
    "name": "my ongoing code",
    "code": "1234",
    ...
  }
  {
    "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",
    ...
  }
  ```
</CodeGroup>

***

## Step 5: Connect a real 33 Lock device

Now that you have learned the basics of using the Seam API, you can connect and control a real 33 Lock device. To do so, make sure to switch to a [non-sandbox workspace](/core-concepts/workspaces#production-workspaces) and [API key](/core-concepts/authentication/api-keys).

For more details about setting up your real 33 Lock device, see the [33 Lock locks integration guide](./).

***

## Step 6: Build your application!

Seam makes it easy to develop your application. In addition to the robust Seam API and the wide variety of programming languages that our SDKs support, we also provide a suite of [Seam Components](/ui-components/overview). These prebuilt UI components help you to build your device management flow.

For example, you can use the [Device Table Seam Component](/ui-components/overview/react-components/device-table) to display a list of devices and to identify all devices with issues. You can use the [Device Details Seam Component](/ui-components/overview/react-components/device-details) to display a device's properties, settings, and issues, as well as to enable your users to perform actions based on each device's capabilities. The [Access Code Details Seam Component](/ui-components/overview/react-components/access-code-details) provides a similar display and actions for access codes.

Seam Components use a responsive design to fit seamlessly on any screen size. They also provide device debugging flows to help your users.

To learn about all the Seam Components that we provide, see [Seam Components](/ui-components/overview).

***

## Next steps

Now that you've completed this getting started guide for 33 Lock devices, you can learn more about what you can do with the Seam API.

* [ ] **Explore**\
  See the [other devices and system integrations](/device-and-system-integration-guides) that Seam supports.
* [ ] **Learn**\
  Read about Seam [concepts](/core-concepts/overview) and the [device and system capabilities ](/capability-guides/device-and-system-capabilities)that Seam supports.
* [ ] **Use Seam Components**\
  Find out about [Seam Components](/ui-components/overview), which are prebuilt UI components for building your device management flow.
* [ ] **Use webhooks**\
  Learn how to use [webhooks](/developer-tools/webhooks) as an efficient way to receive device events.
* [ ] **Find out more**\
  Explore the other types of devices and systems that you can control with Seam, including [access control systems](/low-level-apis/access-systems), [thermostats](/capability-guides/thermostats), and [noise sensors](/capability-guides/noise-sensors).
* [ ] **Develop for mobile access**\
  Learn about Seam's [mobile access solution](/capability-guides/mobile-access).

<Info>
  If you have any questions or want to report an issue, email us at
  [support@seam.co](mailto:support@seam.co).
</Info>

***

## Quick links

<CardGroup>
  <Card title="Get an API Key (free)" href="https://console.seam.co/">
    Sign up for the Seam Console and get your API keys. →
  </Card>

  <Card title="Contact Sales" href="https://www.seam.co/contact-us">
    Got a project or a specific question? Contact our team to get answers. →
  </Card>
</CardGroup>


# 33 Lock Devices
Source: https://docs.seam.co/device-and-system-integration-guides/33-lock-devices/index

Guide for using 33 Lock smart locks with Seam

<img alt="33 Lock logo" />

## Overview

[33 Lock](https://www.33lock.com/) is a Vancouver-based smart lock company that is focused on delivering innovative access solutions for hotels, motels, resorts, hostels, and multifamily properties. These offerings include the IntelliBolt, IntelliLever, IntelliMortise, and IntelliReader. All of these devices have an integrated keypad.

***

## Supported Devices

<DeviceList />

This integration works with all 33 Lock locks. Note that 33 Lock devices require you to register for a free [33 Lock account](https://33lock.notion.site/Account-Registration-13050a6ca1ac81788991ecb923a2cb04#13050a6ca1ac8008b3ece7ed6bbbd094) and to connect the locks to a [compatible 33 Lock Gateway](https://33lock.notion.site/Gateway-Management-13050a6ca1ac811f9962fe949fefcc7a#13650a6ca1ac80d599e7edf5ffc171cf).

For detailed information about the 33 Lock devices that Seam supports, see our [33 Lock Supported Devices page](https://www.seam.co/manufacturers/33-lock).

***

## Supported Features

We support the following features:

* [Triggering web lock and unlock actions](/low-level-apis/smart-locks/lock-and-unlock)
* [Programming access codes](/low-level-apis/smart-locks/access-codes)

***

### Device Provider Key

Seam identifies these devices with the `thirty_three_lock` or `ttlock` device provider keys. By default, a [Connect Webview](/core-concepts/connect-webviews) displays all of the stable providers that Seam supports, so your users can connect their 33 Lock devices without you specifying a provider list. To narrow what a Connect Webview displays, see [Customize the Brands to Display in Your Connect Webviews](/core-concepts/connect-webviews/customizing-connect-webviews#customize-the-brands-to-display-in-your-connect-webviews).

***

## Setup Instructions

For instructions on connecting 33 Lock devices to Seam, see the [33 Lock Setup Guide](./33-lock-setup-guide).

***

## Troubleshooting

For errors and warnings that are relevant to 33 Lock devices, see [Troubleshooting](/device-and-system-integration-guides/ttlock-locks/index#troubleshooting) in the TTLock-compatible device integration guide.

***

## Where to Order

To purchase 33 Lock devices, contact the 33 Lock sales team..

<table>
  <thead>
    <tr>
      <th />

      <th />

      <th />

      <th />

      <th />
    </tr>
  </thead>

  <tbody>
    <tr>
      <td />

      <td>
        <strong>33 Lock Contact Page</strong>
      </td>

      <td />

      <td>
        <a href="https://www.33lock.com/contact">
          [https://www.33lock.com/contact](https://www.33lock.com/contact)
        </a>
      </td>

      <td>
        <a href="/images/33-lock-logo.png">33-lock-logo.png</a>
      </td>
    </tr>
  </tbody>
</table>


# Sandbox 4SUITES Locks
Source: https://docs.seam.co/device-and-system-integration-guides/4suites-locks/4suites-locks-sample-data

Add virtual 4SUITES locks to your Seam sandbox workspace using these sample credentials to test your integration without real hardware.

Use either of the following sets of credentials to add virtual [4SUITES locks](/device-and-system-integration-guides/4suites-locks) to your Seam [sandbox workspace](/core-concepts/workspaces#sandbox-workspaces):

| Email Address                                                                              | Password |
| ------------------------------------------------------------------------------------------ | -------- |
| [jane@example.com](mailto:jane@example.com) or any email address in the example.com domain | 1234     |


# Get started with 4SUITES locks
Source: https://docs.seam.co/device-and-system-integration-guides/4suites-locks/get-started-with-4suites-locks

Learn how to connect and control 4SUITES locks with the Seam API.

## Overview

Seam provides a universal API to connect and control many brands of IoT devices and systems, including smart locks, access control systems (ACSs), thermostats, and noise sensors.

This guide gives you a rapid introduction to connecting and controlling your [4SUITES lock](./) using the Seam API. For application developers, you can use the Seam API in your app, and your users can authorize your app to control their devices using Seam.

For detailed information about the 4SUITES devices that Seam supports, see our [4SUITES Supported Devices page](https://www.seam.co/manufacturers/4suites).

To learn more about other IoT device and system brands that Seam supports—such as Yale, Schlage, Google Nest, and many more—visit our [integration page](https://www.seam.co/supported-devices-and-systems).

<Check>
  This guide shows you how to install a Seam SDK and then control your 4SUITES lock using the Seam API.

  Another easy way to learn about what you can do with the Seam API is to explore the [interactive Seam CLI](/core-concepts/seam-console/seam-online-cli), which you can access from directly within the [Seam Console](/core-concepts/seam-console).

  :arrow\_forward: [Go to the Seam Console!](https://console.seam.co/)
</Check>

***

## Step 1: Install a Seam SDK

Seam provides client libraries for many languages, including JavaScript, Python, Ruby, PHP, and others, as well as a Postman collection and an [OpenAPI](https://connect.getseam.com/openapi.json) spec.

* JavaScript / TypeScript ([npm](https://www.npmjs.com/package/seam), [GitHub](https://github.com/seamapi/javascript))
* Python ([pip](https://pypi.org/project/seam/), [GitHub](https://github.com/seamapi/python))
* Ruby Gem ([rubygem](https://rubygems.org/gems/seam), [GitHub](https://github.com/seamapi/ruby))
* PHP ([packagist](https://packagist.org/packages/seamapi/seam), [GitHub](https://github.com/seamapi/php))
* C# ([nuget](https://www.nuget.org/packages/Seam), [GitHub](https://github.com/seamapi/csharp))

First, install a Seam SDK, as follows:

<Tabs>
  <Tab title="JavaScript">
    ```bash theme={null}
    npm i seam
    ```
  </Tab>

  <Tab title="Python">
    ```bash theme={null}
    pip install seam
    # For some development environments, use pip3 in this command instead of pip.
    ```
  </Tab>

  <Tab title="Ruby">
    ```bash theme={null}
    bundle add seam
    ```
  </Tab>

  <Tab title="PHP">
    ```bash theme={null}
    composer require seamapi/seam
    ```
  </Tab>

  <Tab title="C#">
    Install using [nuget](https://www.nuget.org/packages/Seam).
  </Tab>
</Tabs>

Next, go to [https://console.seam.co/](https://console.seam.co/) and [sign up for Seam](/core-concepts/seam-console#create-a-seam-account) to get your [API key](/core-concepts/authentication/api-keys).

Then, export your API key as an environment variable.

```bash theme={null}
$ export SEAM_API_KEY=seam_test2bMS_94SrGUXuNR2JmJkjtvBQDg5c
```

<Info>
  This guide uses a [sandbox
  workspace](/core-concepts/workspaces#sandbox-workspaces).
  You can only connect virtual devices and systems in this type of workspace. If
  you want to connect a real 4SUITES lock, use a [non-sandbox
  workspace](/core-concepts/workspaces#production-workspaces)
  and API key.
</Info>

***

## Step 2: Link your 4SUITES account with Seam

To control your 4SUITES lock using the Seam API, you must first authorize your Seam workspace to connect to your 4SUITES account. If your application needs to connect to your users' 4SUITES accounts, Seam provides fully-embedded, [customizable](/core-concepts/connect-webviews/customizing-connect-webviews) client-side [Connect Webviews](/core-concepts/connect-webviews) to collect their authorization securely. These user-friendly pre-built authorization flows walk your users through the process of granting your Seam workspace permission to control their 4SUITES locks. The Connect Webview presents a flow that prompts your users to enter their credentials for their 4SUITES account.

In this guide, you create a Connect Webview object. Then, you display the graphical component of the created Connect Webview and enter a set of sample credentials to connect a sandbox 4SUITES account.

<Check>
  This guide shows you how to create a Connect Webview programmatically using the Seam API.

  The [Seam Console](/core-concepts/seam-console) provides another easy way to connect devices to your Seam workspace.

  Go to [https://console.seam.co/](https://console.seam.co/). On the **Devices** page, click **+ Add Devices**. Then, see [Authorize your workspace](#authorize-your-workspace) in this guide to complete the Connect Webview authorization flow.
</Check>

### Create a Connect Webview

Create a `connect_webview` object and then note the returned URL.

**Code:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  import { Seam } from 'seam'

  const seam = new Seam() // Seam automatically uses your exported SEAM_API_KEY.

  const connectWebview = await seam.connectWebviews.create()

  console.log(connectWebview.login_successful) // false

  // Use the returned Connect Webview URL to display
  // the Connect Webview authorization flow to your user.
  console.log(connectWebview.url)
  ```

  ```bash cURL theme={null}
  curl -X 'POST' \
    'https://connect.getseam.com/connect_webviews/create' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d '{}' | jq -r '"Login Successful (false): " + (.connect_webview.login_successful | tostring),
    "URL: " + .connect_webview.url'
    # Use the returned Connect Webview URL to display
    # the Connect Webview authorization flow to your user.
  ```

  ```python Python theme={null}
  from seam import Seam

  seam = Seam()  # Seam automatically uses your exported SEAM_API_KEY.

  connect_webview = seam.connect_webviews.create()

  assert connect_webview.login_successful is False

  # Use the returned Connect Webview URL to display
  # the Connect Webview authorization flow to your user.
  print(connect_webview.url)
  ```

  ```ruby Ruby theme={null}
  require "seam"

  seam = Seam.new() # Seam automatically uses your exported SEAM_API_KEY.

  connect_webview = seam.connect_webviews.create()

  puts connect_webview.login_successful # false

  # Use the returned Connect Webview URL to display
  # the Connect Webview authorization flow to your user.
  puts connect_webview.url
  ```

  ```php PHP theme={null}
  <?php
  require 'vendor/autoload.php';

  $seam = new Seam\SeamClient(); // Seam automatically uses your exported SEAM_API_KEY.

  $connect_webview = $seam->connect_webviews->create();

  echo $connect_webview->login_successful ? 'true' : 'false', "\n"; // false

  // Use the returned Connect Webview URL to display
  // the Connect Webview authorization flow to your user.
  echo $connect_webview->url;
  ```

  ```csharp C# theme={null}
  using Seam.Client;

  var seam = new SeamClient(apiToken: SEAM_API_KEY);

  var connectWebview = seam.ConnectWebviews.Create();

  Console.WriteLine(connectWebview.LoginSuccessful); // False

  // Use the returned Connect Webview URL to display
  // the Connect Webview authorization flow to your user.
  Console.WriteLine(connectWebview.Url);
  ```
</CodeGroup>

**Output:**

<CodeGroup>
  ```json JavaScript theme={null}
  false
  https://connect.getseam.com/connect_webviews/view?connect_webview_id=12345678-1234-1234-1234-123456789012&auth_token=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
  ```

  ```json cURL theme={null}
  Login Successful (false): false
  https://connect.getseam.com/connect_webviews/view?connect_webview_id=12345678-1234-1234-1234-123456789012&auth_token=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
  ```

  ```json Python theme={null}
  https://connect.getseam.com/connect_webviews/view?connect_webview_id=12345678-1234-1234-1234-123456789012&auth_token=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
  ```

  ```json Ruby theme={null}
  false
  https://connect.getseam.com/connect_webviews/view?connect_webview_id=12345678-1234-1234-1234-123456789012&auth_token=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
  ```

  ```json PHP theme={null}
  false
  https://connect.getseam.com/connect_webviews/view?connect_webview_id=12345678-1234-1234-1234-123456789012&auth_token=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
  ```

  ```json C# theme={null}
  False
  https://connect.getseam.com/connect_webviews/view?connect_webview_id=12345678-1234-1234-1234-123456789012&auth_token=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
  ```
</CodeGroup>

***

### Authorize your workspace

In a web browser, go to the URL that the Connect Webview object returned.

For application developers, you can redirect your user to this Connect Webview URL so that they can authorize your app to control their devices using Seam. We even provide a prebuilt [Connect Account Button](/ui-components/overview/react-components/connect-account-button) within our suite of [Seam Components](/ui-components/overview) that help you build your device management flow.

<Check>
  Because you're using a sandbox workspace, you can connect Seam's test 4SUITES
  account. We provide [virtual devices](./4suites-locks-sample-data) for each
  of the brands that we support. These sandbox devices and systems enable you to
  test your app with devices from multiple brands without the need to own all
  the corresponding physical devices.
</Check>

Complete the Connect Webview authorization flow by entering the following [4SUITES sandbox account](./4suites-locks-sample-data) credentials:

* **Email:** [jane@example.com](mailto:jane@example.com)
* **Password:** 1234

Confirm that authorization through the Connect Webview was successful by querying its status.

**Code:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  const updatedConnectWebview = await seam.connectWebviews.get({
    connect_webview_id: connectWebview.connect_webview_id,
  })

  console.log(updatedConnectWebview.login_successful) // true
  ```

  ```bash cURL theme={null}
  curl -X 'GET' \
    'https://connect.getseam.com/connect_webviews/get' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d "{
    \"connect_webview_id\": \"${connect_webview_id}\"
  }" | jq -r '"Login Successful (true): " + (.connect_webview.login_successful | tostring)'
  ```

  ```python Python theme={null}
  updated_connect_webview = seam.connect_webviews.get(connect_webview.connect_webview_id)

  assert updated_connect_webview.login_successful is True # True
  ```

  ```ruby Ruby theme={null}
  updated_connect_webview = seam.connect_webviews.get(
    connect_webview_id: connect_webview.connect_webview_id
  )

  puts updated_connect_webview.login_successful # true
  ```

  ```php PHP theme={null}
  $updated_connect_webview = $seam->connect_webviews->get(
    connect_webview_id: $connect_webview->connect_webview_id
  );

  echo $updated_connect_webview->login_successful ? 'true' : 'false', "\n"; // true
  ```

  ```csharp C# theme={null}
  var updatedConnectWebview = seam.ConnectWebviews.Get(
    connectWebviewId: connectWebview.connectWebviewId
  );

  Console.WriteLine(updatedConnectWebview.LoginSuccessful); // True
  ```
</CodeGroup>

**Output:**

<CodeGroup>
  ```json JavaScript theme={null}
  true
  ```

  ```json cURL theme={null}
  Login Successful (true): true
  ```

  ```json Python theme={null}
  True
  ```

  ```json Ruby theme={null}
  true
  ```

  ```json PHP theme={null}
  true
  ```

  ```json C# theme={null}
  True
  ```
</CodeGroup>

***

## Step 3: Retrieve 4SUITES lock devices

When you link a 4SUITES account with Seam, we create a `device` object to represent each 4SUITES lock in your account. You can then retrieve these 4SUITES devices using the [List Devices](/api/devices/list) and [Get Device](/api/devices/get) endpoints.

The Seam API exposes each device's properties, such as the door lock status, power status, capabilities, and so on.

**Code:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  // Retrieve all devices, filtered by manufacturer,
  // which is one of several filters that list() supports.
  const allFourSuitesLocks = await seam.devices.list({
    manufacturer: 'four_suites',
  })

  // Select the first device as an example.
  const frontDoor = allFourSuitesLocks[0]

  // Inspect specific properties.
  console.log(frontDoor.properties.online) // true
  console.log(frontDoor.properties.locked) // true

  // View the entire returned device object.
  console.log(frontDoor)
  ```

  ```bash cURL theme={null}
  # Retrieve all devices, filtered by manufacturer, which is
  # one of several filters that the list endpoint supports.
  all_four_suites_locks=$(
    # Use GET or POST.
    curl -X 'GET' \
      'https://connect.getseam.com/devices/list' \
      -H 'accept: application/json' \
      -H "Authorization: Bearer ${SEAM_API_KEY}" \
      -H 'Content-Type: application/json' \
      -d '{
      "manufacturer": "four_suites"
    }')

  # Select the first device as an example.
  front_door=$(jq -r '.devices[0]' <<< ${all_four_suites_locks})

  # Inspect specific properties.
  echo $(jq -r '"Online (true): " + (.properties.online | tostring)' <<< ${front_door})
  echo $(jq -r '"Locked (true): " + (.properties.locked | tostring)' <<< ${front_door})

  # View the entire returned device object.
  echo ${front_door}
  ```

  ```python Python theme={null}
  # Retrieve all devices, filtered by manufacturer,
  # which is one of several filters that list() supports.
  all_four_suites_locks = seam.devices.list(manufacturer="four_suites")

  # Select the first device as an example.
  front_door = all_four_suites_locks[0]

  # Inspect specific properties.
  assert front_door.properties["online"] is True # True
  assert front_door.properties["locked"] is True # True

  # View the entire returned device object.
  pprint(front_door)
  ```

  ```ruby Ruby theme={null}
  # Retrieve all devices, filtered by manufacturer,
  # which is one of several filters that list() supports.
  all_four_suites_locks = seam.devices.list(manufacturer: "four_suites")

  # Select the first device as an example.
  front_door = all_four_suites_locks[0]

  # Inspect specific properties.
  puts front_door.properties.online # true
  puts front_door.properties.locked # true

  # View the entire returned device object.
  puts front_door.inspect
  ```

  ```php PHP theme={null}
  // Retrieve all devices, filtered by manufacturer,
  // which is one of several filters that list() supports.
  $all_four_suites_locks = $seam->devices->list(manufacturer: "four_suites");

  // Select the first device as an example.
  $front_door = $all_four_suites_locks[0];

  // Inspect specific properties.
  echo $front_door->properties->online ? 'true' : 'false', "\n"; // true
  echo $front_door->properties->locked ? 'true' : 'false', "\n"; // true

  // View the entire returned device object.
  echo json_encode($front_door, JSON_PRETTY_PRINT);
  ```

  ```csharp C# theme={null}
  // Retrieve all devices, filtered by manufacturer,
  // which is one of several filters that list() supports.
  var allFourSuitesLocks = seam.Devices.List(
    manufacturer: Seam.Api.Devices.ListRequest.ManufacturerEnum.FourSuites
  );

  // Select the first device as an example.
  Device frontDoor = allFourSuitesLocks[0];

  // Inspect specific properties.
  Console.WriteLine(frontDoor.Properties.Online); // true
  Console.WriteLine(frontDoor.Properties.Locked); // true

  // View the entire returned device object.
  Console.WriteLine(frontDoor);
  ```
</CodeGroup>

**Output:**

<CodeGroup>
  ```json JavaScript theme={null}
  true
  true
  {
    device_id: '11111111-1111-1111-1111-444444444444',
    display_name: 'Lock 1',
    workspace_id: '00000000-0000-0000-0000-000000000000',
    connected_account_id: '11111111-1111-1111-1111-222222222222',
    created_at: '2024-05-29T20:08:48.878Z',
    properties: {
      manufacturer: 'four_suites',
      online: true,
      locked: true,
      has_direct_power: true,
      ...
    },
    can_remotely_unlock: true,
    ...
  }
  ```

  ```json cURL theme={null}
  Online (true): true
  Locked (true): true
  {
    "device_id": "11111111-1111-1111-1111-444444444444",
    "display_name": "Lock 1",
    "workspace_id": "00000000-0000-0000-0000-000000000000",
    "connected_account_id": "11111111-1111-1111-1111-222222222222",
    "created_at": "2024-05-29T20:08:48.878Z",
    "properties": {
      "manufacturer": "four_suites",
      "locked": true,
      "online": true,
      "has_direct_power": true,
      ...
    },
    "can_remotely_unlock": true,
    ...
  }
  ```

  ```json Python theme={null}
  Device(
    device_id='11111111-1111-1111-1111-444444444444',
    display_name='Lock 1',
    workspace_id='00000000-0000-0000-0000-000000000000'
    connected_account_id='11111111-1111-1111-1111-222222222222',
    created_at='2024-05-29T20:08:48.878Z',
    properties={
      'manufacturer': 'four_suites',
      'online': True,
      'locked': True,
      'has_direct_power': True,
      ...
    }
    can_remotely_unlock=True,
    ...
  )
  ```

  ```json Ruby theme={null}
  true
  true
  <
    Seam::Device:0x00438
      device_id="11111111-1111-1111-1111-444444444444"
      display_name="Lock 1"
      workspace_id="00000000-0000-0000-0000-000000000000"
      connected_account_id="11111111-1111-1111-1111-222222222222"
      created_at=2024-05-29 20:08:48.878 UTC
      properties={
        "manufacturer"=>"four_suites",
        "online"=>true,
        "locked"=>true,
        "has_direct_power"=>true,
        ...
      }
      can_remotely_unlock=true
      ...
  >
  ```

  ```json PHP theme={null}
  true
  true
  {
    "device_id": "11111111-1111-1111-1111-444444444444",
    "display_name": "Lock 1",
    "workspace_id": "00000000-0000-0000-0000-000000000000"
    "connected_account_id": "11111111-1111-1111-1111-222222222222",
    "created_at": "2024-05-29T20:08:48.878Z",
    "properties": {
      "manufacturer": "four_suites",
      "online": true,
      "locked": true,
      "has_direct_power": true,
      ...
    },
    "can_remotely_unlock": true,
    ...
  }
  ```

  ```json C# theme={null}
  True
  True
  {
    "device_id": "11111111-1111-1111-1111-444444444444",
    "display_name": "Lock 1",
    "workspace_id": "00000000-0000-0000-0000-000000000000",
    "connected_account_id": "11111111-1111-1111-1111-222222222222",
    "created_at": "2024-05-29T20:08:48.878Z",
    "properties": {
      "manufacturer": "four_suites",
      "online": true,
      "locked": true,
      "has_direct_power": true,
      ...
    },
    "can_remotely_unlock": true,
    ...
  }
  ```
</CodeGroup>

***

## Step 4: Control your 4SUITES lock

Next, you can use the Seam API to control your lock.

Each device that you connect to Seam has a specific set of capabilities. These capabilities define the Seam API actions that you can use, such as [remote unlock actions](/low-level-apis/smart-locks/lock-and-unlock), [programming access codes](/low-level-apis/smart-locks/access-codes), and so on. Seam's intuitive and granular [capability flags](/capability-guides/device-and-system-capabilities#capability-flags) inform your application about what features and behaviors each device supports. Notice the capability flags within the code samples in this guide.

Try out the following actions on your 4SUITES lock:

* [ ] [Unlock your lock](#unlock-your-lock)

### Unlock your lock

To unlock a door, use the [Unlock Door](/api/locks/unlock_door) endpoint. Specify the device that you want to unlock by including the `device_id` in the request body. This endpoint returns an [action attempt](/core-concepts/action-attempts) to track the progress of the unlock operation.

**Code:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  // Confirm that the device can remotely unlock.
  // You're using a capability flag here!
  if (frontDoor.can_remotely_unlock) {
    // Perform the unlock operation
    // and return an action attempt.
    const actionAttempt = await seam.locks.unlockDoor({
      device_id: frontDoor.device_id,
    })
  }
  ```

  ```bash cURL theme={null}
  # Confirm that the device can remotely unlock.
  # You're using a capability flag here!
  if  $(jq -r '.can_remotely_lock' <<< ${front_door}); then \
    # Perform the unlock operation
    # and return an action attempt.
    curl -X 'POST' \
      'https://connect.getseam.com/locks/unlock_door' \
      -H 'accept: application/json' \
      -H "Authorization: Bearer ${SEAM_API_KEY}" \
      -H 'Content-Type: application/json' \
      -d "{
        \"device_id\": \"$(jq -r '.device_id' <<< ${front_door})\"
    }";
  fi
  ```

  ```python Python theme={null}
  # Confirm that the device can remotely unlock.
  # You're using a capability flag here!
  if front_door.can_remotely_unlock:
    # Perform the unlock operation
    # and return an action attempt.
    action_attempt=seam.locks.unlock_door(device_id=front_door.device_id)
  ```

  ```ruby Ruby theme={null}
  # Confirm that the device can remotely unlock.
  # You're using a capability flag here!
  if (front_door.can_remotely_unlock)
    # Perform the unlock operation
    # and return an action attempt.
    action_attempt = seam.locks.unlock_door(device_id: front_door.device_id)
  end
  ```

  ```php PHP theme={null}
  // Confirm that the device can remotely unlock.
  // You're using a capability flag here!
  if ($front_door->can_remotely_unlock) {
    // Perform the unlock operation
    // and return an action attempt.
    $action_attempt = $seam->locks->unlock_door(device_id: $front_door->device_id);
  }
  ```

  ```csharp C# theme={null}
  // Confirm that the device can remotely unlock.
  // You're using a capability flag here!
  if (frontDoor.CanRemotelyUnlock == true) {
    // Perform the unlock operation
    // and return an action attempt.
    ActionAttempt actionAttempt = seam.Locks.UnlockDoor(deviceId: frontDoor.DeviceId);
  }
  ```
</CodeGroup>

**Output:**

<CodeGroup>
  ```json JavaScript theme={null}
  {
    "actionAttempt": {
      "status": "success",
      "action_attempt_id": "11111111-2222-3333-4444-555555555555",
      "action_type": "UNLOCK_DOOR",
      "result": {},
      "error": null
    }
  }
  ```

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

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

  ```json Ruby theme={null}
  <Seam::ActionAttempt:0x00438
    status="pending"
    action_type="UNLOCK_DOOR"
    action_attempt_id="11111111-2222-3333-4444-555555555555"
    result=nil>
  ```

  ```json PHP theme={null}
  {
    "action_attempt_id": "11111111-2222-3333-4444-555555555555",
    "action_type": "UNLOCK_DOOR",
    "error": null,
    "result": {},
    "status": "success"
  }
  ```

  ```json C# theme={null}
  {
    "status": "pending",
    "action_type": "UNLOCK_DOOR",
    "action_attempt_id": "11111111-2222-3333-4444-555555555555"
  }
  ```
</CodeGroup>

You can track the status of the unlock operation to confirm that the device unlocked successfully. Query the `locked` status of the device, [retrieve the action attempt](/api/action_attempts/get) by ID, or look for a [`lock.unlocked` event](/api/locks/events#lock-unlocked).

To query the `locked` status of the device:

**Code:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  // Get the device by ID.
  const updatedFrontDoor = await seam.devices.get({
    device_id: frontDoor.device_id,
  })

  // Inspect the locked property to confirm
  // that the unlock operation was successful.
  console.log(updatedFrontDoor.properties.locked) // false
  ```

  ```bash cURL theme={null}
  # Get the device by ID.
  updated_front_door=$(
    # Use GET or POST.
    curl -X 'GET' \
      'https://connect.getseam.com/devices/get' \
      -H 'accept: application/json' \
      -H "Authorization: Bearer ${SEAM_API_KEY}" \
      -H 'Content-Type: application/json' \
      -d "{
        \"device_id\": \"$(jq -r '.device_id' <<< ${front_door})\"
    }")

  # Inspect the locked property to confirm
  # that the unlock operation was successful.
  echo $(jq -r '"Locked (false): " + (.device.properties.locked | tostring)' <<< ${updated_front_door})
  ```

  ```python Python theme={null}
  # Get the device by ID.
  updated_front_door = seam.devices.get(device_id=front_door.device_id)

  # Inspect the locked property to confirm
  # that the unlock operation was successful.
  assert updated_front_door.properties["locked"] is False # False
  ```

  ```ruby Ruby theme={null}
  # Get the device by ID.
  updated_front_door = seam.devices.get(device_id: front_door.device_id)

  # Inspect the locked property to confirm
  # that the unlock operation was successful.
  puts updated_front_door.properties.locked # false
  ```

  ```php PHP theme={null}
  // Get the device by ID.
  $updated_front_door = $seam->devices->get(device_id: $front_door->device_id);

  // Inspect the locked property to confirm
  // that the unlock operation was successful.
  echo $updated_front_door->properties->locked ? 'true' : 'false', "\n"; // false
  ```

  ```csharp C# theme={null}
  // Get the device by ID.
  Device updatedFrontDoor = seam.Devices.Get(
    deviceId: frontDoor.DeviceId
  );

  // Inspect the locked property to confirm
  // that the unlock operation was successful.
  Console.WriteLine(updatedFrontDoor.Properties.Locked); // false
  ```
</CodeGroup>

**Output:**

<CodeGroup>
  ```json JavaScript theme={null}
  false
  ```

  ```json cURL theme={null}
  Locked (false): false
  ```

  ```json Python theme={null}
  False
  ```

  ```json Ruby theme={null}
  false
  ```

  ```json PHP theme={null}
  false
  ```

  ```json C# theme={null}
  False
  ```
</CodeGroup>

***

## Step 5: Connect a real 4SUITES lock

Now that you have learned the basics of using the Seam API, you can connect and control a real 4SUITES device. To do so, make sure to switch to a [non-sandbox workspace](/core-concepts/workspaces#production-workspaces) and [API key](/core-concepts/authentication/api-keys).

For more details about setting up your real 4SUITES lock, see the [4SUITES locks integration guide](./).

***

## Step 6: Build your application!

Seam makes it easy to develop your application. In addition to the robust Seam API and the wide variety of programming languages that our SDKs support, we also provide a suite of [Seam Components](/ui-components/overview). These prebuilt UI components help you to build your device management flow.

For example, you can use the [Device Table Seam Component](/ui-components/overview/react-components/device-table) to display a list of devices and to identify all devices with issues. You can use the [Device Details Seam Component](/ui-components/overview/react-components/device-details) to display a device's properties, settings, and issues, as well as to enable your users to perform actions based on each device's capabilities. The [Access Code Details Seam Component](/ui-components/overview/react-components/access-code-details) provides a similar display and actions for access codes.

Seam Components use a responsive design to fit seamlessly on any screen size. They also provide device debugging flows to help your users.

To learn about all the Seam Components that we provide, see [Seam Components](/ui-components/overview).

***

## Next steps

Now that you've completed this getting started guide for 4SUITES devices, you can learn more about what you can do with the Seam API.

* [ ] **Explore**\
  See the [other devices and system integrations](/device-and-system-integration-guides) that Seam supports.
* [ ] **Learn**\
  Read about Seam [concepts](/core-concepts/overview) and the [device and system capabilities ](/capability-guides/device-and-system-capabilities)that Seam supports.
* [ ] **Use Seam Components**\
  Find out about [Seam Components](/ui-components/overview), which are prebuilt UI components for building your device management flow.
* [ ] **Use webhooks**\
  Learn how to use [webhooks](/developer-tools/webhooks) as an efficient way to receive device events.
* [ ] **Find out more**\
  Explore the other types of devices and systems that you can control with Seam, including [access control systems](/low-level-apis/access-systems), [thermostats](/capability-guides/thermostats), and [noise sensors](/capability-guides/noise-sensors).
* [ ] **Develop for mobile access**\
  Learn about Seam's [mobile access solution](/capability-guides/mobile-access).

<Info>
  If you have any questions or want to report an issue, email us at
  [support@seam.co](mailto:support@seam.co).
</Info>

***

## Quick links

<CardGroup>
  <Card title="Get an API Key (free)" href="https://console.seam.co/">
    Sign up for the Seam Console and get your API keys. →
  </Card>

  <Card title="Contact Sales" href="https://www.seam.co/contact-us">
    Got a project or a specific question? Contact our team to get answers. →
  </Card>
</CardGroup>


# 4SUITES Locks
Source: https://docs.seam.co/device-and-system-integration-guides/4suites-locks/index

Guide for using 4SUITES locks with Seam

<img alt="4SUITES logo" />

## Overview

4SUITES produces cloud-managed Internet of Things (IoT) locks, lock upgrades, and readers for the hospitality industry. Because 4SUITES locks use IoT-enabled sensors, instead of relying on Bluetooth®, guests can use 4SUITES mobile keys through a webapp on a smartphone or other internet-connected device—without needing to download an app. Seam integrates with 4SUITES locks to provide streamlined hotel operations and improved guest access.

***

## Supported Devices

<DeviceList />

This integration supports all [4SUITES locks, lock upgrades, and readers](https://www.4suiteshq.com/products/).

For detailed information about the 4SUITES devices that Seam supports, see our [4SUITES Supported Devices page](https://www.seam.co/manufacturers/4suites).

***

## Supported Features

We support the following features:

* [Triggering web lock and unlock actions](/low-level-apis/smart-locks/lock-and-unlock)
* [Programming access codes](/low-level-apis/smart-locks/access-codes)

***

### Device Provider Key

Seam identifies these devices with the `four_suites` device provider key. By default, a [Connect Webview](/core-concepts/connect-webviews) displays all of the stable providers that Seam supports, so your users can connect their 4SUITES devices without you specifying a provider list. To narrow what a Connect Webview displays, see [Customize the Brands to Display in Your Connect Webviews](/core-concepts/connect-webviews/customizing-connect-webviews#customize-the-brands-to-display-in-your-connect-webviews).

***

## Setup Instructions

To control 4SUITES devices using Seam, you must prompt owners of these devices to perform the following steps:

1. Obtain the credentials that you use to log in to your [4SUITES account](https://app.4suites.nl/auth/login).
2. Use these credentials to log in to the Seam Connect Webview to add your 4SUITES devices to Seam.

***

## Where to Order

To purchase 4SUITES devices, request a quote using the 4SUITES **Contact Us Form**.

<table>
  <thead>
    <tr>
      <th />

      <th />

      <th />

      <th />

      <th />
    </tr>
  </thead>

  <tbody>
    <tr>
      <td />

      <td>
        <strong>4SUITES Contact Us Form</strong>
      </td>

      <td />

      <td>
        <a href="https://www.4suiteshq.com/contact-us/">
          [https://www.4suiteshq.com/contact-us/](https://www.4suiteshq.com/contact-us/)
        </a>
      </td>

      <td>
        <a href="/images/4suites-logo.png">4suites-logo.png</a>
      </td>
    </tr>
  </tbody>
</table>

***


# Akiles Setup Guide
Source: https://docs.seam.co/device-and-system-integration-guides/akiles-locks/akiles-setup-guide

Connect your Akiles locks to Seam.

## Overview

This guide walks you through connecting your Akiles locks to Seam. Your Akiles devices must already be physically installed before proceeding.

Akiles locks require the [Akiles Gateway](https://akiles.app/en/products/smart-lock-system-gateway) for remote connectivity. You can optionally add the [Akiles Pinpad](https://akiles.app/en/products/smart-lock-system-pinpad) to enable access code entry on devices without an integrated keypad.

***

## Step 1: Set Up the Akiles Gateway

1. Plug in your Akiles Gateway and connect it using Ethernet.

   The LED should be blue to indicate that it is connected.

***

## Step 2: Prepare Your Lock Hardware IDs

Before installing an Akiles Roomlock, take a picture of the QR code inside the lock body. The QR code is located on the inside of the lock, opposite the keypad. This code is required to add the lock in the Akiles app.

***

## Step 3: Add Devices in the Akiles App

1. Log in to the Akiles app.

   * [Web](https://web.akiles.app/login)
   * [iOS](https://apps.apple.com/app/akiles/id1467888600)
   * [Google Play](https://play.google.com/store/apps/details?id=app.akiles\&hl=en)

   Make sure to note your credentials for the Akiles app.

2. In the Akiles app, click the upper-left menu and select **Devices**.

3. At the upper-right corner, click **Actions +** and select **New Device**.

4. Type a name for the new device and select the site with which you want to associate the device.

5. In the **Device Type** area, add the Akiles Gateway:
   * Scan the QR code on the back of the Gateway to retrieve the hardware ID number.
   * In the **Device Type** field, paste the hardware ID number. The Akiles app displays Device and Version information based on the hardware ID.
   * Click **Create Device**. The Akiles app creates the device representation and displays the device status. A Gateway takes a moment to connect to the Akiles server, run a firmware auto-update, and reboot.

6. Add each Akiles lock:
   * Using the photo that you took of the QR code inside the lock, scan this code to retrieve the hardware ID number.
   * In the **Device Type** field, paste the hardware ID number. The Akiles app displays Device and Version information based on the hardware ID.
   * Click **Create Device**. The Akiles app creates the device representation and displays that the device status is offline.

***

## Step 4: Link Locks to the Gateway

1. Click the upper-left menu and select **Links**. By default, the Akiles app displays a link between the Gateway and server.
2. Click **Link +**.
3. Clear the **Server** field to remove **Server** from **Central Device**.
4. Click **Central Device** and select **Gateway**.
5. Click **Peripheral Device** and select **Lock**.
6. Click **Create Link**. This link connects the lock to the Akiles server and may take several minutes to complete. It also performs firmware updates that take additional time.
7. Repeat for each lock.
8. Click the upper-left menu, select **Devices**, and make sure that all devices are online.

***

## Step 5: Connect to Seam

Use your credentials for the Akiles app to log in to the [Connect Webview](/core-concepts/connect-webviews) to add your Akiles devices to Seam.

***

## Step 6: Verify the Connection

After connecting, verify that your Akiles devices appear in your Seam workspace and that each device shows an **online** status.

***

## Troubleshooting

### Devices not appearing after connecting

* Verify that all Akiles devices are online in the Akiles app.
* Confirm that each lock is linked to the Gateway.

### Lock shows as offline

* Check that the Gateway LED is blue, indicating it is connected.
* Verify the Ethernet connection to the Gateway.
* In the Akiles app, check the **Links** section to confirm the lock-to-Gateway link is active.

### Gateway not connecting

* Verify the Ethernet cable is securely connected.
* Allow time for the Gateway to complete firmware updates and reboot after initial setup.


# Get started with Akiles locks
Source: https://docs.seam.co/device-and-system-integration-guides/akiles-locks/get-started-with-akiles-locks

Learn how to connect and control Akiles locks with the Seam API.

## Overview

Seam provides a universal API to connect and control many brands of IoT devices and systems, including smart locks, access control systems (ACSs), thermostats, and noise sensors.

This guide gives you a rapid introduction to connecting and controlling your [Akiles lock](./) using the Seam API. For application developers, you can use the Seam API in your app, and your users can authorize your app to control their devices using Seam.

For detailed information about the Akiles devices that Seam supports, see our [Akiles Supported Devices page](https://www.seam.co/manufacturers/akiles).

To learn more about other IoT device and system brands that Seam supports—such as Yale, Schlage, Google Nest, and many more—visit our [integration page](https://www.seam.co/supported-devices-and-systems).

<Check>
  This guide shows you how to install a Seam SDK and then control your Akiles lock using the Seam API.

  Another easy way to learn about what you can do with the Seam API is to explore the [interactive Seam CLI](/core-concepts/seam-console/seam-online-cli), which you can access from directly within the [Seam Console](/core-concepts/seam-console).

  :arrow\_forward: [Go to the Seam Console!](https://console.seam.co/)
</Check>

***

## Step 1: Install a Seam SDK

Seam provides client libraries for many languages, including JavaScript, Python, Ruby, PHP, and others, as well as a Postman collection and an [OpenAPI](https://connect.getseam.com/openapi.json) spec.

* JavaScript / TypeScript ([npm](https://www.npmjs.com/package/seam), [GitHub](https://github.com/seamapi/javascript))
* Python ([pip](https://pypi.org/project/seam/), [GitHub](https://github.com/seamapi/python))
* Ruby Gem ([rubygem](https://rubygems.org/gems/seam), [GitHub](https://github.com/seamapi/ruby))
* PHP ([packagist](https://packagist.org/packages/seamapi/seam), [GitHub](https://github.com/seamapi/php))
* C# ([nuget](https://www.nuget.org/packages/Seam), [GitHub](https://github.com/seamapi/csharp))

First, install a Seam SDK, as follows:

<Tabs>
  <Tab title="JavaScript">
    ```bash theme={null}
    npm i seam
    ```
  </Tab>

  <Tab title="Python">
    ```bash theme={null}
    pip install seam
    # For some development environments, use pip3 in this command instead of pip.
    ```
  </Tab>

  <Tab title="Ruby">
    ```bash theme={null}
    bundle add seam
    ```
  </Tab>

  <Tab title="PHP">
    ```bash theme={null}
    composer require seamapi/seam
    ```
  </Tab>

  <Tab title="C#">
    Install using [nuget](https://www.nuget.org/packages/Seam).
  </Tab>
</Tabs>

Next, go to [https://console.seam.co/](https://console.seam.co/) and [sign up for Seam](/core-concepts/seam-console#create-a-seam-account) to get your [API key](/core-concepts/authentication/api-keys).

Then, export your API key as an environment variable.

```bash theme={null}
$ export SEAM_API_KEY=seam_test2bMS_94SrGUXuNR2JmJkjtvBQDg5c
```

<Info>
  This guide uses a [sandbox
  workspace](/core-concepts/workspaces#sandbox-workspaces).
  You can only connect virtual devices and systems in this type of workspace. If
  you want to connect a real Akiles lock, use a [non-sandbox
  workspace](/core-concepts/workspaces#production-workspaces)
  and API key.
</Info>

***

## Step 2: Link your Akiles account with Seam

To control your Akiles lock using the Seam API, you must first authorize your Seam workspace to connect to your Akiles account. If your application needs to connect to your users' Akiles accounts, Seam provides fully-embedded, [customizable](/core-concepts/connect-webviews/customizing-connect-webviews) client-side [Connect Webviews](/core-concepts/connect-webviews) to collect their authorization securely. These user-friendly pre-built authorization flows walk your users through the process of granting your Seam workspace permission to control their Akiles locks. The Connect Webview presents a flow that prompts your users to enter their credentials for their Akiles account.

In this guide, you create a Connect Webview object. Then, you display the graphical component of the created Connect Webview and enter a set of sample credentials to connect a sandbox Akiles account.

<Check>
  This guide shows you how to create a Connect Webview programmatically using the Seam API.

  The [Seam Console](/core-concepts/seam-console) provides another easy way to connect devices to your Seam workspace.

  Go to [https://console.seam.co/](https://console.seam.co/). On the **Devices** page, click **+ Add Devices**. Then, see [Authorize your workspace](#authorize-your-workspace) in this guide to complete the Connect Webview authorization flow.
</Check>

### Create a Connect Webview

Create a `connect_webview` object and then note the returned URL.

**Code:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  import { Seam } from 'seam'

  const seam = new Seam() // Seam automatically uses your exported SEAM_API_KEY.

  const connectWebview = await seam.connectWebviews.create()

  console.log(connectWebview.login_successful) // false

  // Use the returned Connect Webview URL to display
  // the Connect Webview authorization flow to your user.
  console.log(connectWebview.url)
  ```

  ```bash cURL theme={null}
  curl -X 'POST' \
    'https://connect.getseam.com/connect_webviews/create' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d '{}' | jq -r '"Login Successful (false): " + (.connect_webview.login_successful | tostring),
    "URL: " + .connect_webview.url'
    # Use the returned Connect Webview URL to display
    # the Connect Webview authorization flow to your user.
  ```

  ```python Python theme={null}
  from seam import Seam

  seam = Seam()  # Seam automatically uses your exported SEAM_API_KEY.

  connect_webview = seam.connect_webviews.create()

  assert connect_webview.login_successful is False

  # Use the returned Connect Webview URL to display
  # the Connect Webview authorization flow to your user.
  print(connect_webview.url)
  ```

  ```ruby Ruby theme={null}
  require "seam"

  seam = Seam.new() # Seam automatically uses your exported SEAM_API_KEY.

  connect_webview = seam.connect_webviews.create()

  puts connect_webview.login_successful # false

  # Use the returned Connect Webview URL to display
  # the Connect Webview authorization flow to your user.
  puts connect_webview.url
  ```

  ```php PHP theme={null}
  <?php
  require 'vendor/autoload.php';

  $seam = new Seam\SeamClient(); // Seam automatically uses your exported SEAM_API_KEY.

  $connect_webview = $seam->connect_webviews->create();

  echo $connect_webview->login_successful ? 'true' : 'false', "\n"; // false

  // Use the returned Connect Webview URL to display
  // the Connect Webview authorization flow to your user.
  echo $connect_webview->url;
  ```

  ```csharp C# theme={null}
  using Seam.Client;

  var seam = new SeamClient(apiToken: SEAM_API_KEY);

  var connectWebview = seam.ConnectWebviews.Create();

  Console.WriteLine(connectWebview.LoginSuccessful); // False

  // Use the returned Connect Webview URL to display
  // the Connect Webview authorization flow to your user.
  Console.WriteLine(connectWebview.Url);
  ```
</CodeGroup>

**Output:**

<CodeGroup>
  ```json JavaScript theme={null}
  false
  https://connect.getseam.com/connect_webviews/view?connect_webview_id=12345678-1234-1234-1234-123456789012&auth_token=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
  ```

  ```json cURL theme={null}
  Login Successful (false): false
  https://connect.getseam.com/connect_webviews/view?connect_webview_id=12345678-1234-1234-1234-123456789012&auth_token=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
  ```

  ```json Python theme={null}
  https://connect.getseam.com/connect_webviews/view?connect_webview_id=12345678-1234-1234-1234-123456789012&auth_token=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
  ```

  ```json Ruby theme={null}
  false
  https://connect.getseam.com/connect_webviews/view?connect_webview_id=12345678-1234-1234-1234-123456789012&auth_token=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
  ```

  ```json PHP theme={null}
  false
  https://connect.getseam.com/connect_webviews/view?connect_webview_id=12345678-1234-1234-1234-123456789012&auth_token=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
  ```

  ```json C# theme={null}
  False
  https://connect.getseam.com/connect_webviews/view?connect_webview_id=12345678-1234-1234-1234-123456789012&auth_token=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
  ```
</CodeGroup>

***

### Authorize your workspace

In a web browser, go to the URL that the Connect Webview object returned.

For application developers, you can redirect your user to this Connect Webview URL so that they can authorize your app to control their devices using Seam. We even provide a prebuilt [Connect Account Button](/ui-components/overview/react-components/connect-account-button) within our suite of [Seam Components](/ui-components/overview) that help you build your device management flow.

<Check>
  Because you're using a sandbox workspace, you can connect Seam's test Akiles
  account. We provide [virtual devices](./sandbox-akiles-locks) for each of the
  brands that we support. These sandbox devices and systems enable you to test
  your app with devices from multiple brands without the need to own all the
  corresponding physical devices.
</Check>

Complete the Connect Webview authorization flow by entering the following [Akiles sandbox account](./sandbox-akiles-locks) credentials:

* **Email:** [jane@example.com](mailto:jane@example.com)
* **Password:** 1234

Confirm that authorization through the Connect Webview was successful by querying its status.

**Code:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  const updatedConnectWebview = await seam.connectWebviews.get({
    connect_webview_id: connectWebview.connect_webview_id,
  })

  console.log(updatedConnectWebview.login_successful) // true
  ```

  ```bash cURL theme={null}
  curl -X 'GET' \
    'https://connect.getseam.com/connect_webviews/get' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d "{
    \"connect_webview_id\": \"${connect_webview_id}\"
  }" | jq -r '"Login Successful (true): " + (.connect_webview.login_successful | tostring)'
  ```

  ```python Python theme={null}
  updated_connect_webview = seam.connect_webviews.get(connect_webview.connect_webview_id)

  assert updated_connect_webview.login_successful is True # True
  ```

  ```ruby Ruby theme={null}
  updated_connect_webview = seam.connect_webviews.get(
    connect_webview_id: connect_webview.connect_webview_id
  )

  puts updated_connect_webview.login_successful # true
  ```

  ```php PHP theme={null}
  $updated_connect_webview = $seam->connect_webviews->get(
    connect_webview_id: $connect_webview->connect_webview_id
  );

  echo $updated_connect_webview->login_successful ? 'true' : 'false', "\n"; // true
  ```

  ```csharp C# theme={null}
  var updatedConnectWebview = seam.ConnectWebviews.Get(
    connectWebviewId: connectWebview.connectWebviewId
  );

  Console.WriteLine(updatedConnectWebview.LoginSuccessful); // True
  ```
</CodeGroup>

**Output:**

<CodeGroup>
  ```json JavaScript theme={null}
  true
  ```

  ```json cURL theme={null}
  Login Successful (true): true
  ```

  ```json Python theme={null}
  True
  ```

  ```json Ruby theme={null}
  true
  ```

  ```json PHP theme={null}
  true
  ```

  ```json C# theme={null}
  True
  ```
</CodeGroup>

***

## Step 3: Retrieve Akiles lock devices

When you link an Akiles account with Seam, we create a `device` object to represent each Akiles lock in your account. You can then retrieve these Akiles devices using the [List Devices](/api/devices/list) and [Get Device](/api/devices/get) endpoints.

The Seam API exposes each device's properties, such as the door lock status, capabilities, and so on.

**Code:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  // Retrieve all devices, filtered by manufacturer,
  // which is one of several filters that list() supports.
  const allAkilesLocks = await seam.devices.list({ manufacturer: 'akiles' })

  // Select the first device as an example.
  const frontDoor = allAkilesLocks[0]

  // Inspect specific properties.
  console.log(frontDoor.properties.online) // true
  console.log(frontDoor.properties.locked) // true

  // View the entire returned device object.
  console.log(frontDoor)
  ```

  ```bash cURL theme={null}
  # Retrieve all devices, filtered by manufacturer, which is
  # one of several filters that the list endpoint supports.
  all_akiles_locks=$(
    # Use GET or POST.
    curl -X 'GET' \
      'https://connect.getseam.com/devices/list' \
      -H 'accept: application/json' \
      -H "Authorization: Bearer ${SEAM_API_KEY}" \
      -H 'Content-Type: application/json' \
      -d '{
      "manufacturer": "akiles"
    }')

  # Select the first device as an example.
  front_door=$(jq -r '.devices[0]' <<< ${all_akiles_locks})

  # Inspect specific properties.
  echo $(jq -r '"Online (true): " + (.properties.online | tostring)' <<< ${front_door})
  echo $(jq -r '"Locked (true): " + (.properties.locked | tostring)' <<< ${front_door})

  # View the entire returned device object.
  echo ${front_door}
  ```

  ```python Python theme={null}
  # Retrieve all devices, filtered by manufacturer,
  # which is one of several filters that list() supports.
  all_akiles_locks = seam.devices.list(manufacturer="akiles")

  # Select the first device as an example.
  front_door = all_akiles_locks[0]

  # Inspect specific properties.
  assert front_door.properties["online"] is True # True
  assert front_door.properties["locked"] is True # True

  # View the entire returned device object.
  pprint(front_door)
  ```

  ```ruby Ruby theme={null}
  # Retrieve all devices, filtered by manufacturer,
  # which is one of several filters that list() supports.
  all_akiles_locks = seam.devices.list(manufacturer: "akiles")

  # Select the first device as an example.
  front_door = all_akiles_locks[0]

  # Inspect specific properties.
  puts front_door.properties.online # true
  puts front_door.properties.locked # true

  # View the entire returned device object.
  puts front_door.inspect
  ```

  ```php PHP theme={null}
  // Retrieve all devices, filtered by manufacturer,
  // which is one of several filters that list() supports.
  $all_akiles_locks = $seam->devices->list(manufacturer: "akiles");

  // Select the first device as an example.
  $front_door = $all_akiles_locks[0];

  // Inspect specific properties.
  echo $front_door->properties->online ? 'true' : 'false', "\n"; // true
  echo $front_door->properties->locked ? 'true' : 'false', "\n"; // true

  // View the entire returned device object.
  echo json_encode($front_door, JSON_PRETTY_PRINT);
  ```

  ```csharp C# theme={null}
  // Retrieve all devices, filtered by manufacturer,
  // which is one of several filters that list() supports.
  var allAkilesLocks = seam.Devices.List(
    manufacturer: Seam.Api.Devices.ListRequest.ManufacturerEnum.Akiles
  );

  // Select the first device as an example.
  Device frontDoor = allAkilesLocks[0];

  // Inspect specific properties.
  Console.WriteLine(frontDoor.Properties.Online); // true
  Console.WriteLine(frontDoor.Properties.Locked); // true

  // View the entire returned device object.
  Console.WriteLine(frontDoor);
  ```
</CodeGroup>

**Output:**

<CodeGroup>
  ```json JavaScript theme={null}
  true
  true
  {
    device_id: '11111111-1111-1111-1111-444444444444',
    display_name: 'Lock 1',
    workspace_id: '00000000-0000-0000-0000-000000000000',
    connected_account_id: '11111111-1111-1111-1111-222222222222',
    created_at: '2024-05-29T20:08:48.878Z',
    properties: {
      manufacturer: 'akiles',
      online: true,
      locked: true,
      ...
    },
    can_remotely_unlock: true,
    can_program_online_access_codes: true,
    ...
  }
  ```

  ```json cURL theme={null}
  Online (true): true
  Locked (true): true
  {
    "device_id": "11111111-1111-1111-1111-444444444444",
    "display_name": "Lock 1",
    "workspace_id": "00000000-0000-0000-0000-000000000000",
    "connected_account_id": "11111111-1111-1111-1111-222222222222",
    "created_at": "2024-05-29T20:08:48.878Z",
    "properties": {
      "manufacturer": "akiles",
      "locked": true,
      "online": true,
      ...
    },
    "can_remotely_unlock": true,
    "can_program_online_access_codes": true,
    ...
  }
  ```

  ```json Python theme={null}
  Device(
    device_id='11111111-1111-1111-1111-444444444444',
    display_name='Lock 1',
    workspace_id='00000000-0000-0000-0000-000000000000'
    connected_account_id='11111111-1111-1111-1111-222222222222',
    created_at='2024-05-29T20:08:48.878Z',
    properties={
      'manufacturer': 'akiles',
      'online': True,
      'locked': True,
      ...
    }
    can_remotely_unlock=True,
    can_program_online_access_codes=True,
    ...
  )
  ```

  ```json Ruby theme={null}
  true
  true
  <
    Seam::Device:0x00438
      device_id="11111111-1111-1111-1111-444444444444"
      display_name="Lock 1"
      workspace_id="00000000-0000-0000-0000-000000000000"
      connected_account_id="11111111-1111-1111-1111-222222222222"
      created_at=2024-05-29 20:08:48.878 UTC
      properties={
        "manufacturer"=>"akiles",
        "online"=>true,
        "locked"=>true,
        ...
      }
      can_remotely_unlock=true
      can_program_online_access_codes=true
      ...
  >
  ```

  ```json PHP theme={null}
  true
  true
  {
    "device_id": "11111111-1111-1111-1111-444444444444",
    "display_name": "Lock 1",
    "workspace_id": "00000000-0000-0000-0000-000000000000"
    "connected_account_id": "11111111-1111-1111-1111-222222222222",
    "created_at": "2024-05-29T20:08:48.878Z",
    "properties": {
      "manufacturer": "akiles",
      "online": true,
      "locked": true,
      ...
    },
    "can_remotely_unlock": true,
    "can_program_online_access_codes": true,
    ...
  }
  ```

  ```json C# theme={null}
  True
  True
  {
    "device_id": "11111111-1111-1111-1111-444444444444",
    "display_name": "Lock 1",
    "workspace_id": "00000000-0000-0000-0000-000000000000",
    "connected_account_id": "11111111-1111-1111-1111-222222222222",
    "created_at": "2024-05-29T20:08:48.878Z",
    "properties": {
      "manufacturer": "akiles",
      "online": true,
      "locked": true,
      ...
    },
    "can_remotely_unlock": true,
    "can_program_online_access_codes": true,
    ...
  }
  ```
</CodeGroup>

***

## Step 4: Control your Akiles lock

Next, you can use the Seam API to control your lock.

Each device that you connect to Seam has a specific set of capabilities. These capabilities define the Seam API actions that you can use, such as [remote unlock actions](/low-level-apis/smart-locks/lock-and-unlock), [programming access codes](/low-level-apis/smart-locks/access-codes), and so on. Seam's intuitive and granular [capability flags](/capability-guides/device-and-system-capabilities#capability-flags) inform your application about what features and behaviors each device supports. Notice the capability flags within the code samples in this guide.

Try out the following actions on your Akiles lock:

* [ ] [Unlock your lock](#unlock-your-lock)
* [ ] [Program access codes on your lock](#program-access-codes-on-your-lock)

### Unlock your lock

To unlock a door, use the [Unlock Door](/api/locks/unlock_door) endpoint. Specify the device that you want to unlock by including the `device_id` in the request body. This endpoint returns an [action attempt](/core-concepts/action-attempts) to track the progress of the unlock operation.

**Code:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  // Confirm that the device can remotely unlock.
  // You're using a capability flag here!
  if (frontDoor.can_remotely_unlock) {
    // Perform the unlock operation
    // and return an action attempt.
    const actionAttempt = await seam.locks.unlockDoor({
      device_id: frontDoor.device_id,
    })
  }
  ```

  ```bash cURL theme={null}
  # Confirm that the device can remotely unlock.
  # You're using a capability flag here!
  if  $(jq -r '.can_remotely_lock' <<< ${front_door}); then \
    # Perform the unlock operation
    # and return an action attempt.
    curl -X 'POST' \
      'https://connect.getseam.com/locks/unlock_door' \
      -H 'accept: application/json' \
      -H "Authorization: Bearer ${SEAM_API_KEY}" \
      -H 'Content-Type: application/json' \
      -d "{
        \"device_id\": \"$(jq -r '.device_id' <<< ${front_door})\"
    }";
  fi
  ```

  ```python Python theme={null}
  # Confirm that the device can remotely unlock.
  # You're using a capability flag here!
  if front_door.can_remotely_unlock:
    # Perform the unlock operation
    # and return an action attempt.
    action_attempt=seam.locks.unlock_door(device_id=front_door.device_id)
  ```

  ```ruby Ruby theme={null}
  # Confirm that the device can remotely unlock.
  # You're using a capability flag here!
  if (front_door.can_remotely_unlock)
    # Perform the unlock operation
    # and return an action attempt.
    action_attempt = seam.locks.unlock_door(device_id: front_door.device_id)
  end
  ```

  ```php PHP theme={null}
  // Confirm that the device can remotely unlock.
  // You're using a capability flag here!
  if ($front_door->can_remotely_unlock) {
    // Perform the unlock operation
    // and return an action attempt.
    $action_attempt = $seam->locks->unlock_door(device_id: $front_door->device_id);
  }
  ```

  ```csharp C# theme={null}
  // Confirm that the device can remotely unlock.
  // You're using a capability flag here!
  if (frontDoor.CanRemotelyUnlock == true) {
    // Perform the unlock operation
    // and return an action attempt.
    ActionAttempt actionAttempt = seam.Locks.UnlockDoor(deviceId: frontDoor.DeviceId);
  }
  ```
</CodeGroup>

**Output:**

<CodeGroup>
  ```json JavaScript theme={null}
  {
    "actionAttempt": {
      "status": "success",
      "action_attempt_id": "11111111-2222-3333-4444-555555555555",
      "action_type": "UNLOCK_DOOR",
      "result": {},
      "error": null
    }
  }
  ```

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

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

  ```json Ruby theme={null}
  <Seam::ActionAttempt:0x00438
    status="pending"
    action_type="UNLOCK_DOOR"
    action_attempt_id="11111111-2222-3333-4444-555555555555"
    result=nil>
  ```

  ```json PHP theme={null}
  {
    "action_attempt_id": "11111111-2222-3333-4444-555555555555",
    "action_type": "UNLOCK_DOOR",
    "error": null,
    "result": {},
    "status": "success"
  }
  ```

  ```json C# theme={null}
  {
    "status": "pending",
    "action_type": "UNLOCK_DOOR",
    "action_attempt_id": "11111111-2222-3333-4444-555555555555"
  }
  ```
</CodeGroup>

You can track the status of the unlock operation to confirm that the device unlocked successfully. Query the `locked` status of the device, [retrieve the action attempt](/api/action_attempts/get) by ID, or look for a [`lock.unlocked` event](/api/locks/events#lock-unlocked).

To query the `locked` status of the device:

**Code:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  // Get the device by ID.
  const updatedFrontDoor = await seam.devices.get({device_id: frontDoor.device_id});

  // Inspect the locked property to confirm
  // that the unlock operation was successful.
  console.log(updatedFrontDoor.properties.locked); // false
  ```

  ```bash cURL theme={null}
  # Get the device by ID.
  updated_front_door=$(
    # Use GET or POST.
    curl -X 'GET' \
      'https://connect.getseam.com/devices/get' \
      -H 'accept: application/json' \
      -H "Authorization: Bearer ${SEAM_API_KEY}" \
      -H 'Content-Type: application/json' \
      -d "{
        \"device_id\": \"$(jq -r '.device_id' <<< ${front_door})\"
    }")

  # Inspect the locked property to confirm
  # that the unlock operation was successful.
  echo $(jq -r '"Locked (false): " + (.device.properties.locked | tostring)' <<< ${updated_front_door})
  ```

  ```python Python theme={null}
  # Get the device by ID.
  updated_front_door = seam.devices.get(device_id=front_door.device_id)

  # Inspect the locked property to confirm
  # that the unlock operation was successful.
  assert updated_front_door.properties["locked"] is False # False
  ```

  ```ruby Ruby theme={null}
  # Get the device by ID.
  updated_front_door = seam.devices.get(device_id: front_door.device_id)

  # Inspect the locked property to confirm
  # that the unlock operation was successful.
  puts updated_front_door.properties.locked # false
  ```

  ```php PHP theme={null}
  // Get the device by ID.
  $updated_front_door = $seam->devices->get(device_id: $front_door->device_id);

  // Inspect the locked property to confirm
  // that the unlock operation was successful.
  echo $updated_front_door->properties->locked ? 'true' : 'false', "\n"; // false
  ```

  ```csharp C# theme={null}
  // Get the device by ID.
  Device updatedFrontDoor = seam.Devices.Get(
    deviceId: frontDoor.DeviceId
  );

  // Inspect the locked property to confirm
  // that the unlock operation was successful.
  Console.WriteLine(updatedFrontDoor.Properties.Locked); // false
  ```
</CodeGroup>

**Output:**

<CodeGroup>
  ```json JavaScript theme={null}
  false
  ```

  ```json cURL theme={null}
  Locked (false): false
  ```

  ```json Python theme={null}
  False
  ```

  ```json Ruby theme={null}
  false
  ```

  ```json PHP theme={null}
  false
  ```

  ```json C# theme={null}
  False
  ```
</CodeGroup>

***

### Program access codes on your lock

You can use the Seam API to program [online access codes](/low-level-apis/smart-locks/access-codes) on Akiles locks that have an integrated keypad or an Akiles Pinpad. Lock users can then enter these access codes using the keypad or Pinpad to unlock the lock.

The Seam API makes it easy to program both [ongoing](/low-level-apis/smart-locks/access-codes#ongoing-access-codes) and [time-bound](/low-level-apis/smart-locks/access-codes#time-bound-access-codes) online access codes.

**Code:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  // Confirm that the device supports online access codes.
  // Here's another capability flag!
  if (updatedFrontDoor.can_program_online_access_codes) {
    // Create an ongoing online access code.
    await seam.accessCodes.create({
      device_id: updatedFrontDoor.device_id,
      name: 'my ongoing code',
      code: '1234',
    })
    // Create a time-bound online access code.
    await seam.accessCodes.create({
      device_id: updatedFrontDoor.device_id,
      name: 'my time-bound code',
      starts_at: '2025-01-01T16:00:00Z',
      ends_at: '2025-01-22T12:00:00Z',
      code: '2345',
    })
    // List all access codes for this device.
    const accessCodes = await seam.accessCodes.list({
      device_id: updatedFrontDoor.device_id,
    })
    console.log(accessCodes)
  }
  ```

  ```bash cURL theme={null}
  # Confirm that the device supports online access codes.
  # Here's another capability flag!
  if  $(jq -r '.device.can_program_online_access_codes' <<< ${updated_front_door}); then \
    # Create an ongoing online access code.
    curl -X 'POST' \
      'https://connect.getseam.com/access_codes/create' \
      -H 'accept: application/json' \
      -H "Authorization: Bearer ${SEAM_API_KEY}" \
      -H 'Content-Type: application/json' \
      -d "{
        \"device_id\": \"$(jq -r '.device.device_id' <<< ${updated_front_door})\",
        \"name\": \"my ongoing code\",
        \"code\": \"1234\"
    }"
    # Create a time-bound online access code.
    curl -X 'POST' \
      'https://connect.getseam.com/access_codes/create' \
      -H 'accept: application/json' \
      -H "Authorization: Bearer ${SEAM_API_KEY}" \
      -H 'Content-Type: application/json' \
      -d "{
        \"device_id\": \"$(jq -r '.device.device_id' <<< ${updated_front_door})\",
        \"name\": \"my time-bound code\",
        \"starts_at\": \"2025-01-01T16:00:00Z\",
        \"ends_at\": \"2025-01-22T12:00:00Z\",
        \"code\": \"2345\"
    }"
    # List all access codes for this device.
    access_codes=$(
    # Use GET or POST.
    curl -X 'GET' \
      'https://connect.getseam.com/access_codes/list' \
      -H 'accept: application/json' \
      -H "Authorization: Bearer ${SEAM_API_KEY}" \
      -H 'Content-Type: application/json' \
      -d "{
        \"device_id\": \"$(jq -r '.device.device_id' <<< ${updated_front_door})\"
    }")
    echo ${access_codes};
  fi
  ```

  ```python Python theme={null}
  # Confirm that the device supports online access codes.
  # Here's another capability flag!
  if updated_front_door.can_program_online_access_codes:
    # Create an ongoing online access code.
    seam.access_codes.create(
      device_id = updated_front_door.device_id,
      name = "my ongoing code",
      code = "1234"
    )
    # Create a time-bound online access code.
    seam.access_codes.create(
      device_id = updated_front_door.device_id,
      name = "my time-bound code",
      starts_at = "2025-01-01T16:00:00Z",
      ends_at = "2025-01-22T12:00:00Z",
      code = "2345"
    )
    # List all access codes for this device.
    access_codes = seam.access_codes.list(
      device_id = updated_front_door.device_id
    )
    pprint(access_codes)
  ```

  ```ruby Ruby theme={null}
  # Confirm that the device supports online access codes.
  # Here's another capability flag!
  if (updated_front_door.can_program_online_access_codes)
    # Create an ongoing online access code.
    seam.access_codes.create(
      device_id: updated_front_door.device_id,
      name: "my ongoing code",
      code: "1234"
    )
    # Create a time-bound online access code.
    seam.access_codes.create(
      device_id: updated_front_door.device_id,
      name: "my time-bound code",
      starts_at: "2025-01-01T16:00:00Z",
      ends_at: "2025-01-22T12:00:00Z",
      code: "2345"
    )
    # List all access codes for this device.
    access_codes = seam.access_codes.list(
      device_id: updated_front_door.device_id
    )
    puts access_codes.inspect
  end
  ```

  ```php PHP theme={null}
  // Confirm that the device supports online access codes.
  // Here's another capability flag!
  if ($updated_front_door->can_program_online_access_codes) {
    // Create an ongoing online access code.
    $seam->access_codes->create(
      device_id: $updated_front_door->device_id,
      name: "my ongoing code",
      code: "1234"
    );
    // Create a time-bound online access code.
    $seam->access_codes->create(
      device_id: $updated_front_door->device_id,
      name: "my time-bound code",
      starts_at:  "2025-01-01T16:00:00Z",
      ends_at: "2025-01-22T12:00:00Z",
      code: "2345"
    );
    // List all access codes for this device.
    $access_codes = $seam->access_codes->list(
      device_id: $updated_front_door->device_id
    );
    echo json_encode($access_codes, JSON_PRETTY_PRINT);
  }
  ```

  ```csharp C# theme={null}
  // Confirm that the device supports online access codes.
  // Here's another capability flag!
  if (updatedFrontDoor.CanProgramOnlineAccessCodes == true) {
    // Create an ongoing online access code.
    seam.AccessCodes.Create(
      deviceId: updatedFrontDoor.DeviceId,
      name: "my ongoing code",
      code: "1234"
    );
    // Create a time-bound online access code.
    seam.AccessCodes.Create(
      deviceId: updatedFrontDoor.DeviceId,
      name: "my time-bound code",
      startsAt: "2025-01-01T16:00:00Z",
      endsAt: "2025-01-22T12:00:00Z",
      code: "2345"
    );
    // List all access codes for this device.
    var accessCodes = seam.AccessCodes.List(
      deviceId: updatedFrontDoor.DeviceId
    );
    foreach (var accessCode in accessCodes)
    {
      Console.WriteLine(accessCode);
    }
  }
  ```
</CodeGroup>

**Output:**

<CodeGroup>
  ```json JavaScript theme={null}
  [
    {
      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-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',
      ...
    }
  ]
  ```

  ```json cURL theme={null}
  {
    "access_codes": [
      {
        "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-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
  }
  ```

  ```json Python theme={null}
  [
    AccessCode(
      access_code_id='11111111-1111-1111-1111-555555555555',
      device_id='11111111-1111-1111-1111-444444444444',
      type='ongoing',
      code='1234',
      name='my ongoing code',
      ...
    )
    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',
      ...
    )
  ]
  ```

  ```json Ruby theme={null}
  [
    <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"
      ...
    >,
    <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
      ...
    >
  ]
  ```

  ```json PHP theme={null}
  [
    {
      "access_code_id": "11111111-1111-1111-1111-555555555555",
      "device_id": "11111111-1111-1111-1111-444444444444",
      "name": "my ongoing code",
      "type": "ongoing",
      "code": "1234",
      ...
    },
    {
      "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",
    }
  ]
  ```

  ```json C# theme={null}
  {
    "type": "ongoing",
    "access_code_id": "11111111-1111-1111-1111-555555555555",
    "device_id": "11111111-1111-1111-1111-444444444444",
    "name": "my ongoing code",
    "code": "1234",
    ...
  }
  {
    "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",
    ...
  }
  ```
</CodeGroup>

***

## Step 5: Connect a real Akiles lock

Now that you have learned the basics of using the Seam API, you can connect and control a real Akiles device. To do so, make sure to switch to a [non-sandbox workspace](/core-concepts/workspaces#production-workspaces) and [API key](/core-concepts/authentication/api-keys).

For more details about setting up your real Akiles lock, see the [Akiles locks integration guide](./).

***

## Step 6: Build your application!

Seam makes it easy to develop your application. In addition to the robust Seam API and the wide variety of programming languages that our SDKs support, we also provide a suite of [Seam Components](/ui-components/overview). These prebuilt UI components help you to build your device management flow.

For example, you can use the [Device Table Seam Component](/ui-components/overview/react-components/device-table) to display a list of devices and to identify all devices with issues. You can use the [Device Details Seam Component](/ui-components/overview/react-components/device-details) to display a device's properties, settings, and issues, as well as to enable your users to perform actions based on each device's capabilities. The [Access Code Details Seam Component](/ui-components/overview/react-components/access-code-details) provides a similar display and actions for access codes.

Seam Components use a responsive design to fit seamlessly on any screen size. They also provide device debugging flows to help your users.

To learn about all the Seam Components that we provide, see [Seam Components](/ui-components/overview).

***

## Next steps

Now that you've completed this getting started guide for Akiles devices, you can learn more about what you can do with the Seam API.

* [ ] **Explore**\
  See the [other devices and system integrations](/device-and-system-integration-guides) that Seam supports.
* [ ] **Learn**\
  Read about Seam [concepts](/core-concepts/overview) and the [device and system capabilities ](/capability-guides/device-and-system-capabilities)that Seam supports.
* [ ] **Use Seam Components**\
  Find out about [Seam Components](/ui-components/overview), which are prebuilt UI components for building your device management flow.
* [ ] **Use webhooks**\
  Learn how to use [webhooks](/developer-tools/webhooks) as an efficient way to receive device events.
* [ ] **Find out more**\
  Explore the other types of devices and systems that you can control with Seam, including [access control systems](/low-level-apis/access-systems), [thermostats](/capability-guides/thermostats), and [noise sensors](/capability-guides/noise-sensors).
* [ ] **Develop for mobile access**\
  Learn about Seam's [mobile access solution](/capability-guides/mobile-access).

<Info>
  If you have any questions or want to report an issue, email us at
  [support@seam.co](mailto:support@seam.co).
</Info>

***

## Quick links

<CardGroup>
  <Card title="Get an API Key (free)" href="https://console.seam.co/">
    Sign up for the Seam Console and get your API keys. →
  </Card>

  <Card title="Contact Sales" href="https://www.seam.co/contact-us">
    Got a project or a specific question? Contact our team to get answers. →
  </Card>
</CardGroup>


# Akiles Locks
Source: https://docs.seam.co/device-and-system-integration-guides/akiles-locks/index

Guide for using Akiles locks with Seam

<img alt="akiles logo" />

## Overview

[Akiles](https://akiles.app/en) is a Barcelona-based company that produces smart lock products for the European market. These offerings include the Smart Cylinder, Roomlock, and Pinpad, as well as the Smart Controller for electrified locks and access points. Akiles also offers the Akiles Gateway and Akiles Cloud. Seam integrates with Akiles through the Akiles Gateway to provide remote unlock functionality and access code creation and management.

***

## Supported Devices

<DeviceList />

This integration supports all Akiles locks. These locks require the [Akiles Gateway](https://akiles.app/en/products/smart-lock-system-gateway). Seam also supports the addition of the optional [Akiles Pinpad](https://akiles.app/en/products/smart-lock-system-pinpad) to enable entering access codes for devices that do not have an integrated keypad.

The following table details the requirements for compatibility with this Seam integration:

<table>
  <thead>
    <tr>
      <th>Capability</th>
      <th>Required Accessories</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Remote unlock</td>

      <td>
        <ul>
          <li>Akiles Gateway</li>
        </ul>
      </td>
    </tr>

    <tr>
      <td>Access codes</td>

      <td>
        <ul>
          <li>Akiles Gateway</li>

          <li>
            Akiles Pinpad (if the device does not have an integrated keypad)
          </li>
        </ul>
      </td>
    </tr>
  </tbody>
</table>

For detailed information about the Akiles devices that Seam supports, see our [Akiles Supported Devices page](https://www.seam.co/manufacturers/akiles):

***

## Supported Features

We support the following features:

* [Triggering web unlock actions](/low-level-apis/smart-locks/lock-and-unlock)
* [Programming access codes](/low-level-apis/smart-locks/access-codes) on devices that have an integrated keypad or Akiles Pinpad

***

### Device Provider Key

Seam identifies these devices with the `akiles` device provider key. By default, a [Connect Webview](/core-concepts/connect-webviews) displays all of the stable providers that Seam supports, so your users can connect their Tedee devices without you specifying a provider list. To narrow what a Connect Webview displays, see [Customize the Brands to Display in Your Connect Webviews](/core-concepts/connect-webviews/customizing-connect-webviews#customize-the-brands-to-display-in-your-connect-webviews).

***

## Setup Instructions

For instructions on connecting Akiles locks to Seam, see the [Akiles Setup Guide](./akiles-setup-guide).

***

## Where to Order

To purchase Akiles devices, contact the Akiles sales team.

<table>
  <thead>
    <tr>
      <th />

      <th />

      <th />

      <th />

      <th />
    </tr>
  </thead>

  <tbody>
    <tr>
      <td />

      <td>
        <strong>Akiles Contact Page</strong>
      </td>

      <td />

      <td>
        <a href="https://akiles.app/en/contact">
          [https://akiles.app/en/contact](https://akiles.app/en/contact)
        </a>
      </td>

      <td>
        <a href="/images/akiles-logo.png">akiles-logo.png</a>
      </td>
    </tr>
  </tbody>
</table>

***


# Sandbox Akiles Locks
Source: https://docs.seam.co/device-and-system-integration-guides/akiles-locks/sandbox-akiles-locks

Add virtual Akiles locks to your Seam sandbox workspace using these sample credentials to test your integration without real hardware.

Use the following set of credentials to add virtual [Akiles locks](/device-and-system-integration-guides/akiles-locks) to your Seam [sandbox workspace](/core-concepts/workspaces#sandbox-workspaces):

| Email Address                               | Password |
| ------------------------------------------- | -------- |
| [jane@example.com](mailto:jane@example.com) | 1234     |


# Sandbox Assa Abloy Visionline Access Control System
Source: https://docs.seam.co/device-and-system-integration-guides/assa-abloy-visionline-access-control-system/assa-abloy-visionline-access-management-system-sample-data

Add virtual ASSA ABLOY Visionline access control system devices to your Seam sandbox workspace using these sample credentials to test your integration.

Use the following set of credentials to add virtual [ASSA ABLOY Visionline Access Control System](/device-and-system-integration-guides/assa-abloy-visionline-access-control-system)-connected devices to your Seam [sandbox workspace](/core-concepts/workspaces#sandbox-workspaces):

<Info>
  To use the virtual Vostio Access System to issue mobile keys in a sandbox
  workspace, you must also connect a [virtual ASSA ABLOY Credential
  Services](/device-and-system-integration-guides/assa-abloy-vingcard-credential-services).
</Info>

## Sandbox Seam Bridge Connection Credentials

| Pairing Token |
| ------------- |
| prefilled     |

## Visionline Credentials

<table>
  <thead>
    <tr>
      <th>Visionline Site Name</th>
      <th>Username</th>
      <th>Password</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        Any string to identify this Visionline ACS site, for example, My
        Visionline Site
      </td>

      <td>jane</td>
      <td>1234</td>
    </tr>
  </tbody>
</table>

## Mobile Key Information

If you plan to create mobile keys, select the **Mobile Keys will be issued in this system** field and specify the following information:

| Mobile Access UUID | System ID |
| ------------------ | --------- |
| 1                  | 1         |

## Seam Bridge Connection Information

Normally, leave the **Seam Bridge and Visionline server are installed on different computers** field unchecked.\
If you choose to select this field, type `https://192.168.1.100` in the **LAN URL of the Visionline server** field.


# Common Use Cases
Source: https://docs.seam.co/device-and-system-integration-guides/assa-abloy-visionline-access-control-system/common-use-cases

Learn how to meet the ASSA ABLOY scenario requirements for integrating with the Visionline system.

When integrating with the Visionline system, ASSA ABLOY requires handling a set of common scenarios to meet their integration requirements. Learn how to accomplish some of these key scenarios.

## Issue Guest Mobile Credentials

* [Issue a credential for a single guest in a single room.](./configuring-visionline-mobile-credentials/issuing-various-types-of-guest-mobile-credentials#single-guest-in-a-single-room)
* [Issue a credential for a returning guest to a single room.](./configuring-visionline-mobile-credentials/issuing-various-types-of-guest-mobile-credentials#returning-guest-to-a-single-room)
* [Issue credentials for multiple guests in multiple rooms.](./configuring-visionline-mobile-credentials/issuing-various-types-of-guest-mobile-credentials#multiple-guests-in-multiple-rooms)

```python theme={null}
acs_user = seam.acs.user.get(acs_user_id="xxx")

new_guest_room = seam.acs.entrances.list(
  acs_system_id=hotel_acs_system_id
)[0]

seam.acs.credentials.create(
  acs_user_id=acs_user.acs_user_id
  credential_manager_acs_system_id="xxx"
  is_multi_phone_sync_credential=True,
  access_method="mobile_key",
  starts_at="2023-01-01 10:40:00.000",
  ends_at="2023-01-04 10:40:00.000",
  allowed_acs_entrance_ids=[
    new_guest_room.acs_entrance_id,
    main_entrance.acs_entrance_id
  ],
  visionline_metadata={
    "cardFormat": "rfid48",
    "cardType": "guest",
    "label": "%ROOMNUM% - %SITENAME%",
    "is_override_key": True
  }
)
```

```python theme={null}
guest_room_1 = seam.acs.entrances.list(
  acs_system_id=hotel_acs_system_id
)[0]

guest_room_2 = seam.acs.entrances.list(
  acs_system_id=hotel_acs_system_id
)[0]

first_acs_user = seam.acs.user.get(acs_user_id="xxx")

# First credential should be an override credential.
first_credential = seam.acs.credentials.create(
  acs_user_id=first_acs_user.acs_user_id
  credential_manager_acs_system_id="xxx"
  is_multi_phone_sync_credential=True,
  access_method="mobile_key",
  starts_at="2023-01-01 10:40:00.000",
  ends_at="2023-01-04 10:40:00.000",
  allowed_acs_entrance_ids=[
    guest_room_1.acs_entrance_id,
    guest_room_2.acs_entrance_id,
    main_entrance.acs_entrance_id
  ],
  visionline_metadata={
    "cardFormat": "rfid48",
    "cardType": "guest",
    "label": "%ROOMNUM% - %SITENAME%",
    "is_override_key": True
  }
)

second_acs_user = seam.acs.user.get(acs_user_id="yyy")

# Subsequent credentials should be joiners to the first credential.
seam.acs.credentials.create(
  acs_user_id=second_acs_user.acs_user_id
  credential_manager_acs_system_id="xxx"
  is_multi_phone_sync_credential=True,
  access_method="mobile_key",
  starts_at="2023-01-01 10:40:00.000",
  ends_at="2023-01-04 10:40:00.000",
  allowed_acs_entrance_ids=[
    guest_room_1.acs_entrance_id,
    guest_room_2.acs_entrance_id,
    main_entrance.acs_entrance_id
  ],
  visionline_metadata={
    "cardFormat": "rfid48",
    "cardType": "guest",
    "label": "%ROOMNUM% - %SITENAME%",
    "joiner_acs_credential_ids": [first_credential.acs_credential_id]
  }
)
```

***

## Issue Joiner Mobile Credentials

* [Join to a Seam mobile credential.](./configuring-visionline-mobile-credentials/issuing-various-types-of-guest-joiner-mobile-credentials#join-to-a-seam-mobile-credential)
* [Join to a plastic card.](./configuring-visionline-mobile-credentials/issuing-various-types-of-guest-joiner-mobile-credentials#join-to-a-plastic-card)

```python theme={null}
joiners = [joiner_mobile_parent_sync_credential, joiner_mobile_child_credential]

# Create the mobile credential.
cred = seam.acs.credentials.create({
  acs_user_id: "xxx",
  credential_manager_acs_system_id="xxs"
  is_multi_phone_sync_credential: True,
  access_method = "mobile_key",
  starts_at: "2023-01-01 10:40:00.000",
  ends_at: "2023-01-04 10:40:00.000",
  visionline_metadata: {
    "cardFormat": "rfid48",
    "label": "%ROOMNUM% - %SITENAME%",
    "joiner_acs_credential_ids": [
      joiner.acs_credential_id for joiner in joiners
    ]
  }
})
```

***

## Additional Scenarios

* [Update guest mobile credentials.](./configuring-visionline-mobile-credentials/updating-guest-mobile-credentials)
* [Revoke a mobile credential.](./configuring-visionline-mobile-credentials/revoking-mobile-credentials)
* [Remove a user identity.](/api/user_identities/delete)


# Checking if a User Identity Has a Phone That Is Set up for a Credential Manager
Source: https://docs.seam.co/device-and-system-integration-guides/assa-abloy-visionline-access-control-system/configuring-visionline-mobile-credentials/checking-if-a-user-identity-has-a-phone-that-is-set-up-for-a-credential-manager

Learn how to determine when your app should disable the override credential option for guest credentials.

To issue an [override guest credential](/device-and-system-integration-guides/assa-abloy-visionline-access-control-system/configuring-visionline-mobile-credentials#issue-the-first-credential-for-a-reservation) to an app user, the app user must first set up their phone. If you want to disable the "override" option where it's not available, you can use the following check before allowing a user to configure an override credential:

<CodeGroup>
  ```python Python theme={null}
  def has_active_endpoint(user_identity_id):
      phones = seam.phones.list({
          owner_user_identity_id=user_identity_id
      })
      for phone in phones:
          metadata = phone.get('assa_abloy_credential_service_metadata', {})
          if metadata.get('has_active_endpoint'):
              return True
      return False

  # Check if any phone has an active endpoint.

  user_identity = seam.user_identities.get(phone_number="1234567890")
  active_endpoint_exists = has_active_endpoint(user_identity.user_identity_id)

  ```
</CodeGroup>

## Example of Disabling the Override Option When It's Not Available

```
```


# Configuring Visionline Mobile Credentials
Source: https://docs.seam.co/device-and-system-integration-guides/assa-abloy-visionline-access-control-system/configuring-visionline-mobile-credentials/index

Learn how to configure Visionline mobile credentials.

In the ASSA ABLOY Visionline Access Management System, locks are standalone and battery-powered. All access permissions and scheduling details are contained within the key cards and mobile credentials, characterizing these systems as "data-on-card" systems.

This guide describes how to issue guest and staff mobile credentials on the Visionline ACS.

## Access Permission Assignment for Visionline

Visionline is a [credential-based access control system](/low-level-apis/access-systems/connect-an-acs-to-seam/understanding-access-control-system-differences#credential-based-access-control-systems). That is, you create ACS users and credentials. Within these credentials, you specify the set of entrances to which you want to grant access and the schedules for this access.

### Credential Types for Visionline

When creating credentials, you can configure [guest](#issuing-guest-mobile-credentials) mobile credentials for a Visionline ACS. Guest credentials are further subdivided into [override](#issue-the-first-credential-for-a-reservation) and [joiner](#issue-subsequent-credentials-for-a-reservation) credentials. An override credential serves as the first access grant for a reservation and revokes all previous guest access to the included guest room entrances. When a reservation includes multiple guests who need access, all subsequent access grants for the same reservation are joiner credentials. This type of credential provides shared access that matches the grants of existing credentials. For more details, see the following sections:

* [Guest Mobile Credential Types](#guest-mobile-credential-types)
* [Issue the First Credential for a Reservation](#issue-the-first-credential-for-a-reservation)
* [Issue Subsequent Credentials for a Reservation](#issue-subsequent-credentials-for-a-reservation)

<Info>
  Seam currently only supports issuing guest mobile credentials and plastic
  cards.
</Info>

### Access Grant Process for Visionline

Use the following basic process to grant access in a Visionline ACS:

1. Set up the mobile user account by creating a [user identity](/capability-guides/mobile-access/managing-mobile-app-user-accounts-with-user-identities#what-is-a-user-identity).
2. Associate the user identity with an [ACS user](/low-level-apis/access-systems).
3. Gather the entrances to which the credential should have access.
4. Create the [guest](#issuing-guest-mobile-credentials) mobile credential.

***

## Issuing Guest Mobile Credentials

To issue a guest mobile credential for the Visionline ACS, create a credential with `visionline_metadata.card_function_type` set to `guest`. Also, for a guest credential, you normally set `visionline_metadata.card_format` to `rfid48`, unless the guest needs a higher-capacity `TLCode` card. For more information about Visionline metadata, see [`acs_credential.visionline_metadata` Properties](/device-and-system-integration-guides/assa-abloy-visionline-access-control-system/mobile-credential-related-properties).

### Guest Mobile Credential Types

Guest mobile credentials consist of two credential types: override credentials and joiner credentials.

When issuing the [first guest credential for a reservation](#issue-the-first-credential-for-a-reservation), a hotel needs to guarantee that all previous access to the guest room entrance is revoked. To revoke all other access, you create an override credential that invalidates all previous access to the guest room entrance. That is, an override credential overrides any existing credentials that previously granted access to the same guest room entrance.

Reservations may involve multiple parties. In these situations, hotels often need to provide credentials for the same guest room entrances to additional guests. To do so, [issue "joiner credentials."](#issue-subsequent-credentials-for-a-reservation) This type of credential allows shared access with any existing credentials that already grant entry to the same guest room entrances.

***

### Issue the First Credential for a Reservation

To issue the first guest credential for a reservation, create an override credential. This credential type invalidates any existing guest access to the target entrances. When creating an override credential, set `visionline_metadata.override` to `true`.

<Info>
  You can also [verify whether a user identity has a phone that is set up for a
  credential
  manager](./checking-if-a-user-identity-has-a-phone-that-is-set-up-for-a-credential-manager)
  and, consequently, is ready to accept an override guest credential.
</Info>

<CodeGroup>
  ```python Python theme={null}
  # Set up the mobile user account.
  user_identity = seam.user_identities.create(
      user_identity_key="xxx"
  )

  # Associate the user identity with the ACS user.

  acs_user = seam.acs.users.get(
  email="jane@example.com"
  )
  seam.user_identities.add_acs_user(
  user_identity=user_identity.user_identity_id,
  acs_user_id=acs_user.acs_user_id
  )

  # Gather entrances to which the credential should have access.

  room_entrance = seam.acs.entrances.get(name=f"Room {room_number}")
  common_door = seam.acs.entrances.get(name=f"Main Entrance")

  # Check whether the user identity has an active endpoint on their phones.

  # To learn how to verify this condition, see "Check if a user identity has

  # a phone that is set up for a credential manager."

  if has_active_endpoint(user_identity.user_identity_id):

  # Create the override mobile credential.

  cred = seam.acs.credentials.create(
  acs_user_id="xxx",
  credential_manager_acs_system_id="xx"
  is_multi_phone_sync_credential=True,
  access_method="mobile_key",
  starts_at="2023-01-01 10:40:00.000",
  ends_at="2023-01-04 10:40:00.000"
  allowed_acs_entrance_ids=[
  room_entrance.acs_entrance_id,
  common_door.acs_entrance_id
  ],
  visionline_metadata={
  "cardFormat": "rfid48",
  "label": "%ROOMNUM% - %SITENAME%",
  "override": True
  }
  )

  ```
</CodeGroup>

***

### Issue Subsequent Credentials for a Reservation

Once you have created an override mobile credential as the first credential for a reservation, you can issue mobile credentials to additional guests on the same reservation. To do so, issue "joiner credentials." This type of credential allows shared access with any existing credentials that already grant entry to the same guest room entrances. Note that you can create joiner mobile credentials that provide access to guest room entrances, common entrances, or both.

For example:

* You already created an override mobile credential to grant a guest access to hotel rooms 101 and 102. Now, you create a joiner mobile credential that grants a different guest on the same reservation access to the same two hotel rooms.
* You already created an override mobile credential to grant a guest access to hotel rooms 101 and 102. Now, you create a joiner mobile credential that grants a different guest on the same reservation access to hotel room 101 only.

To issue a joiner credential, you must specify both the entrances to which to grant access and the credentials with which to associate the new joiner credential. Use the following properties:

* `allowed_acs_entrance_ids`
* `visionline_metadata.joiner_acs_credential_ids`

For instructions on how to retrieve credentials that have overlapping access, see [Issuing Various Types of Guest Joiner Mobile Credentials](./issuing-various-types-of-guest-joiner-mobile-credentials).

<CodeGroup>
  ```python Python theme={null}
  # Set up the mobile user account.
  user_identity = seam.user_identities.create(
      user_identity_key="xxx"
  )

  # Associate the user identity with the ACS user.
  acs_user = seam.acs.users.get(
    email="jane@example.com"
  )
  seam.user_identities.add_acs_user(
    user_identity=user_identity.user_identity_id,
    acs_user_id=acs_user.acs_user_id
  )

  # Gather entrances to which the credential should have access.
  room_entrance = seam.acs.entrances.get(name=f"Room {room_number}")
  common_door = seam.acs.entrances.get(name=f"Main Entrance")

  # Retrieve existing valid credentials for guest doors to add as joiners.
  # Be sure to check that these credentials correspond with the correct
  # reservation.
  joiner1 = seam.acs.credentials.get(id="xxx")
  joiner2 = seam.acs.credentials.get(id="yyy")
  joiners = [joiner1, joiner2]

  # Create the mobile credential.
  cred = seam.acs.credentials.create({
    acs_user_id: "xxx",
    credential_manager_acs_system_id="xxs"
    is_multi_phone_sync_credential: True,
    access_method = "mobile_key",
    starts_at: "2023-01-01 10:40:00.000",
    ends_at: "2023-01-04 10:40:00.000",
    allowed_acs_entrance_ids: [
      common_door.acs_entrance_id,
      room_entrance.acs_entrance_id
    ],
    visionline_metadata: {
      "cardFormat": "rfid48",
      "label": "%ROOMNUM% - %SITENAME%",
      "joiner_acs_credential_ids": [
        joiner['acs_credential_id'] for joiner in joiners
      ]
    }
  })
  ```
</CodeGroup>

<CodeGroup>
  ```python Python theme={null}
  all_entrances = seam.acs.entrances.list(
    acs_system_id=acs_system.acs_system_id
  )

  # Filter for entrances with the common entrance category types.

  common_entrance_category_types = ["common", "common (PMS)"]

  def filter_entrances_by_profile_type(entrance_list, category_types):
  common_entrances = []
  for entrance in entrance_list:
  if entrance["visionline_metadata"]["door_category"] in category_types:
  common_entrances.append(entrance)
  return common_entrances

  common_entrances = filter_entrances_by_profile_type(
  all_entrances,
  common_entrance_category_types
  )

  ```
</CodeGroup>

```
```


# Issuing Various Types of Guest Joiner Mobile Credentials
Source: https://docs.seam.co/device-and-system-integration-guides/assa-abloy-visionline-access-control-system/configuring-visionline-mobile-credentials/issuing-various-types-of-guest-joiner-mobile-credentials

Learn how to issue guest joiner credentials of various types.

In addition to understanding the [basic process for issuing guest joiner credentials](/device-and-system-integration-guides/assa-abloy-visionline-access-control-system/configuring-visionline-mobile-credentials#issue-subsequent-credentials-for-a-reservation), it is useful to know how to issue various specific types of guest joiner credentials.

## Before You Begin

To issue a [joiner credential](/device-and-system-integration-guides/assa-abloy-visionline-access-control-system/configuring-visionline-mobile-credentials#issue-subsequent-credentials-for-a-reservation), you must specify the guest door credentials with which to associate the new joiner credential. To identify and retrieve these existing valid credentials, use the following process:

1. Identify the guest entrances to which you want to issue the joiner credential.
2. Retrieve the existing guest credentials that have been issued for these guest entrances.
3. Issue the joiner credential and include these guest credentials as joiners.

<CodeGroup>
  ```python Python theme={null}
  # Define the list of guest entrances to check.
  guest_entrance_ids = [
      room_101.acs_entrance_id,
      room_102.acs_entrance_id,
  ]

  # Initialize a list to hold credentials for each entrance.

  all_credentials = []

  # Retrieve all valid credentials for each entrance individually.

  for entrance_id in guest_entrance_ids:
  credentials = seam.acs.entrances.list_credentials_with_access(
  acs_entrance_id=entrance_id,
  include_if=["visionline_metadata.is_valid"]
  )
  all_credentials.append({
  "entrance_id": entrance_id,
  "credentials": credentials
  })

  ```
</CodeGroup>

***

## Join to a Seam Mobile Credential

You can select either the multi-phone sync credential or the child credentials. Make sure to get the `acs_credential_id` to include in the `joiner_acs_credential_ids` list.

```python theme={null}
joiners = [joiner_mobile_parent_sync_credential, joiner_mobile_child_credential]

# Create the mobile credential.
cred = seam.acs.credentials.create({
  acs_user_id: "xxx",
  credential_manager_acs_system_id="xxs"
  is_multi_phone_sync_credential: True,
  access_method = "mobile_key",
  allowed_acs_entrance_ids=[
    "xxxx"
  ],
  starts_at: "2023-01-01 10:40:00.000",
  ends_at: "2023-01-04 10:40:00.000",
  visionline_metadata: {
    "cardFormat": "rfid48",
    "label": "%ROOMNUM% - %SITENAME%",
    "joiner_acs_credential_ids": [
      joiner.acs_credential_id for joiner in joiners
    ]
  }
})
```

***

## Join to a Plastic Card

You can join to a plastic card.

```python theme={null}
joiners = [joiner_plastic_card_credential]

# Create the mobile credential.
cred = seam.acs.credentials.create({
    acs_user_id: "xxx",
    credential_manager_acs_system_id="xxs"
    is_multi_phone_sync_credential: True,
    access_method = "mobile_key",
    allowed_acs_entrance_ids=[
        "xxxx"
    ]
    starts_at: "2023-01-01 10:40:00.000",
    ends_at: "2023-01-04 10:40:00.000",
    visionline_metadata: {
        "cardFormat": "rfid48",
        "label": "%ROOMNUM% - %SITENAME%",
        "joiner_acs_credential_ids": [
            joiner.acs_credential_id for joiner in joiners
        ]
    }
})
```


# Issuing Various Types of Guest Mobile Credentials
Source: https://docs.seam.co/device-and-system-integration-guides/assa-abloy-visionline-access-control-system/configuring-visionline-mobile-credentials/issuing-various-types-of-guest-mobile-credentials

Learn how to issue guest mobile credentials of various types.

In addition to understanding the [basic process for issuing guest mobile credentials](/device-and-system-integration-guides/assa-abloy-visionline-access-control-system/configuring-visionline-mobile-credentials#issuing-guest-mobile-credentials), it is useful to know how to issue guest mobile credentials of various types.&#x20;

## Single Guest in a Single Room

To issue a credential for a single guest in a single room, create an [override guest credential](/device-and-system-integration-guides/assa-abloy-visionline-access-control-system/configuring-visionline-mobile-credentials#issue-the-first-credential-for-a-reservation).&#x20;

```python theme={null}
acs_user = seam.acs.user.get(acs_user_id="xxx")

guest_room = seam.acs.entrances.list(
  acs_system_id=hotel_acs_system_id
)[0]

seam.acs.credentials.create(
  acs_user_id=acs_user.acs_user_id
  credential_manager_acs_system_id="xxx"
  is_multi_phone_sync_credential=True,
  access_method="mobile_key",
  starts_at="2023-01-01 10:40:00.000",
  ends_at="2023-01-04 10:40:00.000",
  allowed_acs_entrance_ids=[
    guest_room.acs_entrance_id,
    main_entrance.acs_entrance_id
  ],
  visionline_metadata={
    "cardFormat": "rfid48",
    "cardType": "guest",
    "label": "%ROOMNUM% - %SITENAME%",
    "override": True
  }
)
```

***

## Returning Guest to a Single Room

A new mobile key automatically overrides a previously-issued mobile credential.

```python theme={null}
acs_user = seam.acs.user.get(acs_user_id="xxx")

new_guest_room = seam.acs.entrances.list(
  acs_system_id=hotel_acs_system_id
)[0]

seam.acs.credentials.create(
  acs_user_id=acs_user.acs_user_id
  credential_manager_acs_system_id="xxx"
  is_multi_phone_sync_credential=True,
  access_method="mobile_key",
  starts_at="2023-01-01 10:40:00.000",
  ends_at="2023-01-04 10:40:00.000",
  allowed_acs_entrance_ids=[
    new_guest_room.acs_entrance_id,
    main_entrance.acs_entrance_id
  ],
  visionline_metadata={
    "cardFormat": "rfid48",
    "cardType": "guest",
    "label": "%ROOMNUM% - %SITENAME%",
    "override": True
  }
)
```

***

## Multiple Guests in Multiple Rooms

To issue credentials for multiple guests in multiple rooms, first create an [override guest credential](/device-and-system-integration-guides/assa-abloy-visionline-access-control-system/configuring-visionline-mobile-credentials#issue-the-first-credential-for-a-reservation). Then, create all subsequent guest credentials as [joiners](/device-and-system-integration-guides/assa-abloy-visionline-access-control-system/configuring-visionline-mobile-credentials#issue-subsequent-credentials-for-a-reservation).

```python theme={null}
guest_room_1 = seam.acs.entrances.list(
  acs_system_id=hotel_acs_system_id
)[0]

guest_room_2 = seam.acs.entrances.list(
  acs_system_id=hotel_acs_system_id
)[0]

first_acs_user = seam.acs.user.get(acs_user_id="xxx")

# First credential should be an override credential.
first_credential = seam.acs.credentials.create(
  acs_user_id=first_acs_user.acs_user_id
  credential_manager_acs_system_id="xxx"
  is_multi_phone_sync_credential=True,
  access_method="mobile_key",
  starts_at="2023-01-01 10:40:00.000",
  ends_at="2023-01-04 10:40:00.000",
  allowed_acs_entrance_ids=[
    guest_room_1.acs_entrance_id,
    guest_room_2.acs_entrance_id,
    main_entrance.acs_entrance_id
  ],
  visionline_metadata={
    "cardFormat": "rfid48",
    "cardType": "guest",
    "label": "%ROOMNUM% - %SITENAME%",
    "override": True
  }
)

second_acs_user = seam.acs.user.get(acs_user_id="yyy")

# Subsequent credentials should be joiners to the first credential.
seam.acs.credentials.create(
  acs_user_id=second_acs_user.acs_user_id
  credential_manager_acs_system_id="xxx"
  is_multi_phone_sync_credential=True,
  access_method="mobile_key",
  starts_at="2023-01-01 10:40:00.000",
  ends_at="2023-01-04 10:40:00.000",
  allowed_acs_entrance_ids=[
    guest_room_1.acs_entrance_id,
    guest_room_2.acs_entrance_id,
    main_entrance.acs_entrance_id
  ],
  visionline_metadata={
    "cardFormat": "rfid48",
    "cardType": "guest",
    "label": "%ROOMNUM% - %SITENAME%",
    "joiner_acs_credential_ids": [first_credential.acs_credential_id]
  }
)
```


# Retrieving Guest and Common Entrances
Source: https://docs.seam.co/device-and-system-integration-guides/assa-abloy-visionline-access-control-system/configuring-visionline-mobile-credentials/retrieving-guest-and-common-entrances

Learn how to fetch various types of entrances to help provide more context for your app users.

You can retrieve lists of entrances. You may want to display entrances categorized by type to provide more context to your app users. To fetch only guest or common entrances, filter using the `visionline_metadata.door_category` property for entrances. The value for this property is set within the Visionline ACS.

## Fetch Guest Entrances

To fetch only guest entrances, filter entrances to include only those with a `visionline_metadata.properties.door_category` of `guest`.

<CodeGroup>
  ```python Python theme={null}
  all_entrances = seam.acs.entrances.list(
    acs_system_id=acs_system.acs_system_id
  )

  # Filter for entrances with the guest entrance category type.

  guest_entrance_category_types = ["guest"]

  def filter_entrances_by_profile_type(entrance_list, category_types):
  guest_entrances = []
  for entrance in entrance_list:
  if entrance["visionline_metadata"]["door_category"] in category_types:
  guest_entrances.append(entrance)
  return guest_entrances

  guest_entrances = filter_entrances_by_profile_type(
  all_entrances,
  guest_entrance_category_types
  )

  ```
</CodeGroup>

***

## Fetch Common Entrances

To fetch only common entrances, filter entrances to include only those with a `visionline_metadata.properties.door_category` of `common` or `common (PMS)`.

<CodeGroup>
  ```python Python theme={null}
  all_entrances = seam.acs.entrances.list(
    acs_system_id=acs_system.acs_system_id
  )

  # Filter for entrances with the common entrance category types.
  common_entrance_category_types = ["common", "common (PMS)"]

  def filter_entrances_by_profile_type(entrance_list, category_types):
      common_entrances = []
      for entrance in entrance_list:
          if entrance["visionline_metadata"]["door_category"] in category_types:
              common_entrances.append(entrance)
      return common_entrances

  common_entrances = filter_entrances_by_profile_type(
      all_entrances,
      common_entrance_category_types
  )
  ```
</CodeGroup>


# Revoking Mobile Credentials
Source: https://docs.seam.co/device-and-system-integration-guides/assa-abloy-visionline-access-control-system/configuring-visionline-mobile-credentials/revoking-mobile-credentials

Learn how to delete mobile credentials.

To revoke a mobile credential, [delete the credential](/low-level-apis/access-systems/managing-credentials#delete-a-credential). Seam issues a discard command for the Visionline card. If you are deleting a [multi-phone sync credential](/capability-guides/mobile-access/issuing-mobile-credentials-from-an-access-control-system#what-are-multi-phone-sync-credentials), Seam discards all of the credentials that were created underneath it.

**Request:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  await seam.acs.credentials.delete({
    acs_credential_id: '66666666-6666-6666-6666-666666666666',
  })
  ```

  ```bash cURL theme={null}
  curl -X 'POST' \
    'https://connect.getseam.com/acs/credentials/delete' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${API_KEY}" \
    -H 'Content-Type: application/json' \
    -d '{
    "acs_credential_id": "66666666-6666-6666-6666-666666666666"
  }'
  ```

  ```python Python theme={null}
  seam.acs.credentials.delete(
    acs_credential_id="66666666-6666-6666-6666-666666666666"
  )
  ```

  ```ruby Ruby theme={null}
  # Coming soon!
  ```

  ```php PHP theme={null}
  $seam->acs->credentials->delete(
    acs_credential_id: "66666666-6666-6666-6666-666666666666"
  );
  ```

  ```csharp C# theme={null}
  seam.CredentialsAcs.Delete(
    acsCredentialId: "66666666-6666-6666-6666-666666666666"
  );
  ```
</CodeGroup>

**Response:**

<CodeGroup>
  ```json JavaScript theme={null}
  void
  ```

  ```json cURL theme={null}
  {
    "ok": true
  }
  ```

  ```json Python theme={null}
  None
  ```

  ```json Ruby theme={null}
  # Coming soon!
  ```

  ```json PHP theme={null}
  void
  ```

  ```json C# theme={null}
  void
  ```
</CodeGroup>


# Updating Guest Mobile Credentials
Source: https://docs.seam.co/device-and-system-integration-guides/assa-abloy-visionline-access-control-system/configuring-visionline-mobile-credentials/updating-guest-mobile-credentials

Learn how to update guest credentials.

Instead of updating a guest credential, you can issue a new [joiner credential](/device-and-system-integration-guides/assa-abloy-visionline-access-control-system/configuring-visionline-mobile-credentials#issue-subsequent-credentials-for-a-reservation) with the updated parameters. Seam automatically replaces the old credential with the new one.

```python theme={null}
# Creating a new mobile credential automatically revokes
# the previous one.
seam.acs.credentials.create({
    acs_user_id: "xxx",
    credential_manager_acs_system_id="xxx"
    is_multi_phone_sync_credential: True,
    access_method = "mobile_key",
    starts_at: "2023-01-01 10:40:00.000",
    ends_at: "2023-01-04 10:40:00.000",
    visionline_metadata: {
        "cardFormat": "rfid48",
        "label": "%ROOMNUM% - %SITENAME%",
        "joiners": [
            "xxx", "yyy"
        ]
    }
})
```


# Creating Visionline Card-based Credentials
Source: https://docs.seam.co/device-and-system-integration-guides/assa-abloy-visionline-access-control-system/creating-visionline-card-based-credentials

Learn how to create a card-based credential for Visionline.

To create a credential to encode onto a plastic key card for a Visionline ACS:

1. Set up an [ACS user](/low-level-apis/access-systems/user-management).

2. Create a [credential](/low-level-apis/access-systems/managing-credentials#create-a-card-based-credential) with the `access_method` set to `card` and the appropriate [`visionline_metadata`](./mobile-credential-related-properties#acs_credentialvisionline_metadata-properties), such as the card format.

   * To issue the first credential for a reservation—that is, an "override" credential—make sure to set `visionline_metadata.override` to `true`.
   * To issue subsequent credentials for a reservation, set the `visionline_metadata.joiner_acs_credential_ids`.

   For more information about Visionline credential types, see [Credential Types for Visionline](/device-and-system-integration-guides/assa-abloy-visionline-access-control-system/configuring-visionline-mobile-credentials/index#credential-types-for-visionline) and [Guest Mobile Credential Types](/device-and-system-integration-guides/assa-abloy-visionline-access-control-system/configuring-visionline-mobile-credentials/index#guest-mobile-credential-types).

3. Encode the credential onto a plastic card.
   1. Use the `/acs/encoders/list` endpoint to retrieve a list of available encoders. Then, choose the encoder that you want to use to write the credential to the card.\
      See [Retrieve Encoders](/low-level-apis/access-systems/working-with-card-encoders-and-scanners/creating-and-encoding-card-based-credentials#2-retrieve-encoders).
   2. Use the `/acs/encoders/encode_credential` endpoint to encode the credential onto the card, using the encoder that you have chosen.\
      See [Encode the Card](/low-level-apis/access-systems/working-with-card-encoders-and-scanners/creating-and-encoding-card-based-credentials#3-encode-the-card).
   3. Confirm that the card was encoded successfully using polling or a [webhook](/developer-tools/webhooks).\
      See [Confirm Successful Encoding](/low-level-apis/access-systems/working-with-card-encoders-and-scanners/creating-and-encoding-card-based-credentials#4-confirm-successful-encoding). Also, see a list of [common encoding errors](/low-level-apis/access-systems/working-with-card-encoders-and-scanners/creating-and-encoding-card-based-credentials#common-encoding-errors).

The following example shows how to create a card-based override credential for Visionline and encode it onto a plastic card:

**Code:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  // Step 1:
  // Create the new ACS user.
  const acsUser = await seam.acs.users.create({
    acs_system_id: "11111111-1111-1111-1111-111111111111",
    full_name: "Jane Doe",
    email_address: "jane@example.com"
  });

  // Step 2:
  // Create a card-based credential for each entrance for the ACS user.
  const credential = await seam.acs.credentials.create({
    acs_user_id: acsUser.acs_user_id,
    access_method: "card",
    allowed_acs_entrance_ids: [
      // List the IDs of the entrances to which
      // you want to grant access.
      room101.seam_acs_entrance_id
    ],
    starts_at: "2024-12-01T15:00:00.000Z",
    ends_at: "2024-12-04T12:00:00.000Z",
    visionline_metadata: {
      "card_format": "rfid48",
      "override": true
    }
  });

  // Step 3:
  // Encode the credential onto a card.
  // First, get the encoder that you want to use.
  const encoder = (await seam.acs.encoders.list({
    acs_system_ids: ["11111111-1111-1111-1111-111111111111"]
  }))[0];

  # Then, encode the card.
  const encodingActionAttempt = await seam.acs.encoders.encodeCredential({
    acs_credential_id: credential.acs_credential_id,
    acs_encoder_id: encoder.acs_encoder_id
  });

  # To confirm that the encoding succeeded,
  # poll the returned action attempt
  # until its status is success.
  await seam.actionAttempts.get({
    action_attempt_id: encodingActionAttempt.action_attempt_id
  });
  ```

  ```bash cURL theme={null}
  # Step 1:
  # Create the new ACS user.
  acs_user=$(curl -X 'POST' \
    'https://connect.getseam.com/acs/users/create' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d "{
    \"acs_system_id\": \"11111111-1111-1111-1111-111111111111\",
    \"full_name\": \"Jane Doe\",
    \"email_address\": \"jane@example.com\"
  }")

  # Step 2:
  # Create a card-based credential for each entrance for the ACS user.
  # In allowed_entrance_ids, list the IDs of the entrances to
  # which you want to grant access.
  credential=$(curl -X 'POST' \
    'https://connect.getseam.com/acs/credentials/create' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d "{
    \"acs_user_id\": \"$(jq -r '.acs_user.acs_user_id' <<< ${acs_user})\",
    \"access_method\": \"card\",
    \"allowed_acs_entrance_ids\": [
      \"${entrance_id}\"
    ],
    \"starts_at\": \"2024-12-01T15:00:00.000Z\",
    \"ends_at\": \"2024-12-04T12:00:00.000Z\",
    \"visionline_metadata\": {
       \"card_format\": \"rfid48\",
       \"override\": true
    }
  }")

  # Step 3:
  # Encode the credential onto a card.
  # First, get the encoder that you want to use.
  encoder=$(curl -X 'POST' \
    'https://connect.getseam.com/acs/encoders/list' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d "{
    \"acs_system_id\": \"11111111-1111-1111-1111-111111111111\"
  }" | jq -r '.acs_encoders[0]')

  # Then, encode the card.
  encoding_action_attempt=$(curl -X 'POST' \
    'https://connect.getseam.com/acs/encoders/encode_credential' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d "{
    \"acs_credential_id\": \"$(jq -r '.acs_credential.acs_credential_id' <<< ${credential})\",
    \"acs_encoder_id\": \"$(jq -r '.acs_encoder_id' <<< ${encoder})\"
  }")

  # To confirm that the encoding succeeded,
  # poll the returned action attempt
  # until its status is success.
  curl -X 'POST' \
    'https://connect.getseam.com/action_attempts/get' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d "{
    \"action_attempt_id\": \"$(jq -r '.action_attempt.action_attempt_id' <<< ${encoding_action_attempt})\"
  }"
  ```

  ```python Python theme={null}
  # Step 1:
  # Create the new ACS user.
  acs_user = seam.acs.users.create(
    acs_system_id = "11111111-1111-1111-1111-111111111111",
    full_name = "Jane Doe",
    email_address = "jane@example.com"
  )

  # Step 2:
  # Create a card-based credential for each entrance for the ACS user.
  credential = seam.acs.credentials.create(
    acs_user_id = acs_user.acs_user_id,
    access_method = "card",
    # List the IDs of the entrances to which
    # you want to grant access.
    allowed_acs_entrance_ids = [
      room_101.seam_acs_entrance_id
    ],
    starts_at = "2024-12-01T15:00:00.000Z",
    ends_at = "2024-12-04T12:00:00.000Z",
    visionline_metadata = {
      "card_format": "rfid48",
      "override": True
    }
  )

  # Step 3:
  # Encode the credential onto a card.
  # First, get the encoder that you want to use.
  encoder = seam.acs.encoders.list(
    acs_system_ids = ["11111111-1111-1111-1111-111111111111"]
  )[0]

  # Then, encode the card.
  encoding_action_attempt = seam.acs.encoders.encode_credential(
    acs_credential_id = credential.acs_credential_id,
    acs_encoder_id = encoder.acs_encoder_id
  )

  # To confirm that the encoding succeeded,
  # poll the returned action attempt
  # until its status is success.
  seam.action_attempts.get(
    action_attempt_id = encoding_action_attempt.action_attempt_id
  )
  ```

  ```ruby Ruby theme={null}
  # Step 1:
  # Create the new ACS user.
  acs_user = seam.acs.users.create(
    acs_system_id: "11111111-1111-1111-1111-111111111111",
    full_name: "Jane Doe",
    email_address: "jane@example.com"
  )

  # Step 2:
  # Create a card-based credential for each entrance for the ACS user.
  credential = seam.acs.credentials.create(
    acs_user_id: acs_user.acs_user_id,
    access_method: "card",
    # List the IDs of the entrances to which
    # you want to grant access.
    allowed_acs_entrance_ids: [
      room_101.seam_acs_entrance_id
    ],
    starts_at: "2024-12-01T15:00:00.000Z",
    ends_at: "2024-12-04T12:00:00.000Z",
    visionline_metadata: {
      "card_format": "rfid48",
      "override": true
    }
  )

  # Step 3:
  # Encode the credential onto a card.
  # First, get the encoder that you want to use.
  encoder = (seam.acs.encoders.list(
    acs_system_ids: ["11111111-1111-1111-1111-111111111111"]
  ))[0]

  # Then, encode the card.
  encoding_action_attempt = seam.acs.encoders.encode_credential(
    acs_credential_id: credential.acs_credential_id,
    acs_encoder_id: encoder.acs_encoder_id
  )

  # To confirm that the encoding succeeded,
  # poll the returned action attempt
  # until its status is success.
  seam.action_attempts.get(
    action_attempt_id: encoding_action_attempt.action_attempt_id
  )
  ```

  ```php PHP theme={null}
  // Step 1:
  // Create the new ACS user.
  $acs_user = $seam->acs->users->create(
    acs_system_id: "11111111-1111-1111-1111-111111111111",
    full_name: "Jane Doe",
    email_address: "jane@example.com"
  );

  // Step 2:
  // Create a card-based credential for each entrance for the ACS user.
  $credential = $seam->acs->credentials->create(
    acs_user_id: $acs_user->acs_user_id,
    access_method: "card",
    allowed_acs_entrance_ids: [
      // List the IDs of the entrances to which
      // you want to grant access.
      $room_101->seam_acs_entrance_id
    ],
    starts_at: "2024-12-01T15:00:00.000Z",
    ends_at: "2024-12-04T12:00:00.000Z",
    visionline_metadata: array('card_format' => "rfid48", 'is_override_key' => true)
  );

  // Step 3:
  // Encode the credential onto a card.
  // First, get the encoder that you want to use.
  $encoder = $seam->acs->encoders->list(
    acs_system_ids: ["11111111-1111-1111-1111-111111111111"]
  )[0];

  // Then, encode the card.
  $encoding_action_attempt = $seam->acs->encoders->encode_credential(
    acs_credential_id: $credential->acs_credential_id,
    acs_encoder_id: $encoder->acs_encoder_id
  );

  // To confirm that the encoding succeeded,
  // poll the returned action attempt
  // until its status is success.
  $seam->action_attempts->get(
    action_attempt_id: $encoding_action_attempt->action_attempt_id
  );
  ```

  ```csharp C# theme={null}
  // Coming soon!
  ```
</CodeGroup>

**Output:**

<CodeGroup>
  ```json JavaScript theme={null}
  {
    acs_credential_id: '66666666-6666-6666-6666-666666666666',
    acs_user_id: '33333333-3333-3333-3333-333333333333',
    access_method: 'card',
    starts_at: '2024-12-01T15:00:00.000Z',
    ends_at: '2024-12-04T12:00:00.000Z',
    is_issued: false,
    ...
  }

  {
    status: 'success',
    action_attempt_id: '11111111-2222-3333-4444-555555555555",
    action_type: 'ENCODE_CREDENTIAL',
    result: {
      acs_credential_id: "66666666-6666-6666-6666-666666666666',
      card_number: '1234abc',
      is_issued: true,
      issued_at: '2024-12-01T12:00:00.000Z',
      ...
    },
    error: null
  }
  ```

  ```json cURL theme={null}
  {
    "acs_credential":
      {
        "acs_credential_id": "66666666-6666-6666-6666-666666666666",
        "acs_user_id": "33333333-3333-3333-3333-333333333333",
        "access_method": "card",
        "starts_at": "2024-12-01T15:00:00.000Z",
        "ends_at": "2024-12-04T12:00:00.000Z",
        "is_issued": false,
        ...
      },
    "ok":true
  }

  {
    "action_attempt":
      {
        "status": "success",
        "action_attempt_id": "11111111-2222-3333-4444-555555555555",
        "action_type": "ENCODE_CREDENTIAL",
        "result": {
          "acs_credential_id": "66666666-6666-6666-6666-666666666666",
          "card_number": "1234abc",
          "is_issued": true,
          "issued_at": "2024-12-01T12:00:00.000Z",
          ...
        },
        "error": null
      },
    "ok": true
  }
  ```

  ```json Python theme={null}
  AcsCredential(
    acs_credential_id='66666666-6666-6666-6666-666666666666',
    acs_user_id='33333333-3333-3333-3333-333333333333',
    access_method='card',
    starts_at='2024-12-01T15:00:00.000Z',
    ends_at='2024-12-04T12:00:00.000Z',
    is_issued=False,
    ...
  )

  ActionAttempt(
    status='success',
    action_attempt_id='11111111-2222-3333-4444-555555555555',
    action_type='ENCODE_CREDENTIAL',
    result={
      acs_credential_id='66666666-6666-6666-6666-666666666666',
      card_number='1234abc',
      is_issued=True,
      issued_at='2024-12-01T12:00:00.000Z',
      ...
    },
    error=null
  )
  ```

  ```json Ruby theme={null}
  <Seam::Resources::AcsCredential:0x00410
    acs_credential_id="66666666-6666-6666-6666-666666666666"
    acs_user_id="33333333-3333-3333-3333-333333333333"
    access_method="card"
    starts_at="2024-12-01T15:00:00.000Z"
    ends_at="2024-12-04T12:00:00.000Z"
    is_issued=false
    ...
  >

  <Seam::Resources::ActionAttempt:0x00410
    status="success"
    action_attempt_id="11111111-2222-3333-4444-555555555555"
    action_type="ENCODE_CREDENTIAL"
    result={
      acs_credential_id="66666666-6666-6666-6666-666666666666"
      card_number="1234abc"
      is_issued=true,
      issued_at="2024-12-01T12:00:00.000Z"
      ...
    }
    error=nil
  >
  ```

  ```json PHP theme={null}
  {
    "acs_credential_id": "66666666-6666-6666-6666-666666666666",
    "acs_user_id": "33333333-3333-3333-3333-333333333333",
    "access_method": "card",
    "starts_at": "2024-12-01T15:00:00.000Z",
    "ends_at": "2024-12-04T12:00:00.000Z",
    "is_issued": false,
    ...
  }

  {
    "status": "success",
    "action_attempt_id": "11111111-2222-3333-4444-555555555555",
    "action_type": "ENCODE_CREDENTIAL",
    "result": {
      "acs_credential_id": "66666666-6666-6666-6666-666666666666",
      "card_number": "1234abc",
      "is_issued": true,
      "issued_at": "2024-12-01T12:00:00.000Z",
      ...
    },
    "error": null
  }
  ```

  ```json C# theme={null}
  // Coming soon!
  ```
</CodeGroup>

***

## Next Steps

You can use an encoder to scan a plastic key card to read its encoded parameters. The scan result includes the card's properties, such as its card number, serial number, and other useful details. For more information, see [Scanning Encoded Cards](/low-level-apis/access-systems/working-with-card-encoders-and-scanners/scanning-encoded-cards).


# ASSA ABLOY Visionline Access Control System
Source: https://docs.seam.co/device-and-system-integration-guides/assa-abloy-visionline-access-control-system/index

Guide for using the ASSA ABLOY Visionline Access Control System with Seam

<img alt="Visionline logo" />

## Overview

Seam integrates seamlessly with the ASSA ABLOY Visionline Access Control System (ACS), a widely-used on-premises access control platform for hotels. This system supports doors, elevators, turnstiles, and gates, enabling you to secure either a single building or multiple buildings using the same setup. Visionline uses a data-on-card platform, significantly reducing installation costs because the locks can function offline. Additionally, the capability of the system to operate independently of network connectivity enhances the reliability and flexibility.

***

## Supported Devices

<DeviceList />

This integration supports all readers and wireless locks connected to the Visionline ACS.

For detailed information about the ASSA ABLOY Visionline devices that Seam supports, see our [ASSA ABLOY Supported Devices page](https://www.seam.co/manufacturers/assa-abloy).

***

## Supported Features

We support the following features:

* [Managing access systems](/low-level-apis/access-systems)
* [Issuing plastic card credentials](/low-level-apis/access-systems/managing-credentials)
* [Issuing mobile access credentials](/capability-guides/mobile-access)

***

### Device Provider Key

Seam identifies these devices with the `visionline` device provider key. By default, a [Connect Webview](/core-concepts/connect-webviews) displays all of the stable providers that Seam supports, so your users can connect their Visionline ACS without you specifying a provider list. To narrow what a Connect Webview displays, see [Customize the Brands to Display in Your Connect Webviews](/core-concepts/connect-webviews/customizing-connect-webviews#customize-the-brands-to-display-in-your-connect-webviews).

***

## Troubleshooting

For information about Visionline ACS-related errors, including issues related to the connection between your ACS and Seam, see [Troubleshooting Your ACS](/low-level-apis/access-systems/troubleshooting-your-access-control-system).

***

## Where to Order

To purchase the ASS ABLOY Visionline ACS and devices, request a quote from ASSA ABLOY.

<table>
  <thead>
    <tr>
      <th />

      <th />

      <th />

      <th />

      <th />
    </tr>
  </thead>

  <tbody>
    <tr>
      <td />

      <td>
        <strong>ASSA ABLOY Contact Page</strong>
      </td>

      <td />

      <td />

      <td>
        <a href="/images/assa-abloy-logo.png">assa-abloy-logo.png</a>
      </td>
    </tr>
  </tbody>
</table>


# Mobile Credential-Related Properties
Source: https://docs.seam.co/device-and-system-integration-guides/assa-abloy-visionline-access-control-system/mobile-credential-related-properties

Learn about credential properties that you should use when creating mobile credentials.

When issuing a guest mobile credential, you can use the following relevant properties:

## `acs_credential` Properties

These properties are applicable to [guest](/device-and-system-integration-guides/assa-abloy-visionline-access-control-system/configuring-visionline-mobile-credentials/index#issuing-guest-mobile-credentials) credentials for the Visionline ACS.

<table>
  <thead>
    <tr>
      <th>Property</th>
      <th>Type</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        <code>is\_multi\_phone\_sync\_credential</code>
      </td>

      <td>
        Boolean

        <br />

        <em>Optional</em>
      </td>

      <td>
        Indicates whether the credential is a

        <a href="/capability-guides/mobile-access/issuing-mobile-credentials-from-an-access-control-system#what-are-multi-phone-sync-credentials">
          multi-phone sync credential
        </a>

        .<br />
        When creating a Seam mobile key for a Visionline ACS, you must set this
        property to <code>true</code>.
      </td>
    </tr>

    <tr>
      <td>
        <code>allowed\_acs\_entrance\_ids</code>
      </td>

      <td>
        Array of strings <em>Optional</em>
      </td>

      <td>
        List of ACS entrance IDs to which you want to grant the specified ACS
        user access.
      </td>
    </tr>

    <tr>
      <td>
        <code>starts\_at</code>
      </td>

      <td>
        <a href="https://www.iso.org/iso-8601-date-and-time-format.html">
          ISO 8601
        </a>

        format

        <br />

        <em>Optional</em>
      </td>

      <td>Starting timestamp for credential activation.</td>
    </tr>

    <tr>
      <td>
        <code>ends\_at</code>
      </td>

      <td>
        <a href="https://www.iso.org/iso-8601-date-and-time-format.html">
          ISO 8601
        </a>

        format

        <br />

        <em>Optional</em>
      </td>

      <td>Ending timestamp for credential expiration.</td>
    </tr>
  </tbody>
</table>

***

<h2>
  `acs_credential.visionline_metadata` Properties
</h2>

Use the `credential.visionline_metadata` object to include brand-specific data for your Visionline credentials.

<table>
  <thead>
    <tr>
      <th>Property</th>
      <th>Type</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        <code>card\_function\_type</code>
      </td>

      <td>
        Enum

        <br />

        <em>Optional</em>
      </td>

      <td>
        <code>guest</code>
      </td>
    </tr>

    <tr>
      <td>
        <code>cardFormat</code>
      </td>

      <td>
        Enum

        <br />

        <em>Required</em>
      </td>

      <td>
        <p>
          <code>rfid48</code> | <code>TLCode</code>
        </p>

        <ul>
          <li>
            <code>rfid48</code>: A low-capacity card. It can store up to 33
            consecutive guest rooms, 28 common rooms, and 7 additional rooms.
          </li>

          <li>
            <code>TLCode</code>: A high capacity RFID card (for card types
            needing more than 48 bytes).
          </li>
        </ul>

        <p>
          For guest cards, generally use <code>rfid48</code>.
        </p>

        <p>
          For guest advanced cards, which need a higher capacity format, use
          <code>TLCode</code>.
        </p>
      </td>
    </tr>

    <tr>
      <td>
        <code>label</code>
      </td>

      <td>
        String

        <br />

        <em>Optional</em>
      </td>

      <td>
        "Label" field data for mobile credentials. This field may contain plain
        text, as well as predefined placeholders. The placeholders are
        surrounded by percent signs (<code>%</code>).

        <br />

        See

        <a href="#label-placeholders">
          Label Placeholders
        </a>

        .
      </td>
    </tr>

    <tr>
      <td>
        <code>override</code>
      </td>

      <td>
        Boolean

        <br />

        <em>Optional</em>
      </td>

      <td>
        Indicates whether this guest credential invalidates any
        previously-issued credentials for overlapping entrances.

        <br />

        Applicable only to guest credentials.
      </td>
    </tr>

    <tr>
      <td>
        <code>joiner\_acs\_credential\_ids</code>
      </td>

      <td>
        Array of strings <em>Optional</em>
      </td>

      <td>
        List of credential IDs with which the current guest credential shares
        entrance access. When <code>override\_previous\_credentials</code> is
        <code>false</code>, <code>joiner\_acs\_credential\_ids</code> becomes a
        mandatory field.

        <br />

        Applicable only to guest credentials.
      </td>
    </tr>

    <tr>
      <td>
        <code>assa\_abloy\_credential\_service\_mobile\_endpoint\_id</code>
      </td>

      <td>
        String

        <br />

        <em>Optional</em>
      </td>

      <td>
        ID of the ASSA ABLOY Credential Service mobile endpoint associated with
        the credential.
      </td>
    </tr>

    <tr>
      <td>
        <code>is\_valid</code>
      </td>

      <td>
        Boolean

        <br />

        <em>Optional</em>
      </td>

      <td>Indicates whether the credential is currently valid.</td>
    </tr>
  </tbody>
</table>

***

## Label Placeholders

The `label` field provides "label" field data for mobile credentials. This field may contain plain text, as well as predefined placeholders. The placeholders are surrounded by percent signs (`%`). Visionline replaces these placeholders with the actual values before issuing mobile keys. The final text is truncated to 32 characters. The valid placeholders are as follows:

* `%ROOMNUM%`: Replaced with main guest room number or name.
* `%ROOMLIST%`: Replaced with comma-separated list of guest rooms.
* `%ROOMRANGE%`: Replaced with hyphen-separated room range. Alternately, if some rooms do not fit into any range, then they are added as a comma-separated list.
* `%SITENAME%`: Name of the property.
* `%CARDNUM%`: Credential ID.
* `%UUID%`: BLE UUID.
* `%USERID%`: Value passed in the UI field.


# Special Requirements for Android Mobile Access SDK Development
Source: https://docs.seam.co/device-and-system-integration-guides/assa-abloy-visionline-access-control-system/special-requirements-for-android-mobile-access-sdk-development

Learn the requirements and restrictions for developing Android apps that integrate with the Visionline ACS.

## Add XML File with ASSA ABLOY AID

To develop an Android mobile app that integrates with the ASSA ABLOY Visionline ACS, you must register for the ASSA ABLOY partnership program. Note that if you plan to integrate with the [ASSA ABLOY Visionline credential manager](../assa-abloy-vingcard-credential-services/index), you must also register for this program. For details, see [https://www.abloy.com/global/en/partnership-and-integrations](https://www.abloy.com/global/en/partnership-and-integrations).

After you register for the ASSA ABLOY partnership program, ASSA ABLOY provides a Host-based Card Emulation application ID (HCE AID).

When developing your Android app, you must include the following `res/xml/seos_hce_service.xml` resource file that contains your HCE Application ID:

```xml theme={null}
<?xml version="1.0" encoding="utf-8"?>
<host-apdu-service xmlns:android="http://schemas.android.com/apk/res/android"
      android:description="@string/seos_hce_description"
      android:requireDeviceUnlock="false"
      android:requireDeviceScreenOn="true">
    <aid-group android:description="@string/seos_hce_aid_description" android:category="other">
        {/* Specify your AID from ASSA ABLOY here. */}
        <aid-filter android:name="..."/>
    </aid-group>
</host-apdu-service>
```

For additional information about this resource file, contact [ASSA ABLOY](https://www.abloy.com/global/en/partnership-and-integrations#gw-group-text-and-media-eabfaa4827).

***

## BLE Scanning Restriction

When developing a mobile app for Android 7, you cannot start and stop Bluetooth low energy (BLE) scanning within a timeframe of approximately 30 seconds. This Android restriction is intended to optimize mobile device battery life. Instead, use a continuous BLE scan.

For more information, see the [ASSA ABLOY knowledge base](https://my.assaabloyglobalsolutions.com/tpp?id=kb_article_view\&sys_kb_id=a42f98e8db340450812df3b31d9619b1) (ASSA ABLOY login required).

***

## Unlock Success Event Limitation

The `SUCCESS` event indicates that the phone has communicated successfully with the door reader. That is, the Seam mobile SDK cannot determine whether the door reader granted access. It can only determine whether the communication with the reader succeeded. This limitation is the result of the underlying ASSA ABLOY SEOS SDK.


# Special Requirements for iOS Mobile Access SDK Development
Source: https://docs.seam.co/device-and-system-integration-guides/assa-abloy-visionline-access-control-system/special-requirements-for-ios-mobile-access-sdk-development

Learn the requirements for developing iOS apps that integrate with the Visionline ACS.

## Register for ASSA ABLOY Partnership Program

To develop an iOS mobile app that integrates with the ASSA ABLOY Visionline ACS, you must register for the ASSA ABLOY partnership program. Note that if you plan to integrate with the [ASSA ABLOY Visionline credential manager](../assa-abloy-vingcard-credential-services/index), you must also register for this program. For details, see [https://www.abloy.com/global/en/partnership-and-integrations](https://www.abloy.com/global/en/partnership-and-integrations).

***

## Unlock Success Event Limitation

The `SUCCESS` event indicates that the phone has communicated successfully with the door reader. That is, the Seam mobile SDK cannot determine whether the door reader granted access. It can only determine whether the communication with the reader succeeded. This limitation is the result of the underlying ASSA ABLOY SEOS SDK.


# Developing Your Visionline Mobile Key App
Source: https://docs.seam.co/device-and-system-integration-guides/assa-abloy-visionline-access-control-system/visionline-acs-setup-instructions/developing-and-launching-your-visionline-mobile-key-app/developing-your-visionline-mobile-key-app/index

Learn how to develop your Visionline mobile key integration.

You can use Visionline with your development account to develop and test your Visionline mobile key app.

For detailed instructions, see the following topics:

[Step 1: Complete the ASSA ABLOY Mobile Development Course](./step-1-complete-the-assa-abloy-mobile-development-course)

[Step 2: Install Your Visionline Application](./step-2-install-your-visionline-application)

[Step 3: Unblock Required Ports](./step-3-unblock-required-ports)

[Step 4: Configure a Visionline User Account](./step-4-configure-a-visionline-user-account)

[Step 5: Set up Your Credential Services Account in Visionline](./step-5-set-up-your-credential-services-account-in-visionline)

[Step 6: Configure the Mobile Access UUID in Visionline](./step-6-configure-the-mobile-access-uuid-in-visionline)

[Step 7: Set up Door Locks with BLE Profiles](./step-7-set-up-door-locks-with-ble-profiles)

[Step 8: Program Door Locks](./step-8-program-door-locks)

[Step 9: Create a Production Workspace](./step-9-create-a-production-workspace)

[Step 10: Connect Your Visionline Development Account to Seam](../../../../assa-abloy-visionline-access-control-system/visionline-acs-setup-instructions/developing-and-launching-your-visionline-mobile-key-app/developing-your-visionline-mobile-key-app/step-10-connect-your-visionline-development-account-to-seam)

[Next Steps](./next-steps)


# Next Steps
Source: https://docs.seam.co/device-and-system-integration-guides/assa-abloy-visionline-access-control-system/visionline-acs-setup-instructions/developing-and-launching-your-visionline-mobile-key-app/developing-your-visionline-mobile-key-app/next-steps

After you set up your Visionline ACS to develop your mobile key app, learn what's next.

Once you've set up your Visionline ACS using your Visionline development account, proceed to the following steps:

1. Develop your Visionline mobile key app.
2. Test your app.
3. Obtain ASSA ABLOY certification for your Visionline mobile key app
4. Launch your app into production.

For details about obtaining certification and launching your app, see [Launching Your Visionline Mobile Key App](/device-and-system-integration-guides/assa-abloy-visionline-access-control-system/visionline-acs-setup-instructions/developing-and-launching-your-visionline-mobile-key-app/launching-your-visionline-mobile-key-app/index).


# Step 1: Complete the ASSA ABLOY Mobile Development Course
Source: https://docs.seam.co/device-and-system-integration-guides/assa-abloy-visionline-access-control-system/visionline-acs-setup-instructions/developing-and-launching-your-visionline-mobile-key-app/developing-your-visionline-mobile-key-app/step-1-complete-the-assa-abloy-mobile-development-course

Learn how to sign up for the mandatory ASSA ABLOY mobile development course.

Sign up for and complete the mandatory ASSA ABLOY mobile development course. For details, send an email to either of the following addresses:

* [mobile.access.globalsolutions@assaabloy.com](mailto:mobile.access.globalsolutions@assaabloy.com)
* [onboardingprogram@assaabloy.com](mailto:onboardingprogram@assaabloy.com)

As part of this course, ASSA ABLOY provides you with the following items:

* Demo lock that includes the required BLE module
* Development Visionline account
* Development ASSA ABLOY Credential Services account

Note that the course shows you how to install and set up Visionline using your development account. You must use this development account to develop your app.


# Step 10: Connect Your Visionline Development Account to Seam
Source: https://docs.seam.co/device-and-system-integration-guides/assa-abloy-visionline-access-control-system/visionline-acs-setup-instructions/developing-and-launching-your-visionline-mobile-key-app/developing-your-visionline-mobile-key-app/step-10-connect-your-visionline-development-account-to-seam

Learn how to connect your Visionline and Credentials Services development accounts to Seam.

To develop your mobile key app, perform the following procedures to connect your Visionline development account to Seam:

1. [Connect your ASSA ABLOY Credential Services development account to Seam.](#connect-credential-services-to-seam)
2. [Connect your Visionline development account to Seam.](#connect-visionline-to-seam)

   This process includes installing and running Seam Bridge to connect your on-premises Visionline application to Seam. For more information, see [Seam Bridge](/capability-guides/seam-bridge).

***

## Connect Credential Services to Seam

ASSA ABLOY Credential Services stores all the mobile credentials that your application issues. For more information about ASSA ABLOY Credential Services, see the [ASSA ABLOY Credential Services integration guide](/device-and-system-integration-guides/assa-abloy-vingcard-credential-services/index).

You received a Credential Services development "tenant" account during the [mandatory ASSA ABLOY mobile development course](./step-1-complete-the-assa-abloy-mobile-development-course). To find out the credentials and details for this account, see [Retrieve Your ASSA ABLOY Credential Services Development Account Details](#retrieve-your-assa-abloy-credential-services-development-account-details). Then, [connect your development Credential Services account to Seam](#connect-credential-services).

***

### Retrieve Your ASSA ABLOY Credential Services Development Account Details

Locate your ASSA ABLOY Credential Services development tenant account details in the ASSA ABLOY Global Solutions Technology Partner Portal.

1. In a web browser, go to the [ASSA ABLOY Global Solutions Technology Partner Portal](https://my.assaabloyglobalsolutions.com/tpp).
2. Log in to the ASSA ABLOY Global Solutions Technology Partner Portal.
3. Click **Accounts > Account List**.
4. In the **Agreements** area, locate and open the text (`.txt`) file.\
   This text file contains the following information:
   * ASSA ABLOY development tenant account username
   * ASSA ABLOY development tenant account password
   * System ID for the development phase
   * Application ID for the development phase
   * ASSA ABLOY credential services URL for the development phase

***

### Connect Credential Services

1. In the top navigation pane of [Seam Console](https://console.seam.co/), click **ACS Systems**. Then, in the upper-right corner of the **Access Systems** page, click **New Access System**.
2. In the Connect Webview, perform the following steps:
   1. Click **Continue**.
   2. If the Connect Webview displays multiple brand options, select **Assa Abloy Credential Service**.
   3. In the **Username** field, type your development tenant account username.
   4. In the **Password** field, type your development tenant account password.
   5. In the **Credential Services URL** field, type the development Credential Services URL.
   6. Click **Submit**.
3. Configure your ASSA ABLOY settings in Seam Console, as follows:
   1. In the top navigation pane of [Seam Console](https://console.seam.co/), click **Settings**.
   2. On the **Workspace Settings** page, next to **Assa Abloy Settings**, click **Edit**.
   3. In the **Assa Abloy Settings** dialog, type your development application ID.
   4. Click **Save**.

<Info>
  ASSA ABLOY assigns you a preliminary application ID during the development phase. You cannot use this preliminary application ID to connect to live sites. After you receive certification, ASSA ABLOY provides a production application ID that you can use to connect to real sites. This production application ID uniquely identifies your application within both the iOS and Android app stores.

  When you obtain certification, you must edit your Seam workspace settings to update this application ID.
</Info>

***

## Connect Visionline to Seam

Perform this process for each Visionline site that you want to connect to Seam.

1. In the top navigation pane of [Seam Console](https://console.seam.co/), click **ACS Systems**.

2. On the **Access Systems** page, click **New Access System**.

   Seam Console displays a Connect Webview that enables you to connect your ACS to Seam.

3. In the Connect Webview, click **Continue**.

4. If the Connect Webview displays multiple brand options, click **Visionline**.

5. On the **Set up your Seam Bridge** page, click [**latest Seam Bridge client**](https://www.seam.co/seam-bridge/releases/latest).

   [Seam Bridge](/capability-guides/seam-bridge) is a software-only component that enables you to connect on-premises software systems to the Seam platform. Because Visionline is an on-premises ACS, Seam Bridge is required for Visionline systems.

6. Download the Seam Bridge executable onto the on-premises computer that is running Visionline or onto a computer on the same network.

   For systems requirements, see [Seam Bridge](/capability-guides/seam-bridge).

7. Run the downloaded Seam Bridge app.

8. In the **Welcome to Seam Bridge** window, type a name for the site that you are connecting using Seam Bridge and then click **Start pairing**.

9. Copy the pairing code.

10. In the Connect Webview, click **Continue**.

11. On the **Set up your Seam Bridge** page:
    1. In the **Enter your pairing token** field, paste the pairing code that you copied.
    2. Click **Submit**.

12. On the **Enter your credentials** page:
    1. In the **Visionline Site Name** field, type a name to identify the Visionline site within your Seam workspace.

    2. In the **Username** field, type the username for your Visionline development account.

       This account is the one that you [created or identified in Visionline for the connection with Seam](./step-4-configure-a-visionline-user-account).

    3. In the **Password** field, type the password for your Visionline development account.

    4. Select the **Mobile Keys will be issued in this system** checkbox.

    5. In the **Mobile Access UUID** field, type `1`.

    6. In the **System ID** field, type your system ID for the development phase.

    7. If Seam Bridge is not installed on the same computer as Visionline, select **Seam Bridge and Visionline server are installed on different computers** and then type the local IP address of the on-premises computer running Seam Bridge.

    8. Click **Submit**.

13. Click **Close**.


# Step 2: Install Your Visionline Application
Source: https://docs.seam.co/device-and-system-integration-guides/assa-abloy-visionline-access-control-system/visionline-acs-setup-instructions/developing-and-launching-your-visionline-mobile-key-app/developing-your-visionline-mobile-key-app/step-2-install-your-visionline-application

Learn how to install the Visionline application and use your Visionline development account.

You can install the Visionline application and use a development—pre-certification—Visionline account to develop and test your mobile key app.

<Info>
  The [mandatory ASSA ABLOY mobile development
  course](./step-1-complete-the-assa-abloy-mobile-development-course) shows you
  how to install and set up Visionline using your development account. If you
  have already installed Visionline as part of the ASSA ABLOY mobile development
  course, skip this step.
</Info>

***

## System Requirements

Make sure that your computer meets the following requirements:

* Key server:
  * Visionline V1.27
  * Windows 10 1901 (or newer)
  * Hosted in a location where internet traffic is allowed
* ASSA ABLOY online locks:
  * Bluetooth modules and licenses installed

For more details, see the following ASSA ABLOY Visionline document:

***

## Install Visionline

Install the Visionline application on a Windows computer.

<Info>
  When prompted for an account username and password, you must specify the
  username and password of the Windows account that has administrative rights to
  the computer on which you are installing Visionline.
</Info>

For detailed instructions, see the following ASSA ABLOY Visionline document:

***

## Start Visionline

When you open the Visionline application, choose unlicensed mode.


# Step 3: Unblock Required Ports
Source: https://docs.seam.co/device-and-system-integration-guides/assa-abloy-visionline-access-control-system/visionline-acs-setup-instructions/developing-and-launching-your-visionline-mobile-key-app/developing-your-visionline-mobile-key-app/step-3-unblock-required-ports

Learn which ports are required for using Visionline.

Unblock the required ports on the Visionline server and client.

1. Unblock the following ports on the server:
   * All files in the Visionline `Program Files` and `ProgramData` folders\
     The default locations are `C:\Program Files\ASSA ABLOY\Visionline` and `C:\ProgramData\ASSA ABLOY\Visionline`.
   * Firewall ports:
     * Port 135 (TCP)
     * 3001 (TCP)
     * 7799, 7788 (TCP/UDP)
     * Lock Service Port (27015 default) (TCP)
     * PMS port (4000 default) (TCP)
2. Unblock the following ports on the client:
   * All files in the Visionline `Program Files` and `ProgramData` folders\
     The default locations are `C:\Program Files\ASSA ABLOY\Visionline` and `C:\ProgramData\ASSA ABLOY\Visionline`.
   * Firewall ports
     * Port 135 (TCP)
     * 3001 (TCP)
     * DCOM ports

For more details, see the following ASSA ABLOY Visionline document:


# Step 4: Configure a Visionline User Account
Source: https://docs.seam.co/device-and-system-integration-guides/assa-abloy-visionline-access-control-system/visionline-acs-setup-instructions/developing-and-launching-your-visionline-mobile-key-app/developing-your-visionline-mobile-key-app/step-4-configure-a-visionline-user-account

Learn how to set up a Visionline user account to integrate with Seam.

Make sure that your Visionline application is configured with an appropriate user account. You use this account to connect the Visionline instance with Seam. You can use the default `sym` username and password.

Alternately, the Visionline ACS administrator can create a Visionline user specifically for the connection with Seam. This user must be configured as an operator that uses the System Manager operator template. This user must also have a password.

To create a new Visionline user for the Seam connection, first create a new user. Then, configure the user as an operator that uses the System Manager operator template.

<Info>
  These instructions use Visionline 1.27. If you are using Visionline 1.28, you
  may notice differences in a few field names.
</Info>

1. Log in to the Visionline application as a user with System Manager access.

   When opening Visionline during the development phase, use unlicensed mode.

2. Create a new Visionline user.
   1. At the bottom of the left navigation pane, click **Lists**.
   2. In the **System administration** section of the left navigation pane, double-click **Users**.
   3. In the **Users** window, click **Add**.
   4. In the **User details** window, type a **User ID** for the new user, for example, `Seam Integration`.
   5. Type the **Last name** of the user, for example, `Integration`.
   6. Type the **First name** of the user, for example, `Seam`.
   7. Select the **User group** to which to assign the user.
   8. Optionally, in the **PIN** field, type a PIN for the user.
   9. If you've added a PIN, in the **Confirm PIN** field, type the same PIN for the user.
   10. Click **Save**.
   11. In the **User details** dialog, click **Close**.
   12. In the **Users** window, click **Close**.

3. Configure the new user as an operator that uses the System Manager operator template.
   1. At the bottom of the left navigation pane, click **Lists**.
   2. In the **System access** section of the left navigation pane, double-click **Operators**.
   3. In the **Operators** window, click **Add**.
   4. In the **Operator details** dialog, click **...** next to the **User name** field.
   5. In the **Users \<Operator details>** window, select the user that you created and then click **Select**.
   6. In the **Operator details** dialog, select **System Manager** as the **Operator template**.\
      Alternately, you can create a new operator template for the new user, but you must make sure that this operator template has access to all permissions.
   7. In the **Password** and **Confirm Password** fields, type a password for the user.
   8. Click **Save**.
   9. In the **Operator details** dialog, click **Close**.
   10. In the **Operators** window, click **Close**.

4. Note the username and password for this Visionline user. You must use these credentials when you [connect your Visionline account to Seam](./step-10-connect-your-visionline-development-account-to-seam).


# Step 5: Set up Your Credential Services Account in Visionline
Source: https://docs.seam.co/device-and-system-integration-guides/assa-abloy-visionline-access-control-system/visionline-acs-setup-instructions/developing-and-launching-your-visionline-mobile-key-app/developing-your-visionline-mobile-key-app/step-5-set-up-your-credential-services-account-in-visionline

Learn how to set up your development Credential Services account in Visionline.

Set up your development Credential Services account in the Visionline application.

1. At the bottom of the left navigation pane in the Visionline application, click **Lists**.
2. In the **System setup** section of the left navigation pane, double-click **Mobile Access Accounts**.
3. Click **Add**.
4. In the **Mobile Access account details** window, enter your development Credential Services account details.

   Note that you received these credentials and details during the [mandatory ASSA ABLOY mobile development course](./step-1-complete-the-assa-abloy-mobile-development-course). Alternately, see [Retrieve Your ASSA ABLOY Credential Services Development Account Details](#retrieve-your-assa-abloy-credential-services-development-account-details).

   1. Type a **Name** for the mobile access account.
   2. Select the **Set As Default Account** checkbox.
   3. Type the **URL** of the credential server.
   4. Type **User name** and **Password** for your development Credential Services account.
   5. Type the Credential Services **System ID**.
   6. Click **Test** to verify these credentials.
   7. Click **Save**.

***

## Retrieve Your ASSA ABLOY Credential Services Development Account Details

Locate your ASSA ABLOY Credential Services development tenant account details in the ASSA ABLOY Global Solutions Technology Partner Portal.

1. In a web browser, go to the [ASSA ABLOY Global Solutions Technology Partner Portal](https://my.assaabloyglobalsolutions.com/tpp).
2. Log in to the ASSA ABLOY Global Solutions Technology Partner Portal.
3. Click **Accounts > Account List**.
4. In the **Agreements** area, locate and open the text (`.txt`) file.\
   This text file contains your ASSA ABLOY tenant account username and password, as well as your system ID, application ID, and credential services URL.


# Step 6: Configure the Mobile Access UUID in Visionline
Source: https://docs.seam.co/device-and-system-integration-guides/assa-abloy-visionline-access-control-system/visionline-acs-setup-instructions/developing-and-launching-your-visionline-mobile-key-app/developing-your-visionline-mobile-key-app/step-6-configure-the-mobile-access-uuid-in-visionline

Learn how to configure the mobile access UUID in Visionline for the development phase.

Configure the mobile access UUID in the Visionline application.

Set this property to `1` for the development phase, that is, for anytime that you're using your development Visionline account to integrate with Seam.

1. In the top menu, click **Tools > Options**.
2. In the left navigation pane of the **Options** window, click **Mobile Access**.
3. Make sure that the **UUID** field is set to `1`.
4. If needed, click **Apply**.


# Step 7: Set up Door Locks with BLE Profiles
Source: https://docs.seam.co/device-and-system-integration-guides/assa-abloy-visionline-access-control-system/visionline-acs-setup-instructions/developing-and-launching-your-visionline-mobile-key-app/developing-your-visionline-mobile-key-app/step-7-set-up-door-locks-with-ble-profiles

Learn how to set up door locks with BLE profiles when developing your Visionline mobile key integration.

In the Visionline application, set up all door locks for your Visionline mobile key integration.

Use the Visionline application to define guest room and common door locks. First, set up the desired door areas, such as `Guest Doors` and `Common Doors`. Then, define each door and assign it to the appropriate door area. When you define a door or set of doors, you also choose a door type, to determine the access behavior of the door. Visionline door types include guest, guest entrance, guest common, elevator reader, elevator reader relay, and so on.

Note that for common doors, guest entrance doors and elevator reader relays automatically give access to guests within a specific guest door range, such as common entrances. Then, you assign elevator reader relays to the corresponding elevator reader.

For guest common doors, you must grant guest access manually, such as for a gym door or parking entrance.

<Info>
  These instructions use Visionline 1.27. If you are using Visionline 1.28, you
  may notice differences in a few field names.
</Info>

***

## Set up Guest Room Locks

When defining guest room doors, first create a door area and then create a door of the **Guest** door type.

1. Log in to the Visionline application.
2. Set up a door area for guest rooms.
   1. At the bottom of the left navigation pane, click **Lists**.
   2. In the **System setup** section of the left navigation pane, double-click **Door areas**.
   3. In the **Door areas** window, click **Add**.
   4. In the **Door area details** dialog, type a name and, optionally, a description for the new door area.\
      For example, you could create a door area named `Guest Doors`.
   5. Click **Save**.
   6. To add more door areas, click **New** and then repeat this process in the **Door area details** dialog.
   7. When you are done adding door areas, in the **Door area details** dialog, click **Close**.
   8. In the **Door areas** window, click **Close**.
3. Define each set of guest room doors.
   1. At the bottom of the left navigation pane, click **Lists**.
   2. In the **System setup** section of the left navigation pane, double-click **Doors**.
   3. In the **Doors** window, click **Add**.
   4. In the **Door details** window, select **Guest** as the door **Type**.
   5. In the **Number** field, type the door range.\
      For example: `101-109`
   6. In the **Area** field, select the guest door area that you created.\
      For example: **Guest Doors**
   7. In the left navigation pane of the **Door details** window, click **Profiles**.
   8. In the **Profiles** pane, select the desired BLE profile.
   9. Click **Save**.
   10. To add more door sets, click **New** and then repeat this process in the **Door details** window.
   11. When you are done adding door sets, in the **Door details** window, click **Close**.
   12. In the **Doors** window, click **Close**.

***

## Set up Common Door Locks

When defining common doors, make sure to choose the appropriate door type. Visionline door types include the following, among others:

<table>
  <thead>
    <tr>
      <th>Door Type</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Guest entrance</td>

      <td>
        Specify a set of guest doors to give automatic access to guests within
        this range. You can use this door type for common entrances.
      </td>
    </tr>

    <tr>
      <td>Guest common</td>

      <td>
        You must grant access to doors of this type explicitly to specific guest
        credentials. You can use this door type for gym doors, parking
        entrances, and so on.
      </td>
    </tr>

    <tr>
      <td>Elevator reader relay</td>

      <td>
        This door type represents a floor button or relay within an elevator.
        Specify a set of guest doors to give automatic access to guests within
        this range. Assign each elevator reader relay to the corresponding
        "slot" in an elevator reader definition.
      </td>
    </tr>

    <tr>
      <td>Elevator reader</td>

      <td>
        The door type serves as an organization mechanism for sets of elevator
        reader relays.
      </td>
    </tr>
  </tbody>
</table>

<Info>For more information about door types, see the Visionline Help.</Info>

To define a common door, first create a door area and then create a door of the appropriate type.

1. Log in to the Visionline application if you are not already logged in.
2. Set up a door area for the group of common doors.
   1. At the bottom of the left navigation pane, click **Lists**.
   2. In the **System setup** section of the left navigation pane, double-click **Door areas**.
   3. In the **Door areas** window, click **Add**.
   4. In the **Door area details** dialog, type a name and, optionally, a description for the new door area.\
      For example, you could create a door area named `Common Doors`.
   5. Click **Save**.
   6. To add more door areas, click **New** and then repeat this process in the **Door area details** dialog.
   7. When you are done adding door areas, in the **Door area details** dialog, click **Close**.
   8. In the **Door areas** window, click **Close**.
3. Define each common door.
   1. At the bottom of the left navigation pane, click **Lists**.
   2. In the **System setup** section of the left navigation pane, double-click **Doors**.
   3. In the **Doors** window, click **Add**.
   4. In the **Door details** window, select the appropriate door **Type**.\
      See the table at the beginning of this section for descriptions of some common door types.
   5. Type a **Name** for the door, reader, relay, or other entrance.
   6. For a guest entrance door or elevator reader relay, type the beginning and ending room numbers to define the associated **Room interval**.\
      Note that for guest common entrances, you set up access permissions explicitly when creating guest or other credentials.
   7. In the **Area** field, select the common door area that you created.\
      For example: **Common Doors**
   8. For an elevator reader, set the relay outputs to define the access permissions by floor or other output:
      1. In the **Relay outputs** table, select an output.
      2. Click **Select**.
      3. In the **Select elevator reader relay** dialog, select the corresponding elevator reader relay and then click **OK**.
      4. Repeat this process for any additional relay outputs.
   9. In the left navigation pane of the **Door details** window, click **Profiles**.
   10. In the **Profiles** pane, select the desired BLE profile.
   11. Click **Save**.
   12. To add more common doors, click **New** and then repeat this process in the **Door details** window.
   13. When you are done adding common doors, in the **Door details** window, click **Close**.
   14. In the **Doors** window, click **Close**.


# Step 8: Program Door Locks
Source: https://docs.seam.co/device-and-system-integration-guides/assa-abloy-visionline-access-control-system/visionline-acs-setup-instructions/developing-and-launching-your-visionline-mobile-key-app/developing-your-visionline-mobile-key-app/step-8-program-door-locks

Learn how to program door locks for your mobile key integration.

Once you have [set up door locks](./step-7-set-up-door-locks-with-ble-profiles) in the Visionline application, use the Lock Service 3G application to program the door locks themselves. When you program a lock, you download the identity and settings for the lock from Lock Service 3G to the lock.

<Info>
  As part of its [mobile development
  course](./step-1-complete-the-assa-abloy-mobile-development-course), ASSA
  ABLOY provides a demo lock that includes the required BLE module.
</Info>

This process consists of the following basic steps:

1. [Install Lock Service 3G on a laptop or tablet.](#install-lock-service-3g)
2. [Configure the Visionline application to download door lock data to Lock Service 3G.](#configure-visionline-for-lock-service-3g)
3. [Configure Lock Service 3G to connect to the Visionline server.](#configure-lock-service-3g-to-connect-to-the-visionline-server)
4. [Download door lock data from the Visionline server to Lock Service 3G.](#download-door-lock-data-to-lock-service-3g)
5. [Initialize each door lock to program it with the correct settings.](#initialize-door-locks)

***

## Install Lock Service 3G

Install the Lock Service 3G on a Windows laptop or tablet that you can move to each door lock. You use an [RJ12 service cable](https://estore.assaabloyglobalsolutions.com/us/marine/service-cable-rj12-for-3g-rfid-lcu-e-cylinder.html) with an [RJ12 to USB adapter cable](https://estore.assaabloyglobalsolutions.com/us/marine/cable-rj12-to-usb-adapter-for-3g.html) to connect this laptop or tablet to each door lock.

<Info>
  If the service cable with adapter cable does not work correctly, you may need to install the following driver:

  `CDM v2.12.xx WHQL Certified.exe`
</Info>

***

## Configure Visionline for Lock Service 3G

1. Log in to the Visionline application if you are not already logged in.
2. Add a device.
   1. At the bottom of the left navigation pane, click **Lists**.
   2. In the **System setup** section of the left navigation pane, double-click **Devices**.
   3. In the **Devices** window, click **Add**.
   4. In the **Device details** window, type a **Name** for the device, such as `Lock Service 3G`.
   5. Select **Service device host** as the device **Type**.
   6. Make sure that the **Port** is `27015`.
   7. Make sure that the **Location** is **Server**.
   8. Click **Save**.
   9. In the **Device details** window, click **Close**.
   10. In the **Devices** window, click **Close**.
3. Obtain the registration code for the Lock Service 3G instance.
   1. At the bottom of the left navigation pane, click **Lists**.
   2. In the **System setup** section of the left navigation pane, double-click **Service devices**.
   3. In the **Service devices** window, click **Add**.
   4. Note the registration code and validity period that the Visionline application displays.\
      You must enter this code in Lock Service 3G on the laptop or tablet.
   5. Click **OK**.
   6. In the **Service devices** window, click **Close**.

***

## Configure Lock Service 3G to Connect to the Visionline Server

1. Open the Lock Service 3G application if you have not done so already.

2. Add a server connection.
   1. In the **Setup** section of the left navigation pane, click **Server connections**.
   2. If the **Server connections** dialog does not display automatically, click **Add**.
   3. In the **Server connections** dialog, type a **Name** for this connection to the Visionline server.\
      Note that some of the field names in this dialog are different in different versions of Lock Service 3G.
   4. In the **Address** field, type the IP address of the Visionline server.
   5. Type the **Port** number to use to connect to the Visionline server.
   6. Click **OK**.

3. At the right of the **Lock Service 3G** window, in the lower field in the **Serial port and host** area, select the name of the Visionline server connection that you created.

4. Register Lock Service 3G on the laptop or tablet.

   1. In the **Setup** section of the left navigation pane, click **Register PC**.
   2. In the **Register PC** area, type the registration **Code** that you obtained from the Visionline application.
   3. Click **Register**.

   Lock Service 3G registers with the Visionline server and displays a **Registration Finished** message.

5. Click **OK**.

6. Retrieve the Visionline system ID.

   1. In the **Setup** section of the left navigation pane, click **System ID**.
   2. In the **System ID** area, click **Get**.

   Lock Service 3G retrieves the Visionline system ID and then displays a **New system ID has been set** message.

7. Click **OK**.

***

## Download Door Lock Data to Lock Service 3G

1. Open the Lock Service 3G application if you have not done so already.
2. In the **Setup** section of the left navigation pane, click **Download data from server**.
3. At the right of the **Lock Service 3G** window, in the lower field in the **Serial port and host** area, select the name of the Visionline server connection.
4. In the **Download data from server** area, click **Check all**.
5. Click **Download**.

Lock Service downloads the door lock data from the Visionline server and displays a message when the download is complete.

***

## Initialize Door Locks

Perform the following steps on each lock:

1. Only if necessary, update the Lock Control Unit firmware.\
   **Test locks from ASSA ABLOY should already be preprogrammed with the correct firmware.**\
   For other locks, contact ASSA ABLOY to learn whether you need to update the Lock Control Unit firmware and, if so, to obtain the correct firmware version.
   1. Open the Lock Service 3G application if you have not done so already.
   2. In the **Initiation** section of the left navigation pane, click **Upload firmware**.
   3. At the right of the **Lock Service 3G** window, in the lower field in the **Serial port and host** area, select the name of the Visionline server connection.
   4. In the **Upload firmware** area, click **Browse**.\\
   5. Select the firmware that ASSA ABLOY has sent to you and then click **Open**.
   6. In the **Available versions** table, right-click the appropriate firmware version and select **Save to database**.\\
   7. In the **Available versions** table, select the appropriate firmware version.
   8. At the right of the **Lock Service 3G** window, in the upper field in the **Serial port and host** area, select the serial port that you want to use to connect to the lock.
   9. Connect the service cable with adapter cable from the laptop or tablet running Lock Service 3G to the lock.
   10. At the bottom of the **Upload firmware** area, click **Upload**.
2. Open the Lock Service 3G application if you have not done so already.
3. Initialize the lock.
   1. In the **Initiation** section of the left navigation pane, click **Initialize lock**.
   2. At the right of the **Lock Service 3G** window, in the lower field in the **Serial port and host** area, select the name of the Visionline server connection.
   3. In the **Initialize lock** area, expand the appropriate door area and select the lock that you want to initialize.
   4. Select the **Read parameters after successful initialization** checkbox.
   5. Select the **Include BLE configuration data** checkbox.
   6. At the right of the **Lock Service 3G** window, in the upper field in the **Serial port and host** area, select the serial port that you want to use to connect to the lock.
   7. Connect the service cable with adapter cable from the laptop or tablet running Lock Service 3G to the lock and then click **Initialize**.


# Step 9: Create a Production Workspace
Source: https://docs.seam.co/device-and-system-integration-guides/assa-abloy-visionline-access-control-system/visionline-acs-setup-instructions/developing-and-launching-your-visionline-mobile-key-app/developing-your-visionline-mobile-key-app/step-9-create-a-production-workspace

Learn how to create a production workspace to help you develop and test your Visionline mobile key app.

Create a Seam production workspace to connect your Visionline account to Seam. You can continue to use this workspace in your production phase as well.

1. Log in to [Seam Console](https://console.seam.co/).

2. In the upper-left corner, click the workspace switcher.

   <img alt="Use the Seam Console workspace switcher to switch between workspaces and create new workspaces." />

3. Click **New Workspace**.

4. In the **Add a Workspace** dialog, type a name for your new workspace and your company name.

5. Disable **Sandbox mode**.

   <img alt="To create a production workspace, disable sandbox mode." />

6. Click **Create Workspace**.


# Developing and Launching Your Visionline Mobile Key App
Source: https://docs.seam.co/device-and-system-integration-guides/assa-abloy-visionline-access-control-system/visionline-acs-setup-instructions/developing-and-launching-your-visionline-mobile-key-app/index

Learn how to develop and then launch your Visionline mobile key integration.

You can use your own Visionline development account to develop your Visionline mobile key app. Then, launch your app into production.

See the following instructions:

## Step 1: Development Phase

* [Developing Your Visionline Mobile Key App](/device-and-system-integration-guides/assa-abloy-visionline-access-control-system/visionline-acs-setup-instructions/developing-and-launching-your-visionline-mobile-key-app/developing-your-visionline-mobile-key-app/index)

## Step 2: Launch Phase

* [Launching Your Visionline Mobile Key App](/device-and-system-integration-guides/assa-abloy-visionline-access-control-system/visionline-acs-setup-instructions/developing-and-launching-your-visionline-mobile-key-app/launching-your-visionline-mobile-key-app/index)


# Launching Your Visionline Mobile Key App
Source: https://docs.seam.co/device-and-system-integration-guides/assa-abloy-visionline-access-control-system/visionline-acs-setup-instructions/developing-and-launching-your-visionline-mobile-key-app/launching-your-visionline-mobile-key-app/index

Learn how to launch your Visionline mobile key app into production.

Once you have developed and tested your Visionline mobile key app, you can launch your app into production.

For detailed instructions, see the following topics:

[Step 1: Obtain ASSA ABLOY Certification for Your Mobile Key App](./step-1-obtain-assa-abloy-certification-for-your-mobile-key-app)

[Step 2: Confirm That Your Visionline Site Meets the Requirements](./step-2-confirm-that-your-visionline-site-meets-the-requirements)

[Step 3: Confirm BLE Module on All Locks](./step-3-confirm-ble-module-on-all-locks)

<Info>
  This process can be quite time-consuming because it requires interaction with
  all locks.
</Info>

[Step 4: Set up Door Locks with BLE Profiles](./step-4-set-up-door-locks-with-ble-profiles)

[Step 5: Program Door Locks](./step-5-program-door-locks)

<Info>
  This process can be quite time-consuming because it requires interaction with
  all locks.
</Info>

[Step 6: Configure a Visionline User Account](./step-6-configure-a-visionline-user-account)

[Step 7: Purchase and Import the Callback and Mobile Service Options from ASSA ABLOY](./step-7-purchase-and-import-the-callback-and-mobile-service-options-from-assa-abloy)

[Step 8: Create a Production Workspace](./step-8-create-a-production-workspace)

<Info>
  Skip this step if you have already created a production workspace during the
  development phase and want to use this workspace to launch your app.
</Info>

[Step 9: Connect Your Visionline Production Account to Seam](../../../../assa-abloy-visionline-access-control-system/visionline-acs-setup-instructions/developing-and-launching-your-visionline-mobile-key-app/launching-your-visionline-mobile-key-app/step-9-connect-your-visionline-production-account-to-seam)


# Step 1: Obtain ASSA ABLOY Certification for Your Mobile Key App
Source: https://docs.seam.co/device-and-system-integration-guides/assa-abloy-visionline-access-control-system/visionline-acs-setup-instructions/developing-and-launching-your-visionline-mobile-key-app/launching-your-visionline-mobile-key-app/step-1-obtain-assa-abloy-certification-for-your-mobile-key-app

Learn how to obtain ASSA ABLOY certification for your Visionline mobile key app.

To launch your mobile app for issuing Visionline mobile keys into production, you must first obtain ASSA ABLOY certification. This certification process consists of the following steps:

* Answer a series of questions about your app. The categories of questions include app development and deployment, user authentication, credential issuance, mobile device handling, BLE reader integration, use cases, troubleshooting and support, and so on.
* Perform a set of pre-verification tests. Failing any of the pre-verification tests can result in a delay in the approval process.

Work with the ASSA ABLOY and Seam teams to achieve certification.

<Info>
  Once your app is certified, ASSA ABLOY provides you with a production Credential Services tenant account and production application ID for your mobile app. ASSA ABLOY gives you the following production details:

  * Tenant account username
  * Tenant account password
  * Credential Services URL
  * System ID
  * Application ID
  * Mobile access UUID

  Use this information to configure Visionline for mobile access and to connect your production Visionline account to Seam.
</Info>


# Step 2: Confirm That Your Visionline Site Meets the Requirements
Source: https://docs.seam.co/device-and-system-integration-guides/assa-abloy-visionline-access-control-system/visionline-acs-setup-instructions/developing-and-launching-your-visionline-mobile-key-app/launching-your-visionline-mobile-key-app/step-2-confirm-that-your-visionline-site-meets-the-requirements

Learn the system and lock requirements that your production Visionline site must meet.

Confirm that your production Visionline site meets the following system and lock requirements:

## System Requirements

Make sure that your computer meets the following requirements:

* Key server:
  * Visionline V1.27 (or newer)
  * Windows 10 1901 (or newer)
  * Hosted in a location where internet traffic is allowed

## Lock Requirements

Make sure that all locks meet the following requirements:

* ASSA ABLOY online locks:
  * Bluetooth modules installed

    See [Step 3: Confirm BLE Module on All Locks](./step-3-confirm-ble-module-on-all-locks).

For more details, see the following ASSA ABLOY Visionline document:


# Step 3: Confirm BLE Module on All Locks
Source: https://docs.seam.co/device-and-system-integration-guides/assa-abloy-visionline-access-control-system/visionline-acs-setup-instructions/developing-and-launching-your-visionline-mobile-key-app/launching-your-visionline-mobile-key-app/step-3-confirm-ble-module-on-all-locks

Learn how to confirm that the BLE module, which is required for mobile keys, is installed on all locks.

The Visionline integration for mobile key apps requires you to install the following BLE module on each door lock:

[https://estore.assaabloyglobalsolutions.com/no/marine/ble-module-pcba-7001.html](https://estore.assaabloyglobalsolutions.com/no/marine/ble-module-pcba-7001.html)

This process consists of the following basic steps:

1. [Install Lock Service 3G on a laptop or tablet.](#install-lock-service-3g)
2. [Confirm that all locks have the required BLE module.](#confirm-that-all-locks-have-the-required-ble-module)

<Info>
  This process can be quite time-consuming because it requires interaction with
  all locks.
</Info>

***

## Install Lock Service 3G

Install the Lock Service 3G on a Windows laptop or tablet that you can move to each door lock. You use a USB-to-lock interface cable to connect this laptop or tablet to each door lock.

<Info>
  If the USB-to-lock interface cable does not work correctly, you may need to install the following driver:

  `CDM v2.12.xx WHQL Certified.exe`
</Info>

***

## Confirm that All Locks Have the Required BLE Module

Perform the following procedure for each lock:

1. On the laptop or tablet, open the Lock Service 3G application.
2. Connect the cable from the laptop or tablet running Lock Service 3G to the lock.
3. At the right of the **Lock Service 3G** window, in the upper field in the **Serial port and host** area, select the serial port that you want to use to connect to the lock.
4. In the **Readout** section of the left navigation pane, click **Parameters**.
5. In the **Parameters** area, click **Readout**.
6. Click the **Module** tab.
7. Confirm that the lock includes a BLE module.


# Step 4: Set up Door Locks with BLE Profiles
Source: https://docs.seam.co/device-and-system-integration-guides/assa-abloy-visionline-access-control-system/visionline-acs-setup-instructions/developing-and-launching-your-visionline-mobile-key-app/launching-your-visionline-mobile-key-app/step-4-set-up-door-locks-with-ble-profiles

Learn how to set up door locks with BLE profiles when launching your Visionline mobile key app into production.

In the Visionline application, set up all door locks for your Visionline mobile key integration.

Use the Visionline application to define guest room and common door locks. First, set up the desired door areas, such as `Guest Doors` and `Common Doors`. Then, define each door and assign it to the appropriate door area. When you define a door or set of doors, you also choose a door type, to determine the access behavior of the door. Visionline door types include guest, guest entrance, guest common, elevator reader, elevator reader relay, and so on.

Note that for common doors, guest entrance doors and elevator reader relays automatically give access to guests within a specific guest door range, such as common entrances. Then, you assign elevator reader relays to the corresponding elevator reader.

For guest common doors, you must grant guest access manually, such as for a gym door or parking entrance.

<Info>
  These instructions use Visionline 1.27. If you are using Visionline 1.28, you
  may notice differences in a few field names.
</Info>

***

## Set up Guest Room Locks

When defining guest room doors, first create a door area and then create a door of the **Guest** door type.

1. Log in to the Visionline application.
2. Set up a door area for guest rooms.
   1. At the bottom of the left navigation pane, click **Lists**.
   2. In the **System setup** section of the left navigation pane, double-click **Door areas**.
   3. In the **Door areas** window, click **Add**.
   4. In the **Door area details** dialog, type a name and, optionally, a description for the new door area.\
      For example, you could create a door area named `Guest Doors`.
   5. Click **Save**.
   6. To add more door areas, click **New** and then repeat this process in the **Door area details** dialog.
   7. When you are done adding door areas, in the **Door area details** dialog, click **Close**.
   8. In the **Door areas** window, click **Close**.
3. Define each set of guest room doors.
   1. At the bottom of the left navigation pane, click **Lists**.
   2. In the **System setup** section of the left navigation pane, double-click **Doors**.
   3. In the **Doors** window, click **Add**.
   4. In the **Door details** window, select **Guest** as the door **Type**.
   5. In the **Number** field, type the door range.\
      For example: `101-109`
   6. In the **Area** field, select the guest door area that you created.\
      For example: **Guest Doors**
   7. In the left navigation pane of the **Door details** window, click **Profiles**.
   8. In the **Profiles** pane, select the desired BLE profile.
   9. Click **Save**.
   10. To add more door sets, click **New** and then repeat this process in the **Door details** window.
   11. When you are done adding door sets, in the **Door details** window, click **Close**.
   12. In the **Doors** window, click **Close**.

***

## Set up Common Door Locks

When defining common doors, make sure to choose the appropriate door type. Visionline door types include the following, among others:

<table>
  <thead>
    <tr>
      <th>Door Type</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Guest entrance</td>

      <td>
        Specify a set of guest doors to give automatic access to guests within
        this range. You can use this door type for common entrances.
      </td>
    </tr>

    <tr>
      <td>Guest common</td>

      <td>
        You must grant access to doors of this type explicitly to specific guest
        credentials. You can use this door type for gym doors, parking
        entrances, and so on.
      </td>
    </tr>

    <tr>
      <td>Elevator reader relay</td>

      <td>
        This door type represents a floor button or relay within an elevator.
        Specify a set of guest doors to give automatic access to guests within
        this range. Assign each elevator reader relay to the corresponding
        "slot" in an elevator reader definition.
      </td>
    </tr>

    <tr>
      <td>Elevator reader</td>

      <td>
        The door type serves as an organization mechanism for sets of elevator
        reader relays.
      </td>
    </tr>
  </tbody>
</table>

<Info>For more information about door types, see the Visionline Help.</Info>

To define a common door, first create a door area and then create a door of the appropriate type.

1. Log in to the Visionline application if you are not already logged in.
2. Set up a door area for the group of common doors.
   1. At the bottom of the left navigation pane, click **Lists**.
   2. In the **System setup** section of the left navigation pane, double-click **Door areas**.
   3. In the **Door areas** window, click **Add**.
   4. In the **Door area details** dialog, type a name and, optionally, a description for the new door area.\
      For example, you could create a door area named `Common Doors`.
   5. Click **Save**.
   6. To add more door areas, click **New** and then repeat this process in the **Door area details** dialog.
   7. When you are done adding door areas, in the **Door area details** dialog, click **Close**.
   8. In the **Door areas** window, click **Close**.
3. Define each common door.
   1. At the bottom of the left navigation pane, click **Lists**.
   2. In the **System setup** section of the left navigation pane, double-click **Doors**.
   3. In the **Doors** window, click **Add**.
   4. In the **Door details** window, select the appropriate door **Type**.\
      See the table at the beginning of this section for descriptions of some common door types.
   5. Type a **Name** for the door, reader, relay, or other entrance.
   6. For a guest entrance door or elevator reader relay, type the beginning and ending room numbers to define the associated **Room interval**.\
      Note that for guest common entrances, you set up access permissions explicitly when creating guest or other credentials.
   7. In the **Area** field, select the common door area that you created.\
      For example: **Common Doors**
   8. For an elevator reader, set the relay outputs to define the access permissions by floor or other output:
      1. In the **Relay outputs** table, select an output.
      2. Click **Select**.
      3. In the **Select elevator reader relay** dialog, select the corresponding elevator reader relay and then click **OK**.
      4. Repeat this process for any additional relay outputs.
   9. In the left navigation pane of the **Door details** window, click **Profiles**.
   10. In the **Profiles** pane, select the desired BLE profile.
   11. Click **Save**.
   12. To add more common doors, click **New** and then repeat this process in the **Door details** window.
   13. When you are done adding common doors, in the **Door details** window, click **Close**.
   14. In the **Doors** window, click **Close**.


# Step 5: Program Door Locks
Source: https://docs.seam.co/device-and-system-integration-guides/assa-abloy-visionline-access-control-system/visionline-acs-setup-instructions/developing-and-launching-your-visionline-mobile-key-app/launching-your-visionline-mobile-key-app/step-5-program-door-locks

Learn how to program door locks for your mobile key integration.

Once you have [set up door locks](./step-4-set-up-door-locks-with-ble-profiles) in the Visionline application, use the Lock Service 3G application to program the door locks themselves. When you program a lock, you download the identity and settings for the lock from Lock Service 3G to the lock.

This process consists of the following basic steps:

1. [Configure the Visionline application to download door lock data to Lock Service 3G.](#configure-visionline-for-lock-service-3g)
2. [Configure Lock Service 3G to connect to the Visionline server.](#configure-lock-service-3g-to-connect-to-the-visionline-server)
3. [Download door lock data from the Visionline server to Lock Service 3G.](#download-door-lock-data-to-lock-service-3g)
4. [Initialize each door lock to program it with the correct settings.](#initialize-door-locks)

***

## Configure Visionline for Lock Service 3G

1. Log in to the Visionline application if you are not already logged in.
2. Add a device.
   1. At the bottom of the left navigation pane, click **Lists**.
   2. In the **System setup** section of the left navigation pane, double-click **Devices**.
   3. In the **Devices** window, click **Add**.
   4. In the **Device details** window, type a **Name** for the device, such as `Lock Service 3G`.
   5. Select **Service device host** as the device **Type**.
   6. Make sure that the **Port** is `27015`.
   7. Make sure that the **Location** is **Server**.
   8. Click **Save**.
   9. In the **Device details** window, click **Close**.
   10. In the **Devices** window, click **Close**.
3. Obtain the registration code for the Lock Service 3G instance.
   1. At the bottom of the left navigation pane, click **Lists**.
   2. In the **System setup** section of the left navigation pane, double-click **Service devices**.
   3. In the **Service devices** window, click **Add**.
   4. Note the registration code and validity period that the Visionline application displays.\
      You must enter this code in Lock Service 3G on the laptop or tablet.
   5. Click **OK**.
   6. In the **Service devices** window, click **Close**.

***

## Configure Lock Service 3G to Connect to the Visionline Server

1. Open the Lock Service 3G application if you have not done so already.

2. Add a server connection.
   1. In the **Setup** section of the left navigation pane, click **Server connections**.
   2. If the **Server connections** dialog does not display automatically, click **Add**.
   3. In the **Server connections** dialog, type a **Name** for this connection to the Visionline server.\
      Note that some of the field names in this dialog are different in different versions of Lock Service 3G.
   4. In the **Address** field, type the IP address of the Visionline server.
   5. Type the **Port** number to use to connect to the Visionline server.
   6. Click **OK**.

3. At the right of the **Lock Service 3G** window, in the lower field in the **Serial port and host** area, select the name of the Visionline server connection that you created.

4. Register Lock Service 3G on the laptop or tablet.

   1. In the **Setup** section of the left navigation pane, click **Register PC**.
   2. In the **Register PC** area, type the registration **Code** that you obtained from the Visionline application.
   3. Click **Register**.

   Lock Service 3G registers with the Visionline server and displays a **Registration Finished** message.

5. Click **OK**.

6. Retrieve the Visionline system ID.

   1. In the **Setup** section of the left navigation pane, click **System ID**.
   2. In the **System ID** area, click **Get**.

   Lock Service 3G retrieves the Visionline system ID and then displays a **New system ID has been set** message.

7. Click **OK**.

***

## Download Door Lock Data to Lock Service 3G

1. Open the Lock Service 3G application if you have not done so already.
2. In the **Setup** section of the left navigation pane, click **Download data from server**.
3. At the right of the **Lock Service 3G** window, in the lower field in the **Serial port and host** area, select the name of the Visionline server connection.
4. In the **Download data from server** area, click **Check all**.
5. Click **Download**.

Lock Service downloads the door lock data from the Visionline server and displays a message when the download is complete.

***

## Initialize Door Locks

Perform the following steps on each lock:

1. Only if necessary, update the Lock Control Unit firmware.\
   **Test locks from ASSA ABLOY should already be preprogrammed with the correct firmware.**\
   For other locks, contact ASSA ABLOY to learn whether you need to update the Lock Control Unit firmware and, if so, to obtain the correct firmware version.
   1. Open the Lock Service 3G application if you have not done so already.
   2. In the **Initiation** section of the left navigation pane, click **Upload firmware**.
   3. At the right of the **Lock Service 3G** window, in the lower field in the **Serial port and host** area, select the name of the Visionline server connection.
   4. In the **Upload firmware** area, click **Browse**.
   5. Select the firmware that ASSA ABLOY has sent to you and then click **Open**.
   6. In the **Available versions** table, right-click the appropriate firmware version and select **Save to database**.
   7. In the **Available versions** table, select the appropriate firmware version.
   8. At the right of the **Lock Service 3G** window, in the upper field in the **Serial port and host** area, select the serial port that you want to use to connect to the lock.
   9. Connect the [service cable](https://estore.assaabloyglobalsolutions.com/us/marine/service-cable-rj12-for-3g-rfid-lcu-e-cylinder.html) with [adapter cable](https://estore.assaabloyglobalsolutions.com/us/marine/cable-rj12-to-usb-adapter-for-3g.html) from the laptop or tablet running Lock Service 3G to the lock.
   10. At the bottom of the **Upload firmware** area, click **Upload**.
2. Open the Lock Service 3G application if you have not done so already.
3. Initialize the lock.
   1. In the **Initiation** section of the left navigation pane, click **Initialize lock**.
   2. At the right of the **Lock Service 3G** window, in the lower field in the **Serial port and host** area, select the name of the Visionline server connection.
   3. In the **Initialize lock** area, expand the appropriate door area and select the lock that you want to initialize.
   4. Select the **Read parameters after successful initialization** checkbox.
   5. Select the **Include BLE configuration data** checkbox.
   6. At the right of the **Lock Service 3G** window, in the upper field in the **Serial port and host** area, select the serial port that you want to use to connect to the lock.
   7. Connect the service cable with adapter cable from the laptop or tablet running Lock Service 3G to the lock and then click **Initialize**.

      <Info>
        The lock and cable connection times out after 30 seconds. If programming
        the lock results in an error, try unplugging the cable from the lock and
        reconnecting it. Then, try initializing the lock again.
      </Info>


# Step 6: Configure a Visionline User Account
Source: https://docs.seam.co/device-and-system-integration-guides/assa-abloy-visionline-access-control-system/visionline-acs-setup-instructions/developing-and-launching-your-visionline-mobile-key-app/launching-your-visionline-mobile-key-app/step-6-configure-a-visionline-user-account

Learn how to set up a Visionline user account to integrate with Seam.

Make sure that your Visionline application is configured with an appropriate user account. You use this account to connect the Visionline instance with Seam. You can use the default `sym` username and password.

Alternately, the Visionline ACS administrator can create a Visionline user specifically for the connection with Seam. This user must be configured as an operator that uses the System Manager operator template. This user must also have a password.

To create a new Visionline user for the Seam connection, first create a new user. Then, configure the user as an operator that uses the System Manager operator template.

<Info>
  These instructions use Visionline 1.27. If you are using Visionline 1.28, you
  may notice differences in a few field names.
</Info>

1. Log in to the Visionline application as a user with System Manager access.
2. Create a new Visionline user.
   1. At the bottom of the left navigation pane, click **Lists**.
   2. In the **System administration** section of the left navigation pane, double-click **Users**.
   3. In the **Users** window, click **Add**.
   4. In the **User details** window, type a **User ID** for the new user, for example, `Seam Integration`.
   5. Type the **Last name** of the user, for example, `Integration`.
   6. Type the **First name** of the user, for example, `Seam`.
   7. Select the **User group** to which to assign the user.
   8. Optionally, in the **PIN** field, type a PIN for the user.
   9. If you've added a PIN, in the **Confirm PIN** field, type the same PIN for the user.
   10. Click **Save**.
   11. In the **User details** dialog, click **Close**.
   12. In the **Users** window, click **Close**.
3. Configure the new user as an operator that uses the System Manager operator template.
   1. At the bottom of the left navigation pane, click **Lists**.
   2. In the **System access** section of the left navigation pane, double-click **Operators**.
   3. In the **Operators** window, click **Add**.
   4. In the **Operator details** dialog, click **...** next to the **User name** field.
   5. In the **Users \<Operator details>** window, select the user that you created and then click **Select**.
   6. In the **Operator details** dialog, select **System Manager** as the **Operator template**.\
      Alternately, you can create a new operator template for the new user, but you must make sure that this operator template has access to all permissions.
   7. In the **Password** and **Confirm Password** fields, type a password for the user.
   8. Click **Save**.
   9. In the **Operator details** dialog, click **Close**.
   10. In the **Operators** window, click **Close**.
4. Note the username and password for this Visionline user. You must use these credentials when you [connect your Visionline account to Seam](./step-9-connect-your-visionline-production-account-to-seam).


# Step 7: Purchase and Import the Callback and Mobile Service Options from ASSA ABLOY
Source: https://docs.seam.co/device-and-system-integration-guides/assa-abloy-visionline-access-control-system/visionline-acs-setup-instructions/developing-and-launching-your-visionline-mobile-key-app/launching-your-visionline-mobile-key-app/step-7-purchase-and-import-the-callback-and-mobile-service-options-from-assa-abloy

Learn about the Callback and Mobile Service options that you need to purchase from ASSA ABLOY and import into Visionline.

To launch your Visionline mobile key app into production, you must purchase the Callback and Mobile Service options from ASSA ABLOY and then import these options into Visionline.

1. Purchase the Callback and Mobile Service options from ASSA ABLOY.

   To purchase these options, contact ASSA ABLOY.

   Once you purchase these options, ASSA ABLOY provides you with corresponding option codes.

2. Import the corresponding option codes into Visionline.
   1. Open Visionline.
   2. In the top menu, click **Tools** > **Option code**.
   3. In the **Option code** field, type or paste the option codes that you received from Visionline and then click **Apply**.

3. Verify that the required options have been configured.
   1. At the bottom of the Visionline left navigation pane, click **Reports**.
   2. In the **Pre-defined** section of the left navigation pane, double-click **System settings**.
   3. If desired, print or export the report.
   4. In the report, find the **`[Options]`** section and verify that the purchased options are listed.


# Step 8: Create a Production Workspace
Source: https://docs.seam.co/device-and-system-integration-guides/assa-abloy-visionline-access-control-system/visionline-acs-setup-instructions/developing-and-launching-your-visionline-mobile-key-app/launching-your-visionline-mobile-key-app/step-8-create-a-production-workspace

Learn how to create a production workspace for your production Visionline mobile key app.

If you did not create a Seam production workspace during the development phase for your Visionline mobile key app, you must create a new production workspace to connect your Visionline production account to Seam. If you did create a production workspace already, you can choose to continue using this workspace or to create a new one.

To create a production workspace.

1. Log in to [Seam Console](https://console.seam.co/).

2. In the upper-left corner, click the workspace switcher.

   <img alt="Use the Seam Console workspace switcher to switch between workspaces and create new workspaces." />

3. Click **New Workspace**.

4. In the **Add a Workspace** dialog, type a name for your new workspace and your company name.

5. Disable **Sandbox mode**.

   <img alt="To create a production workspace, disable sandbox mode." />

6. Click **Create Workspace**.


# Step 9: Connect Your Visionline Production Account to Seam
Source: https://docs.seam.co/device-and-system-integration-guides/assa-abloy-visionline-access-control-system/visionline-acs-setup-instructions/developing-and-launching-your-visionline-mobile-key-app/launching-your-visionline-mobile-key-app/step-9-connect-your-visionline-production-account-to-seam

Learn how to connect your Visionline production account to Seam.

To launch your mobile key app into production, perform the following procedures to connect your Visionline production account to Seam:

1. [Connect your ASSA ABLOY Credential Services production account to Seam.](#connect-credential-services-to-seam)
2. [Connect your Visionline production account to Seam.](#connect-visionline-to-seam)

   This process includes installing and running Seam Bridge to connect your on-premises Visionline application to Seam. For more information, see [Seam Bridge](/capability-guides/seam-bridge).

<Info>
  If you already connected your Visionline ACS to Seam during the development
  phase—using your Visionline development account—you must now reconnect
  Visionline to Seam using your production Visionline credentials.
</Info>

***

## Connect Credential Services to Seam

ASSA ABLOY Credential Services stores all the mobile credentials that your application issues. For more information about ASSA ABLOY Credential Services, see the [ASSA ABLOY Credential Services integration guide](/device-and-system-integration-guides/assa-abloy-vingcard-credential-services/index).

You received a Credential Services production "tenant" account from ASSA ABLOY when you [obtained ASSA ABLOY certification](./step-1-obtain-assa-abloy-certification-for-your-mobile-key-app) for your mobile key app. ASSA ABLOY provided you with the following production-phase information upon certification:

* Tenant account username
* Tenant account password
* Credential Services URL
* Application ID

<Info>
  ASSA ABLOY assigned you a preliminary application ID during the development phase. You cannot use this preliminary application ID to connect to live sites. To connect to real sites, you must use the production application ID that you received from ASSA ABLOY when you obtained ASSA ABLOY certification. This production application ID uniquely identifies your application within both the iOS and Android app stores.

  Once you've obtained certification, you must edit your workspace settings to update this application ID.
</Info>

1. In the top navigation pane of [Seam Console](https://console.seam.co/), click **ACS Systems**. Then, in the upper-right corner of the **Access Systems** page, click **New Access System**.
2. In the Connect Webview, perform the following steps:
   1. Click **Continue**.
   2. If the Connect Webview displays multiple brand options, select **Assa Abloy Credential Service**.
   3. In the **Username** field, type your production tenant account username.
   4. In the **Password** field, type your production tenant account password.
   5. In the **Credential Services URL** field, type the production Credential Services URL.
   6. Click **Submit**.
3. Configure your ASSA ABLOY settings in Seam Console, as follows:
   1. In the top navigation pane of [Seam Console](https://console.seam.co/), click **Settings**.
   2. On the **Workspace Settings** page, next to **Assa Abloy Settings**, click **Edit**.
   3. In the **Assa Abloy Settings** dialog, type your production application ID.
   4. Click **Save**.

***

## Connect Visionline to Seam

Perform this process for each Visionline site that you want to connect to Seam.

1. Identify your production Visionline mobile access UUID and system ID.

   Note that you received these details when you [obtained ASSA ABLOY certification](./step-1-obtain-assa-abloy-certification-for-your-mobile-key-app). Alternately, to find this information:

   1. In the Visionline application, at the bottom of the left navigation pane, click **Lists**.
   2. In the **System setup** section of the left navigation pane, double-click **Mobile Access Accounts**.
   3. Double-click the production mobile access account that you created for the Seam integration.
   4. In the **Mobile Access account details** window, note the **System ID**.
   5. In the top menu in the Visionline application, click **Tools > Options**.
   6. In the left navigation pane of the **Options** window, click **Mobile Access**.
   7. Note the **UUID**.

2. In the top navigation pane of [Seam Console](https://console.seam.co/), click **ACS Systems**.

3. On the **Access Systems** page, click **New Access System**.

   Seam Console displays a Connect Webview that enables you to connect your ACS to Seam.

4. In the Connect Webview, click **Continue**.

5. If the Connect Webview displays multiple brand options, click **Visionline**.

6. On the **Set up your Seam Bridge** page, click [**latest Seam Bridge client**](https://www.seam.co/seam-bridge/releases/latest).

   [Seam Bridge](/capability-guides/seam-bridge) is a software-only component that enables you to connect on-premises software systems to the Seam platform. Because Visionline is an on-premises ACS, Seam Bridge is required for Visionline systems.

7. Download the Seam Bridge executable onto the on-premises computer that is running Visionline or onto a computer on the same network.

   For systems requirements, see [Seam Bridge](/capability-guides/seam-bridge).

8. Run the downloaded Seam Bridge app.

9. In the **Welcome to Seam Bridge** window, type a name for the site that you are connecting using Seam Bridge and then click **Start pairing**.

10. Copy the pairing code.

11. In the Connect Webview, click **Continue**.

12. On the **Set up your Seam Bridge** page:
    1. In the **Enter your pairing token** field, paste the pairing code that you copied.
    2. Click **Submit**.

13. On the **Enter your credentials** page:
    1. In the **Visionline Site Name** field, type a name to identify the Visionline site within your Seam workspace.

    2. In the **Username** field, type the username for your Visionline production account.

       This account is the one that you [created or identified in Visionline for the connection with Seam](./step-6-configure-a-visionline-user-account).

    3. In the **Password** field, type the password for your Visionline production account.

    4. Select the **Mobile Keys will be issued in this system** checkbox.

    5. In the **Mobile Access UUID** field, type your production mobile access UUID.

    6. In the **System ID** field, type your production system ID.

    7. If Seam Bridge is not installed on the same computer as Visionline, select **Seam Bridge and Visionline server are installed on different computers** and then type the local IP address of the on-premises computer running Seam Bridge.

    8. Click **Submit**.

14. Click **Close**.


# Developing Your Visionline Plastic Card Encoding App Using a Real Visionline Server
Source: https://docs.seam.co/device-and-system-integration-guides/assa-abloy-visionline-access-control-system/visionline-acs-setup-instructions/developing-and-launching-your-visionline-plastic-card-encoding-app/developing-your-visionline-plastic-card-encoding-app-using-a-real-visionline-server/index

Learn how to use a Real Visionline server to develop your Visionline plastic card encoding app.

You can use an unlicensed Visionline account to develop and test your Visionline plastic card encoding integration. Then, you can launch your app into production using a real Visionline site.

<Info>
  There are some differences between using an unlicensed Visionline account and
  using a real, production Visionline site. Consequently, when you are ready to
  launch your app to production, make sure to follow the [instructions for
  launching](/device-and-system-integration-guides/assa-abloy-visionline-access-control-system/visionline-acs-setup-instructions/developing-and-launching-your-visionline-plastic-card-encoding-app/launching-your-visionline-plastic-card-encoding-app-to-a-live-site/index).
</Info>

For detailed instructions, see the following topics:

[Step 1: Install Your Visionline Application](./step-1-install-your-visionline-application)

[Step 2: Unblock Required Ports](./step-2-unblock-required-ports)

[Step 3: Configure a Visionline User Account](./step-3-configure-a-visionline-user-account)

[Step 4: Install a Visionline Card Encoder](./step-4-install-a-visionline-card-encoder)

[Step 5: Set up Door Locks](./step-5-set-up-door-locks)

[Step 6: Program Door Locks](./step-6-program-door-locks)

[Step 7: Create a Production Workspace](./step-7-create-a-production-workspace)

[Step 8: Connect Your Visionline Development Account to Seam](../../../../assa-abloy-visionline-access-control-system/visionline-acs-setup-instructions/developing-and-launching-your-visionline-plastic-card-encoding-app/developing-your-visionline-plastic-card-encoding-app-using-a-real-visionline-server/step-8-connect-your-visionline-development-account-to-seam)

[Next Steps](./next-steps)


# Next Steps
Source: https://docs.seam.co/device-and-system-integration-guides/assa-abloy-visionline-access-control-system/visionline-acs-setup-instructions/developing-and-launching-your-visionline-plastic-card-encoding-app/developing-your-visionline-plastic-card-encoding-app-using-a-real-visionline-server/next-steps

After you set up your Visionline ACS to develop your plastic card encoding app, learn what's next.

Once you've set up your Visionline ACS using your Visionline development account, proceed to the following steps:

1. Develop your Visionline plastic card encoding app.
2. Test your app.
3. Launch your app into production.

   For details, see [Launching Your Visionline Plastic Card Encoding App to a Live Site](/device-and-system-integration-guides/assa-abloy-visionline-access-control-system/visionline-acs-setup-instructions/developing-and-launching-your-visionline-plastic-card-encoding-app/launching-your-visionline-plastic-card-encoding-app-to-a-live-site/index).


# Step 1: Install Your Visionline Application
Source: https://docs.seam.co/device-and-system-integration-guides/assa-abloy-visionline-access-control-system/visionline-acs-setup-instructions/developing-and-launching-your-visionline-plastic-card-encoding-app/developing-your-visionline-plastic-card-encoding-app-using-a-real-visionline-server/step-1-install-your-visionline-application

Learn how to install the Visionline application and use your Visionline development account.

You can install the Visionline application and use a development—pre-certification—Visionline account to develop and test your plastic card encoding app.

To obtain access, contact Seam at [support@seam.co](mailto:support@seam.co).

***

## System Requirements

Make sure that your computer meets the following requirements:

* Key server:
  * Visionline V1.27 (or newer)
  * Windows 10 1901 (or newer)
  * Hosted in a location where internet traffic is allowed
* ASSA ABLOY online locks:
  * Bluetooth modules and licenses installed

For more details, see the following ASSA ABLOY Visionline document:

***

## Install Visionline

Install the Visionline application on a Windows computer.

<Info>
  When prompted for an account username and password, you must specify the
  username and password of the Windows account that has administrative rights to
  the computer on which you are installing Visionline.
</Info>

For detailed instructions, see the following ASSA ABLOY Visionline document:

***

## Start Visionline

When you open the Visionline application, choose unlicensed mode.


# Step 2: Unblock Required Ports
Source: https://docs.seam.co/device-and-system-integration-guides/assa-abloy-visionline-access-control-system/visionline-acs-setup-instructions/developing-and-launching-your-visionline-plastic-card-encoding-app/developing-your-visionline-plastic-card-encoding-app-using-a-real-visionline-server/step-2-unblock-required-ports

Learn which ports are required for using Visionline.

Unblock the required ports on the Visionline server and client.

1. Unblock the following ports on the server:
   * All files in the Visionline `Program Files` and `ProgramData` folders\
     The default locations are `C:\Program Files\ASSA ABLOY\Visionline` and `C:\ProgramData\ASSA ABLOY\Visionline`.
   * Firewall ports:
     * Port 135 (TCP)
     * 3001 (TCP)
     * 7799, 7788 (TCP/UDP)
     * Lock Service Port (27015 default) (TCP)
     * PMS port (4000 default) (TCP)
2. Unblock the following ports on the client:
   * All files in the Visionline `Program Files` and `ProgramData` folders\
     The default locations are `C:\Program Files\ASSA ABLOY\Visionline` and `C:\ProgramData\ASSA ABLOY\Visionline`.
   * Firewall ports
     * Port 135 (TCP)
     * 3001 (TCP)
     * DCOM ports

For more details, see the following ASSA ABLOY Visionline document:


# Step 3: Configure a Visionline User Account
Source: https://docs.seam.co/device-and-system-integration-guides/assa-abloy-visionline-access-control-system/visionline-acs-setup-instructions/developing-and-launching-your-visionline-plastic-card-encoding-app/developing-your-visionline-plastic-card-encoding-app-using-a-real-visionline-server/step-3-configure-a-visionline-user-account

Learn how to set up a Visionline user account to integrate with Seam.

Make sure that your Visionline application is configured with an appropriate user account. You use this account to connect the Visionline instance with Seam. You can use the default `sym` username and password.

Alternately, the Visionline ACS administrator can create a Visionline user specifically for the connection with Seam. This user must be configured as an operator that uses the System Manager operator template. This user must also have a password.

To create a new Visionline user for the Seam connection, first create a new user. Then, configure the user as an operator that uses the System Manager operator template.

<Info>
  These instructions use Visionline 1.27. If you are using Visionline 1.28, you
  may notice differences in a few field names.
</Info>

1. Log in to the Visionline application as a user with System Manager access.

   When opening Visionline during the development phase, use unlicensed mode.

2. Create a new Visionline user.
   1. At the bottom of the left navigation pane, click **Lists**.
   2. In the **System administration** section of the left navigation pane, double-click **Users**.
   3. In the **Users** window, click **Add**.
   4. In the **User details** window, type a **User ID** for the new user, for example, `Seam Integration`.
   5. Type the **Last name** of the user, for example, `Integration`.
   6. Type the **First name** of the user, for example, `Seam`.
   7. Select the **User group** to which to assign the user.
   8. Optionally, in the **PIN** field, type a PIN for the user.
   9. If you've added a PIN, in the **Confirm PIN** field, type the same PIN for the user.
   10. Click **Save**.
   11. In the **User details** dialog, click **Close**.
   12. In the **Users** window, click **Close**.

3. Configure the new user as an operator that uses the System Manager operator template.
   1. At the bottom of the left navigation pane, click **Lists**.
   2. In the **System access** section of the left navigation pane, double-click **Operators**.
   3. In the **Operators** window, click **Add**.
   4. In the **Operator details** dialog, click **...** next to the **User name** field.
   5. In the **Users \<Operator details>** window, select the user that you created and then click **Select**.
   6. In the **Operator details** dialog, select **System Manager** as the **Operator template**.\
      Alternately, you can create a new operator template for the new user, but you must make sure that this operator template has access to all permissions.
   7. In the **Password** and **Confirm Password** fields, type a password for the user.
   8. Click **Save**.
   9. In the **Operator details** dialog, click **Close**.
   10. In the **Operators** window, click **Close**.

4. Note the username and password for this Visionline user. You must use these credentials when you [connect your Visionline account to Seam](./step-8-connect-your-visionline-development-account-to-seam).


# Step 4: Install a Visionline Card Encoder
Source: https://docs.seam.co/device-and-system-integration-guides/assa-abloy-visionline-access-control-system/visionline-acs-setup-instructions/developing-and-launching-your-visionline-plastic-card-encoding-app/developing-your-visionline-plastic-card-encoding-app-using-a-real-visionline-server/step-4-install-a-visionline-card-encoder

Learn how to install and configure a Visionline card encoder for your Visionline plastic card encoding integration.

Buy and install a Visionline card encoder—specifically, the [ASSA ABLOY RFID encoder & updater](https://estore.assaabloyglobalsolutions.com/no/marine/rfid-encoder-updater-complete.html)—and then connect it to your Visionline server.

1. Install USB drivers.
   1. Install the USBXpress Development Kit.\
      This file is available for download from the [Silabs web site](https://www.silabs.com/Support%20Documents/Software/USBXpress_Install.exe).
   2. Connect the RFID encoder & updater to the power supply.
   3. Connect the RFID encoder & updater to the computer using the USB cable.
   4. On your Windows computer, go to the **Device Manager**.
   5. Expand the **Universal Serial Bus controllers** category.
   6. Double-click **USBXpress Device** .
   7. In the **General** tab of the **USBXpress Device Properties** window, make sure that the **Device status** is `This device is working properly`.
   8. In the Visionline bundle, under **RFID Encoder/RFID Encoder Configuration Utility**, double-click **RFIDEncoderConfig.exe**.

      Note that, starting with Visionline 1.24.0, the **RFID Encoder Configuration Utility** is automatically installed in the Visionline installation folder when **Visionline.msi** is installed.

      If the RFID encoder & updater is correctly connected to the PC and correctly uses the USBXpress driver, the serial number of the RFID encoder & updater displays in the **USB** area at the upper-left of the window.

2. Connect the card encoder to the Visionline server using USB.

   <Info>
     To connect through USB, you must use firmware version 2.6.2.4 or higher for
     the RFID encoder. Visionline 1.22.1 or higher is also required.
   </Info>

   3. Register the card encoder.\ 1. Log in to the Visionline application if
      you are not already logged in.\ 2. At the bottom of the left navigation
      pane, click \*\*Lists\*\*.\ 3. In the \*\*System setup\*\* section of the
      left navigation pane, double-click \*\*Devices\*\*.\ 4. In the
      \*\*Devices\*\* window, click \*\*Add\*\*.\ 5. In the \*\*Device details\*\*
      window, type a \*\*Name\*\* for the RFID encoder & updater.\ 6. If desired,
      type a \*\*Description\*\*.\ 7. In the \*\*Type\*\* field, select
      \*\*Network RFID encoder (USB)\*\*.

```
   ![Specify the details for the new card encoder device.](/images/visionline-card-encoder-device-details-window.png)
```

8\. Click **...** next to the **S/N** field.

```
   The list displays all network RFID encoder & updaters that are connected through USB.
```

9\. Make sure that the correct RFID encoder & updater is selected.

```
   ![Select the correct RFID encoder &#x26; updater.](/images/visionline-card-encoder-select-s-n-field.png)
```

10\. Select the correct **Location**.\
11\. If you have selected **Server** or **Computer** as the **Location**, type the **PMS address**, if applicable.\
12\. Click **Save**.\
13\. In the **Device details** window, click **Close**.\
14\. In the **Devices** window, click **Close**.\
4\. Select the card encoder to which the Visionline server should send cards.

1. Click **File** > **Select encoder**.
2. Select the encoder that you registered in the previous section and then click **OK**.


# Step 5: Set up Door Locks
Source: https://docs.seam.co/device-and-system-integration-guides/assa-abloy-visionline-access-control-system/visionline-acs-setup-instructions/developing-and-launching-your-visionline-plastic-card-encoding-app/developing-your-visionline-plastic-card-encoding-app-using-a-real-visionline-server/step-5-set-up-door-locks

Learn how to set up door locks when developing your Visionline plastic card encoding integration.

In the Visionline application, set up all door locks for your Visionline plastic card encoding integration.

Use the Visionline application to define guest room and common door locks. First, set up the desired door areas, such as `Guest Doors` and `Common Doors`. Then, define each door and assign it to the appropriate door area. When you define a door or set of doors, you also choose a door type, to determine the access behavior of the door. Visionline door types include guest, guest entrance, guest common, elevator reader, elevator reader relay, and so on.

Note that for common doors, guest entrance doors and elevator reader relays automatically give access to guests within a specific guest door range, such as common entrances. Then, you assign elevator reader relays to the corresponding elevator reader.

For guest common doors, you must grant guest access manually, such as for a gym door or parking entrance.

<Info>
  These instructions use Visionline 1.27. If you are using Visionline 1.28, you
  may notice differences in a few field names.
</Info>

***

## Set up Guest Room Locks

When defining guest room doors, first create a door area and then create a door of the **Guest** door type.

1. Log in to the Visionline application.
2. Set up a door area for guest rooms.
   1. At the bottom of the left navigation pane, click **Lists**.
   2. In the **System setup** section of the left navigation pane, double-click **Door areas**.
   3. In the **Door areas** window, click **Add**.
   4. In the **Door area details** dialog, type a name and, optionally, a description for the new door area.\
      For example, you could create a door area named `Guest Doors`.
   5. Click **Save**.
   6. To add more door areas, click **New** and then repeat this process in the **Door area details** dialog.
   7. When you are done adding door areas, in the **Door area details** dialog, click **Close**.
   8. In the **Door areas** window, click **Close**.
3. Define each set of guest room doors.
   1. At the bottom of the left navigation pane, click **Lists**.
   2. In the **System setup** section of the left navigation pane, double-click **Doors**.
   3. In the **Doors** window, click **Add**.
   4. In the **Door details** window, select **Guest** as the door **Type**.
   5. In the **Number** field, type the door range.\
      For example: `101-109`
   6. In the **Area** field, select the guest door area that you created.\
      For example: **Guest Doors**
   7. Click **Save**.
   8. To add more door sets, click **New** and then repeat this process in the **Door details** window.
   9. When you are done adding door sets, in the **Door details** window, click **Close**.
   10. In the **Doors** window, click **Close**.

***

## Set up Common Door Locks

When defining common doors, make sure to choose the appropriate door type. Visionline door types include the following, among others:

<table>
  <thead>
    <tr>
      <th>Door Type</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Guest entrance</td>

      <td>
        Specify a set of guest doors to give automatic access to guests within
        this range. You can use this door type for common entrances.
      </td>
    </tr>

    <tr>
      <td>Guest common</td>

      <td>
        You must grant access to doors of this type explicitly to specific guest
        credentials. You can use this door type for gym doors, parking
        entrances, and so on.
      </td>
    </tr>

    <tr>
      <td>Elevator reader relay</td>

      <td>
        This door type represents a floor button or relay within an elevator.
        Specify a set of guest doors to give automatic access to guests within
        this range. Assign each elevator reader relay to the corresponding
        "slot" in an elevator reader definition.
      </td>
    </tr>

    <tr>
      <td>Elevator reader</td>

      <td>
        The door type serves as an organization mechanism for sets of elevator
        reader relays.
      </td>
    </tr>
  </tbody>
</table>

<Info>For more information about door types, see the Visionline Help.</Info>

To define a common door, first create a door area and then create a door of the appropriate type.

1. Log in to the Visionline application if you are not already logged in.
2. Set up a door area for the group of common doors.
   1. At the bottom of the left navigation pane, click **Lists**.
   2. In the **System setup** section of the left navigation pane, double-click **Door areas**.
   3. In the **Door areas** window, click **Add**.
   4. In the **Door area details** dialog, type a name and, optionally, a description for the new door area.\
      For example, you could create a door area named `Common Doors`.
   5. Click **Save**.
   6. To add more door areas, click **New** and then repeat this process in the **Door area details** dialog.
   7. When you are done adding door areas, in the **Door area details** dialog, click **Close**.
   8. In the **Door areas** window, click **Close**.
3. Define each common door.
   1. At the bottom of the left navigation pane, click **Lists**.
   2. In the **System setup** section of the left navigation pane, double-click **Doors**.
   3. In the **Doors** window, click **Add**.
   4. In the **Door details** window, select the appropriate door **Type**.\
      See the table at the beginning of this section for descriptions of some common door types.
   5. Type a **Name** for the door, reader, relay, or other entrance.
   6. For a guest entrance door or elevator reader relay, type the beginning and ending room numbers to define the associated **Room interval**.\
      Note that for guest common entrances, you set up access permissions explicitly when creating guest or other credentials.
   7. In the **Area** field, select the common door area that you created.\
      For example: **Common Doors**
   8. For an elevator reader, set the relay outputs to define the access permissions by floor or other output:
      1. In the **Relay outputs** table, select an output.
      2. Click **Select**.
      3. In the **Select elevator reader relay** dialog, select the corresponding elevator reader relay and then click **OK**.
      4. Repeat this process for any additional relay outputs.
   9. Click **Save**.
   10. To add more common doors, click **New** and then repeat this process in the **Door details** window.
   11. When you are done adding common doors, in the **Door details** window, click **Close**.
   12. In the **Doors** window, click **Close**.


# Step 6: Program Door Locks
Source: https://docs.seam.co/device-and-system-integration-guides/assa-abloy-visionline-access-control-system/visionline-acs-setup-instructions/developing-and-launching-your-visionline-plastic-card-encoding-app/developing-your-visionline-plastic-card-encoding-app-using-a-real-visionline-server/step-6-program-door-locks

Learn how to program door locks for your plastic card encoding integration.

Once you have [set up door locks](./step-5-set-up-door-locks) in the Visionline application, use the Lock Service 3G application to program the door locks themselves. When you program a lock, you download the identity and settings for the lock from Lock Service 3G to the lock.

This process consists of the following basic steps:

1. [Install Lock Service 3G on a laptop or tablet.](#install-lock-service-3g)
2. [Configure the Visionline application to download door lock data to Lock Service 3G.](#configure-visionline-for-lock-service-3g)
3. [Configure Lock Service 3G to connect to the Visionline server.](#configure-lock-service-3g-to-connect-to-the-visionline-server)
4. [Download door lock data from the Visionline server to Lock Service 3G.](#download-door-lock-data-to-lock-service-3g)
5. [Initialize each door lock to program it with the correct settings.](#initialize-door-locks)

***

## Install Lock Service 3G

Install the Lock Service 3G on a Windows laptop or tablet that you can move to each door lock. You use an [RJ12 service cable](https://estore.assaabloyglobalsolutions.com/us/marine/service-cable-rj12-for-3g-rfid-lcu-e-cylinder.html) with an [RJ12 to USB adapter cable](https://estore.assaabloyglobalsolutions.com/us/marine/cable-rj12-to-usb-adapter-for-3g.html) to connect this laptop or tablet to each door lock.

<Info>
  If the service cable with adapter cable does not work correctly, you may need to install the following driver:

  `CDM v2.12.xx WHQL Certified.exe`
</Info>

***

## Configure Visionline for Lock Service 3G

1. Log in to the Visionline application if you are not already logged in.
2. Add a device.
   1. At the bottom of the left navigation pane, click **Lists**.
   2. In the **System setup** section of the left navigation pane, double-click **Devices**.
   3. In the **Devices** window, click **Add**.
   4. In the **Device details** window, type a **Name** for the device, such as `Lock Service 3G`.
   5. Select **Service device host** as the device **Type**.
   6. Make sure that the **Port** is `27015`.
   7. Make sure that the **Location** is **Server**.
   8. Click **Save**.
   9. In the **Device details** window, click **Close**.
   10. In the **Devices** window, click **Close**.
3. Obtain the registration code for the Lock Service 3G instance.
   1. At the bottom of the left navigation pane, click **Lists**.
   2. In the **System setup** section of the left navigation pane, double-click **Service devices**.
   3. In the **Service devices** window, click **Add**.
   4. Note the registration code and validity period that the Visionline application displays.\
      You must enter this code in Lock Service 3G on the laptop or tablet.
   5. Click **OK**.
   6. In the **Service devices** window, click **Close**.

***

## Configure Lock Service 3G to Connect to the Visionline Server

1. On the laptop or tablet, open the Lock Service 3G application.

2. Add a server connection.
   1. In the **Setup** section of the left navigation pane, click **Server connections**.
   2. If the **Server connections** dialog does not display automatically, click **Add**.
   3. In the **Server connections** dialog, type a **Name** for this connection to the Visionline server.\
      Note that some of the field names in this dialog are different in different versions of Lock Service 3G.
   4. In the **Address** field, type the IP address of the Visionline server.
   5. Type the **Port** number to use to connect to the Visionline server.
   6. Click **OK**.

3. At the right of the **Lock Service 3G** window, in the lower field in the **Serial port and host** area, select the name of the Visionline server connection that you created.

4. Register Lock Service 3G on the laptop or tablet.

   1. In the **Setup** section of the left navigation pane, click **Register PC**.
   2. In the **Register PC** area, type the registration **Code** that you obtained from the Visionline application.
   3. Click **Register**.

   Lock Service 3G registers with the Visionline server and displays a **Registration Finished** message.

5. Click **OK**.

6. Retrieve the Visionline system ID.

   1. In the **Setup** section of the left navigation pane, click **System ID**.
   2. In the **System ID** area, click **Get**.

   Lock Service 3G retrieves the Visionline system ID and then displays a **New system ID has been set** message.

7. Click **OK**.

***

## Download Door Lock Data to Lock Service 3G

1. Open the Lock Service 3G application if you have not done so already.
2. In the **Setup** section of the left navigation pane, click **Download data from server**.
3. At the right of the **Lock Service 3G** window, in the lower field in the **Serial port and host** area, select the name of the Visionline server connection.
4. In the **Download data from server** area, click **Check all**.
5. Click **Download**.

Lock Service downloads the door lock data from the Visionline server and displays a message when the download is complete.

***

## Initialize Door Locks

Perform the following steps on each lock:

1. Only if necessary, update the Lock Control Unit firmware.\
   **Test locks from ASSA ABLOY should already be preprogrammed with the correct firmware.**\
   For other locks, contact ASSA ABLOY to learn whether you need to update the Lock Control Unit firmware and, if so, to obtain the correct firmware version.
   1. Open the Lock Service 3G application if you have not done so already.
   2. In the **Initiation** section of the left navigation pane, click **Upload firmware**.
   3. At the right of the **Lock Service 3G** window, in the lower field in the **Serial port and host** area, select the name of the Visionline server connection.
   4. In the **Upload firmware** area, click **Browse**.\\
   5. Select the firmware that ASSA ABLOY has sent to you and then click **Open**.
   6. In the **Available versions** table, right-click the appropriate firmware version and select **Save to database**.\\
   7. In the **Available versions** table, select the appropriate firmware version.
   8. At the right of the **Lock Service 3G** window, in the upper field in the **Serial port and host** area, select the serial port that you want to use to connect to the lock.
   9. Connect the service cable with adapter cable from the laptop or tablet running Lock Service 3G to the lock.
   10. At the bottom of the **Upload firmware** area, click **Upload**.
2. Open the Lock Service 3G application if you have not done so already.
3. Initialize the lock.
   1. In the **Initiation** section of the left navigation pane, click **Initialize lock**.
   2. At the right of the **Lock Service 3G** window, in the lower field in the **Serial port and host** area, select the name of the Visionline server connection.
   3. In the **Initialize lock** area, expand the appropriate door area and select the lock that you want to initialize.
   4. Select the **Read parameters after successful initialization** checkbox.
   5. At the right of the **Lock Service 3G** window, in the upper field in the **Serial port and host** area, select the serial port that you want to use to connect to the lock.
   6. Connect the service cable with adapter cable from the laptop or tablet running Lock Service 3G to the lock and then click **Initialize**.


# Step 7: Create a Production Workspace
Source: https://docs.seam.co/device-and-system-integration-guides/assa-abloy-visionline-access-control-system/visionline-acs-setup-instructions/developing-and-launching-your-visionline-plastic-card-encoding-app/developing-your-visionline-plastic-card-encoding-app-using-a-real-visionline-server/step-7-create-a-production-workspace

Learn how to create a production workspace to help you develop and test your Visionline plastic card encoding app.

Create a Seam production workspace to connect your Visionline account to Seam. You can continue to use this workspace in your production phase as well.

1. Log in to [Seam Console](https://console.seam.co/).

2. In the upper-left corner, click the workspace switcher.

   <img alt="Use the Seam Console workspace switcher to switch between workspaces and create new workspaces." />

3. Click **New Workspace**.

4. In the **Add a Workspace** dialog, type a name for your new workspace and your company name.

5. Disable **Sandbox mode**.

   <img alt="To create a production workspace, disable sandbox mode." />

6. Click **Create Workspace**.


# Step 8: Connect Your Visionline Development Account to Seam
Source: https://docs.seam.co/device-and-system-integration-guides/assa-abloy-visionline-access-control-system/visionline-acs-setup-instructions/developing-and-launching-your-visionline-plastic-card-encoding-app/developing-your-visionline-plastic-card-encoding-app-using-a-real-visionline-server/step-8-connect-your-visionline-development-account-to-seam

Learn how to connect your Visionline development account to Seam.

Perform this process for each Visionline site that you want to connect to Seam.

1. In the top navigation pane of [Seam Console](https://console.seam.co/), click **ACS Systems**.

2. On the **Access Systems** page, click **New Access System**.

   Seam Console displays a Connect Webview that enables you to connect your ACS to Seam.

3. In the Connect Webview, click **Continue**.

4. If the Connect Webview displays multiple brand options, click **Visionline**.

5. On the **Set up your Seam Bridge** page, click [**latest Seam Bridge client**](https://www.seam.co/seam-bridge/releases/latest).

   [Seam Bridge](/capability-guides/seam-bridge) is a software-only component that enables you to connect on-premises software systems to the Seam platform. Because Visionline is an on-premises ACS, Seam Bridge is required for Visionline systems.

6. Download the Seam Bridge executable onto the on-premises computer that is running Visionline or onto a computer on the same network.

   For systems requirements, see [Seam Bridge](/capability-guides/seam-bridge).

7. Run the downloaded Seam Bridge app.

8. In the **Welcome to Seam Bridge** window, type a name for the site that you are connecting using Seam Bridge and then click **Start pairing**.

9. Copy the pairing code.

10. In the Connect Webview, click **Continue**.

11. On the **Set up your Seam Bridge** page:
    1. In the **Enter your pairing token** field, paste the pairing code that you copied.
    2. Click **Submit**.

12. On the **Enter your credentials** page:
    1. In the **Visionline Site Name** field, type a name to identify the Visionline site within your Seam workspace.

    2. In the **Username** field, type the username for your Visionline development account.

       This account is the one that you [created or identified in Visionline for the connection with Seam](./step-3-configure-a-visionline-user-account).

    3. In the **Password** field, type the password for your Visionline development account.

    4. If Seam Bridge is not installed on the same computer as Visionline, select **Seam Bridge and Visionline server are installed on different computers** and then type the local IP address of the on-premises computer running Seam Bridge.

    5. Click **Submit**.

13. Click **Close**.


# Developing Your Visionline Plastic Card Encoding App Using a Sandbox Workspace
Source: https://docs.seam.co/device-and-system-integration-guides/assa-abloy-visionline-access-control-system/visionline-acs-setup-instructions/developing-and-launching-your-visionline-plastic-card-encoding-app/developing-your-visionline-plastic-card-encoding-app-using-a-sandbox-workspace/index

Learn how to use Seam's virtual Visionline ACS to develop your Visionline plastic card encoding app.

If you do not have access to an unlicensed Visionline account, you can use a [sandbox workspace](/core-concepts/workspaces#sandbox-workspaces) and Seam-provided virtual Visionline ACS to develop and test your Visionline plastic card encoding app. Seam sandbox workspaces provide test accounts and virtual devices and systems that you can connect and control. Importantly, virtual devices and systems behave identically to the corresponding real devices and systems.

For detailed instructions, see the following topics:

1. [Step 1: Create a Sandbox Workspace](./step-1-create-a-sandbox-workspace)
2. [Step 2: Connect the Virtual Visionline ACS to Seam](./step-2-connect-the-virtual-visionline-acs-to-seam)
3. [Next Steps](./next-steps)


# Next Steps
Source: https://docs.seam.co/device-and-system-integration-guides/assa-abloy-visionline-access-control-system/visionline-acs-setup-instructions/developing-and-launching-your-visionline-plastic-card-encoding-app/developing-your-visionline-plastic-card-encoding-app-using-a-sandbox-workspace/next-steps

After you set up your sandbox workspace and virtual Visionline ACS to develop your plastic card encoding app, learn what's next.

Once you've created a sandbox workspace and added a virtual Visionline ACS, proceed to the following steps:

1. Develop your Visionline plastic card encoding app.
2. Test your app.
3. Launch your app into production.

   For details, see [Launching Your Visionline Plastic Card Encoding App to a Live Site](/device-and-system-integration-guides/assa-abloy-visionline-access-control-system/visionline-acs-setup-instructions/developing-and-launching-your-visionline-plastic-card-encoding-app/launching-your-visionline-plastic-card-encoding-app-to-a-live-site/index).


# Step 1: Create a Sandbox Workspace
Source: https://docs.seam.co/device-and-system-integration-guides/assa-abloy-visionline-access-control-system/visionline-acs-setup-instructions/developing-and-launching-your-visionline-plastic-card-encoding-app/developing-your-visionline-plastic-card-encoding-app-using-a-sandbox-workspace/step-1-create-a-sandbox-workspace

Learn how to create a sandbox workspace to help you develop and test your Visionline plastic card encoding app.

The first step in developing and testing your Visionline plastic card encoding app using a sandbox workspace and Seam-provided virtual Visionline ACS is to create the sandbox workspace.

1. Log in to [Seam Console](https://console.seam.co/).

2. In the upper-left corner, click the workspace switcher.

   <img alt="Use the Seam Console workspace switcher to switch between workspaces and create new workspaces." />

3. Click **New Workspace**.

4. In the **Add a Workspace** dialog, type a name for your new workspace and your company name.

5. Enable **Sandbox mode**.

6. Click **Create Workspace**.


# Step 2: Connect the Virtual Visionline ACS to Seam
Source: https://docs.seam.co/device-and-system-integration-guides/assa-abloy-visionline-access-control-system/visionline-acs-setup-instructions/developing-and-launching-your-visionline-plastic-card-encoding-app/developing-your-visionline-plastic-card-encoding-app-using-a-sandbox-workspace/step-2-connect-the-virtual-visionline-acs-to-seam

Learn how to connect a virtual Visionline ACS to Seam to help you develop and test your Visionline plastic card encoding app.

Once you've created a sandbox workspace, add a virtual Visionline ACS to start developing your Visionline plastic card encoding app.

1. In the top navigation pane of [Seam Console](https://console.seam.co/), click **ACS Systems**.

2. On the **Access Systems** page, click **New Access System**.

   Seam Console displays a Connect Webview that enables you to connect a virtual ACS to Seam.

3. In the Connect Webview, authorize the connection.
   1. Click **Continue**.

   2. If the Connect Webview displays multiple brand options, click **Visionline**.

   3. On the **Set up your Seam Bridge** page, click **Continue**.

      [Seam Bridge](/capability-guides/seam-bridge) is a software-only component that enables you to connect on-premises software systems to the Seam platform. Because Visionline is an on-premises ACS, Seam Bridge is required for real Visionline systems. However, this option uses a virtual Visionline ACS, so you do not need to install Seam Bridge.

   4. On the **Set up your Seam Bridge** page, click **Submit**.

   5. On the **Enter your credentials** page:
      1. In the **Visionline Site Name** field, type any string to identify this virtual Visionline ACS site, for example, `My Visionline Site`.
      2. In the **Username** field, type `jane`.
      3. In the **Password** field, type `1234`.
      4. Click **Submit**.

   6. Click **Close**.

The **Access Systems** page now displays the newly-connected virtual Visionline access control system.


# Developing and Launching Your Visionline Plastic Card Encoding App
Source: https://docs.seam.co/device-and-system-integration-guides/assa-abloy-visionline-access-control-system/visionline-acs-setup-instructions/developing-and-launching-your-visionline-plastic-card-encoding-app/index

Learn how to develop and then launch your Visionline plastic card encoding integration.

You can use your own Visionline development account—that is, an unlicensed Visionline account—to develop your Visionline plastic card encoding app. If you do not have access to a Visionline development account, you can use a Seam sandbox workspace instead. Once you have developed and tested your app, launch it into production.

See the following instructions:

## Step 1: Development Phase

* [Developing Your Visionline Plastic Card Encoding App Using A Real Visionline Server](/device-and-system-integration-guides/assa-abloy-visionline-access-control-system/visionline-acs-setup-instructions/developing-and-launching-your-visionline-plastic-card-encoding-app/developing-your-visionline-plastic-card-encoding-app-using-a-real-visionline-server/index)
* [Developing Your Visionline Plastic Card Encoding App Using a Sandbox Workspace](/device-and-system-integration-guides/assa-abloy-visionline-access-control-system/visionline-acs-setup-instructions/developing-and-launching-your-visionline-plastic-card-encoding-app/developing-your-visionline-plastic-card-encoding-app-using-a-sandbox-workspace/index)

## Step 2: Launch Phase

* [Launching Your Visionline Plastic Card Encoding App](/device-and-system-integration-guides/assa-abloy-visionline-access-control-system/visionline-acs-setup-instructions/developing-and-launching-your-visionline-plastic-card-encoding-app/launching-your-visionline-plastic-card-encoding-app-to-a-live-site/index)


# Launching Your Visionline Plastic Card Encoding App to a Live Site
Source: https://docs.seam.co/device-and-system-integration-guides/assa-abloy-visionline-access-control-system/visionline-acs-setup-instructions/developing-and-launching-your-visionline-plastic-card-encoding-app/launching-your-visionline-plastic-card-encoding-app-to-a-live-site/index

Learn how to launch your Visionline plastic card encoding app into production.

Once you have developed and tested your Visionline plastic card encoding app, you can launch your app into production using an existing live Visionline site. The instructions in this section assume that your live site already has Visionline card encoders installed and that all door locks are already set up and programmed to work with cards.&#x20;

For detailed instructions, see the following topics:

[Step 1: Confirm That Your Visionline Site Meets the Requirements](./step-1-confirm-that-your-visionline-site-meets-the-requirements)

[Step 2: Configure a Visionline User Account](./step-2-configure-a-visionline-user-account)

[Step 3: Purchase and Import the Callback Option from ASSA ABLOY](./step-3-purchase-and-import-the-callback-option-from-assa-abloy)

[Step 4: Create a Production Workspace](./step-4-create-a-production-workspace)

<Info>
  Skip this step if you have already created a production workspace during the
  development phase and want to use this workspace to launch your app.
</Info>

[Step 5: Connect Your Visionline Production Account to Seam](../../../../assa-abloy-visionline-access-control-system/visionline-acs-setup-instructions/developing-and-launching-your-visionline-plastic-card-encoding-app/launching-your-visionline-plastic-card-encoding-app-to-a-live-site/step-5-connect-your-visionline-production-account-to-seam)


# Step 1: Confirm That Your Visionline Site Meets the Requirements
Source: https://docs.seam.co/device-and-system-integration-guides/assa-abloy-visionline-access-control-system/visionline-acs-setup-instructions/developing-and-launching-your-visionline-plastic-card-encoding-app/launching-your-visionline-plastic-card-encoding-app-to-a-live-site/step-1-confirm-that-your-visionline-site-meets-the-requirements

Learn the system and port requirements that your production Visionline site must meet.

Confirm that your production Visionline site meets the following system and port requirements:

## System Requirements

Make sure that your computer meets the following requirements:

* Key server:
  * Visionline V1.27 (or newer)
  * Windows 10 1901 (or newer)
  * Hosted in a location where internet traffic is allowed

***

## Port Requirements

Make sure that the following ports are unblocked on the Visionline server and client:

### Server Ports

* All files in the Visionline `Program Files` and `ProgramData` folders\
  The default locations are `C:\Program Files\ASSA ABLOY\Visionline` and `C:\ProgramData\ASSA ABLOY\Visionline`.
* Firewall ports:
  * Port 135 (TCP)
  * 3001 (TCP)
  * 7799, 7788 (TCP/UDP)
  * Lock Service Port (27015 default) (TCP)
  * PMS port (4000 default) (TCP)

### Client Ports

* All files in the Visionline `Program Files` and `ProgramData` folders\
  The default locations are `C:\Program Files\ASSA ABLOY\Visionline` and `C:\ProgramData\ASSA ABLOY\Visionline`.
* Firewall ports
  * Port 135 (TCP)
  * 3001 (TCP)
  * DCOM ports

***

## For More Information

See the following ASSA ABLOY Visionline document:


# Step 2: Configure a Visionline User Account
Source: https://docs.seam.co/device-and-system-integration-guides/assa-abloy-visionline-access-control-system/visionline-acs-setup-instructions/developing-and-launching-your-visionline-plastic-card-encoding-app/launching-your-visionline-plastic-card-encoding-app-to-a-live-site/step-2-configure-a-visionline-user-account

Learn how to set up a Visionline user account to integrate with Seam.

Make sure that your Visionline application is configured with an appropriate user account. You use this account to connect the Visionline instance with Seam. You can use the default `sym` username and password.

Alternately, the Visionline ACS administrator can create a Visionline user specifically for the connection with Seam. This user must be configured as an operator that uses the System Manager operator template. This user must also have a password.

To create a new Visionline user for the Seam connection, first create a new user. Then, configure the user as an operator that uses the System Manager operator template.

<Info>
  These instructions use Visionline 1.27. If you are using Visionline 1.28, you
  may notice differences in a few field names.
</Info>

1. Log in to the Visionline application as a user with System Manager access.
2. Create a new Visionline user.
   1. At the bottom of the left navigation pane, click **Lists**.
   2. In the **System administration** section of the left navigation pane, double-click **Users**.
   3. In the **Users** window, click **Add**.
   4. In the **User details** window, type a **User ID** for the new user, for example, `Seam Integration`.
   5. Type the **Last name** of the user, for example, `Integration`.
   6. Type the **First name** of the user, for example, `Seam`.
   7. Select the **User group** to which to assign the user.
   8. Optionally, in the **PIN** field, type a PIN for the user.
   9. If you've added a PIN, in the **Confirm PIN** field, type the same PIN for the user.
   10. Click **Save**.
   11. In the **User details** dialog, click **Close**.
   12. In the **Users** window, click **Close**.
3. Configure the new user as an operator that uses the System Manager operator template.
   1. At the bottom of the left navigation pane, click **Lists**.
   2. In the **System access** section of the left navigation pane, double-click **Operators**.
   3. In the **Operators** window, click **Add**.
   4. In the **Operator details** dialog, click **...** next to the **User name** field.
   5. In the **Users \<Operator details>** window, select the user that you created and then click **Select**.
   6. In the **Operator details** dialog, select **System Manager** as the **Operator template**.\
      Alternately, you can create a new operator template for the new user, but you must make sure that this operator template has access to all permissions.
   7. In the **Password** and **Confirm Password** fields, type a password for the user.
   8. Click **Save**.
   9. In the **Operator details** dialog, click **Close**.
   10. In the **Operators** window, click **Close**.
4. Note the username and password for this Visionline user. You must use these credentials when you [connect your Visionline account to Seam](./step-5-connect-your-visionline-production-account-to-seam).


# Step 3: Purchase and Import the Callback Option from ASSA ABLOY
Source: https://docs.seam.co/device-and-system-integration-guides/assa-abloy-visionline-access-control-system/visionline-acs-setup-instructions/developing-and-launching-your-visionline-plastic-card-encoding-app/launching-your-visionline-plastic-card-encoding-app-to-a-live-site/step-3-purchase-and-import-the-callback-option-from-assa-abloy

Learn about the Callback option that you need to purchase from ASSA ABLOY and import into Visionline.

To launch your Visionline plastic card encoding app into production, you must purchase the Callback option from ASSA ABLOY and then import this option into Visionline.

1. Purchase the Callback option from ASSA ABLOY.

   To purchase this option, contact ASSA ABLOY.

   Once you purchase the Callback option, ASSA ABLOY provides you with a corresponding option code.

2. Import the corresponding option code into Visionline.
   1. Open Visionline.
   2. In the top menu, click **Tools** > **Option code**.
   3. In the **Option code** field, type or paste the option code that you received from Visionline and then click **Apply**.

3. Verify that the required option has been configured.
   1. At the bottom of the Visionline left navigation pane, click **Reports**.
   2. In the **Pre-defined** section of the left navigation pane, double-click **System settings**.
   3. If desired, print or export the report.
   4. In the report, find the **`[Options]`** section and verify that the purchased option is listed.


# Step 4: Create a Production Workspace
Source: https://docs.seam.co/device-and-system-integration-guides/assa-abloy-visionline-access-control-system/visionline-acs-setup-instructions/developing-and-launching-your-visionline-plastic-card-encoding-app/launching-your-visionline-plastic-card-encoding-app-to-a-live-site/step-4-create-a-production-workspace

Learn how to create a production workspace for your production Visionline plastic card encoding app.

If you did not create a Seam production workspace during the development phase for your Visionline plastic card encoding app, you must create a new production workspace to connect your Visionline production account to Seam. If you did create a production workspace already, you can choose to continue using this workspace or to create a new one.

To create a production workspace.

1. Log in to [Seam Console](https://console.seam.co/).

2. In the upper-left corner, click the workspace switcher.

   <img alt="Use the Seam Console workspace switcher to switch between workspaces and create new workspaces." />

3. Click **New Workspace**.

4. In the **Add a Workspace** dialog, type a name for your new workspace and your company name.

5. Disable **Sandbox mode**.

   <img alt="To create a production workspace, disable sandbox mode." />

6. Click **Create Workspace**.


# Step 5: Connect Your Visionline Production Account to Seam
Source: https://docs.seam.co/device-and-system-integration-guides/assa-abloy-visionline-access-control-system/visionline-acs-setup-instructions/developing-and-launching-your-visionline-plastic-card-encoding-app/launching-your-visionline-plastic-card-encoding-app-to-a-live-site/step-5-connect-your-visionline-production-account-to-seam

Learn how to connect your Visionline production account to Seam.

Perform this process for each Visionline site that you want to connect to Seam.

<Info>
  If you already connected your Visionline ACS to Seam during the development
  phase—using your Visionline development account—you must now reconnect
  Visionline to Seam using your production Visionline credentials.
</Info>

1. In the top navigation pane of [Seam Console](https://console.seam.co/), click **ACS Systems**.

2. On the **Access Systems** page, click **New Access System**.

   Seam Console displays a Connect Webview that enables you to connect your ACS to Seam.

3. In the Connect Webview, click **Continue**.

4. If the Connect Webview displays multiple brand options, click **Visionline**.

5. On the **Set up your Seam Bridge** page, click [**latest Seam Bridge client**](https://www.seam.co/seam-bridge/releases/latest).

   [Seam Bridge](/capability-guides/seam-bridge) is a software-only component that enables you to connect on-premises software systems to the Seam platform. Because Visionline is an on-premises ACS, Seam Bridge is required for Visionline systems.

6. Download the Seam Bridge executable onto the on-premises computer that is running Visionline or onto a computer on the same network.

   For systems requirements, see [Seam Bridge](/capability-guides/seam-bridge).

7.

8. Run the downloaded Seam Bridge app.

9. In the **Welcome to Seam Bridge** window, type a name for the site that you are connecting using Seam Bridge and then click **Start pairing**.

10. Copy the pairing code.

11. In the Connect Webview, click **Continue**.

12. On the **Set up your Seam Bridge** page:
    1. In the **Enter your pairing token** field, paste the pairing code that you copied.
    2. Click **Submit**.

13. On the **Enter your credentials** page:
    1. In the **Visionline Site Name** field, type a name to identify the Visionline site within your Seam workspace.

    2. In the **Username** field, type the username for your Visionline production account.

       This account is the one that you [created or identified in Visionline for the connection with Seam](./step-2-configure-a-visionline-user-account).

    3. In the **Password** field, type the password for your Visionline production account.

    4. If Seam Bridge is not installed on the same computer as Visionline, select **Seam Bridge and Visionline server are installed on different computers** and then type the local IP address of the on-premises computer running Seam Bridge.

    5. Click **Submit**.

14. Click **Close**.


# Visionline ACS Setup Instructions
Source: https://docs.seam.co/device-and-system-integration-guides/assa-abloy-visionline-access-control-system/visionline-acs-setup-instructions/index

Learn how to configure your Visionline ACS for integration with Seam.

Seam's Visionline ACS integration enables you to create the following two types of applications:

* Apps that issue and encode Visionline plastic cards
* Mobile apps that issue Visionline mobile keys

<Info>
  For information about Seam mobile keys, see [Mobile
  Access](/capability-guides/mobile-access).
</Info>

Integrating Visionline with Seam consists of a development phase and a production phase. The setup processes and requirements differ between these two phases.

This topic provides the following process overviews with links to complete instructions:

* [Developing and Launching a Plastic Card Encoding Solution](#developing-and-launching-a-plastic-card-encoding-solution)
  * [Develop a Plastic Card Encoding App Using a Real Visionline Server](#develop-a-plastic-card-encoding-app-using-a-real-visionline-server)
  * [Develop a Plastic Card Encoding App Using a Sandbox Workspace](#develop-a-plastic-card-encoding-app-using-a-sandbox-workspace)
  * [Launch Your Visionline Plastic Card Encoding App](#launch-your-visionline-plastic-card-encoding-app-to-a-live-visionline-system)
* [Developing and Launching a Mobile Key Solution](#developing-and-launching-a-mobile-key-solution)
  * [Develop Your Visionline Mobile Key App](#develop-your-visionline-mobile-key-app)
  * [Launch Your Visionline Mobile Key App](#launch-your-visionline-mobile-key-app)

***

## Developing and Launching a Plastic Card Encoding Solution

The following sections describe the major steps of the setup process for developing and launching a plastic card encoding solution:

### Develop a Plastic Card Encoding App Using a Real Visionline Server

1. Install your Visionline application using your development account.

   Contact Seam at [support@seam.co](mailto:support@seam.co) to obtain access.

2. Configure Visionline and set it up to work with plastic cards.
   1. Unblock the required ports.
   2. Make sure that Visionline is configured with an appropriate user account.
   3. Buy and install a [Visionline card encoder](https://estore.assaabloyglobalsolutions.com/no/marine/rfid-encoder-updater-complete.html) and then connect it to your Visionline server.
   4. Set up all door locks.
   5. Use Lock Service 3G to program the door locks.

3. Create a Seam production workspace.

   You can continue to use this workspace in your production phase as well.

4. Connect your Visionline development account to Seam.

   This step includes installing and running Seam Bridge to connect your on-premises Visionline application to Seam.

For detailed instructions, see [Developing Your Visionline Plastic Card Encoding App Using a Real Visionline Server](/device-and-system-integration-guides/assa-abloy-visionline-access-control-system/visionline-acs-setup-instructions/developing-and-launching-your-visionline-plastic-card-encoding-app/developing-your-visionline-plastic-card-encoding-app-using-a-real-visionline-server/index).

***

### Develop a Plastic Card Encoding App Using a Sandbox Workspace

1. Create a sandbox workspace.\
   A sandbox workspace enables you to develop and test your app using Seam-provided virtual systems and devices.
2. Connect the virtual Visionline ACS to Seam.

For detailed instructions, see [Developing Your Visionline Plastic Card Encoding App Using a Sandbox Workspace](/device-and-system-integration-guides/assa-abloy-visionline-access-control-system/visionline-acs-setup-instructions/developing-and-launching-your-visionline-plastic-card-encoding-app/developing-your-visionline-plastic-card-encoding-app-using-a-sandbox-workspace/index).

***

### Launch Your Visionline Plastic Card Encoding App to a Live Visionline System

1. Confirm that your production Visionline site meets the system requirements.
2. Make sure that Visionline is configured with an appropriate user account.
3. Purchase the required Callback option from ASSA ABLOY and import it into Visionline.
4. Connect your Visionline production account to Seam.

   Either create a new production workspace or use your existing production workspace.\
   This step also includes installing Seam Bridge.

For detailed instructions, see [Launching Your Visionline Plastic Card Encoding App](/device-and-system-integration-guides/assa-abloy-visionline-access-control-system/visionline-acs-setup-instructions/developing-and-launching-your-visionline-plastic-card-encoding-app/launching-your-visionline-plastic-card-encoding-app-to-a-live-site/index).

***

## Developing and Launching a Mobile Key Solution

The following sections describe the major steps of the setup process for developing and launching a mobile key solution:

### Develop Your Visionline Mobile Key App

1. Sign up for and complete the ASSA ABLOY mobile development course.

2. Install your Visionline app.

3. Configure Visionline using your development account.
   1. Unblock the required ports.
   2. Make sure that Visionline is configured with an appropriate user account.
   3. Set up your Credential Services account in the Visionline application.
   4. Configure the mobile access UUID in the Visionline application.
   5. Set up all door locks with Bluetooth low energy (BLE) profiles.
   6. Use Lock Service 3G to program the door locks.

4. Create a Seam production workspace.

   You can continue to use this workspace in your production phase as well.

5. Connect your Visionline site to Seam using your Visionline development account.

   This step includes installing and running Seam Bridge to connect your on-premises Visionline application to Seam.

   1. Also, add your Visionline development application ID in Seam Console.

For detailed instructions, see [Developing Your Visionline Mobile Key App](/device-and-system-integration-guides/assa-abloy-visionline-access-control-system/visionline-acs-setup-instructions/developing-and-launching-your-visionline-mobile-key-app/developing-your-visionline-mobile-key-app/index).

***

### Launch Your Visionline Mobile Key App

1. Pass the ASSA ABLOY certification process.
2. Confirm that your production Visionline site meets the system requirements.
3. Configure all door locks for use with mobile keys.

<Info>
  This process can be quite time-consuming because it requires interaction
  with all locks.
</Info>

1. Make sure that the BLE module is installed on all locks.

2. Set up all door locks with BLE profiles.

3. Use Lock Service 3G to program all locks.

4. Configure Visionline using your production account.

5. Make sure that Visionline is configured with an appropriate user account.

6. Purchase the following required options from ASSA ABLOY and import them into Visionline:
   * Callback options
   * Mobile Service option with your tenant account

7. Connect your Visionline production instance to Seam.

   Either create a new production workspace or use your existing production workspace.

   This step also includes installing Seam Bridge and adding your Visionline application ID in your workspace.

For detailed instructions, see [Launching Your Visionline Mobile Key App](/device-and-system-integration-guides/assa-abloy-visionline-access-control-system/visionline-acs-setup-instructions/developing-and-launching-your-visionline-mobile-key-app/launching-your-visionline-mobile-key-app/index).


# Instructions for issuing Visionline Instant Keys
Source: https://docs.seam.co/device-and-system-integration-guides/assa-abloy-visionline-access-control-system/visionline-acs-setup-instructions/instructions-for-issuing-visionline-instant-keys

To use mobile keys with your access system, you may need to purchase licenses or subscriptions to activate certain software features. These features vary by access system.

## System Requirements for Visionline Instant Keys

To use Instant Keys with Visionline, please reach out to your local installer to purchase the following from Assa Abloy:

* A mobile key license linked to Seam's Assa Abloy tenant account: `SeamLabs-tenant.` Provide this account username when completing your purchase.
* A web services option code.

After you have purchased the items above from Assa Abloy, please reach out to Seam at [support@seam.co](mailto:support@seam.co). Include the Seam workspace ID you'll be using, so we can help finish setting up your workspace for Visionline Instant Keys.


# ASSA ABLOY Vostio Access Control System
Source: https://docs.seam.co/device-and-system-integration-guides/assa-abloy-vostio-access-control-system/index

Guide for using the ASSA ABLOY Vostio access control system with Seam

<img alt="Vostio logo" />

## Overview

ASSA ABLOY Vostio is a cloud-based access control system designed for the hospitality industry. It manages electronic door locks, encoders, and room access across hotel properties. Seam integrates with Vostio to provide entrance management, credential provisioning (mobile keys and physical cards), and card encoding through a unified API.

***

## Supported Devices

<DeviceList />

This integration supports all electronic door locks and encoders connected to a Vostio system. Vostio manages four types of entrances:

* **Guest doors** — individual hotel room doors
* **Common doors** — shared spaces such as lobbies, gyms, and pools
* **Entrance doors** — building entry points
* **Elevators** — elevator floor access

For detailed information about the ASSA ABLOY Vostio devices that Seam supports, see our [ASSA ABLOY Vostio Supported Devices page](https://www.seam.co/manufacturers/assa_abloy_vostio).

***

## Supported Features

We support the following features:

* Managing ACS users (guests and staff)
* Listing and managing entrances (guest doors, common doors, entrance doors, elevators)
* Creating and revoking credentials (mobile keys and physical cards)
* Encoding plastic cards via connected encoders

***

## Related Features

* [**Access Grants**](/use-cases/granting-access) — The recommended way to manage access in Seam. Integrate once, and your access model works consistently across all providers, including Vostio.
* [**Plastic Card Encoding**](/api/acs/encoders/encode_credential) — Encode and issue physical key cards using Seam's card management API.

***

## Device Provider Key

Seam identifies these devices with the `assa_abloy_vostio` device provider key. By default, a [Connect Webview](/core-concepts/connect-webviews) displays all of the stable providers that Seam supports, so your users can connect their Vostio system without you specifying a provider list. To narrow what a Connect Webview displays, see [Customize the Brands to Display in Your Connect Webviews](/core-concepts/connect-webviews/customizing-connect-webviews#customize-the-brands-to-display-in-your-connect-webviews).

***

## Setup Instructions

For step-by-step instructions on connecting a Vostio system to Seam, see the [Vostio Setup Guide](./vostio-setup-guide).

***

## Where to Order

<CardGroup>
  <Card title="ASSA ABLOY - Vostio" href="https://www.assaabloy.com/group/solutions/products/categories/access-management-systems/vostio" />
</CardGroup>


# Sandbox Assa Abloy Vostio Access Control System
Source: https://docs.seam.co/device-and-system-integration-guides/assa-abloy-vostio-access-control-system/sandbox-assa-abloy-vostio-access-control-system

Add virtual ASSA ABLOY Vostio access control system devices to your Seam sandbox workspace using these sample credentials to test your integration.

Use the following set of credentials to add virtual Assa Abloy Vingcard Vostio locks to your Seam [sandbox workspace](/core-concepts/workspaces#sandbox-workspaces):

<Info>
  To use the virtual Visionline Access Control System (ACS) to issue mobile keys
  in a sandbox workspace, you must also connect the [virtual ASSA ABLOY
  Credential
  Services](/device-and-system-integration-guides/assa-abloy-vingcard-credential-services).
</Info>

## Vostio Credentials

| Field        | Value                                                                    |
| ------------ | ------------------------------------------------------------------------ |
| System Name  | Any string to identify this Vostio ACS site, for example, My Vostio Site |
| Username     | `jane`                                                                   |
| Password     | `1234`                                                                   |
| Client ID    | `1234`                                                                   |
| User Pool ID | `1234`                                                                   |

## Mobile Key Information

If you plan to create mobile keys, select the **Mobile Keys will be issued in this system** field and specify the following information:

| Field     | Value |
| --------- | ----- |
| BLE UUID  | 1     |
| System ID | 1     |


# Vostio Setup Guide
Source: https://docs.seam.co/device-and-system-integration-guides/assa-abloy-vostio-access-control-system/vostio-setup-guide

Connect your ASSA ABLOY Vostio system to Seam.

## Overview

This guide walks you through connecting your ASSA ABLOY Vostio access control system to Seam. Your Vostio system must already be configured and operational before proceeding.

***

## Step 1: Create Your Vostio API Credentials

1. Log in to the Vostio dashboard.
2. In the left sidebar, click **Settings**, then select **Integrations**.
3. On the **Guest API** tab, click **Create credentials**.
4. Enter a name for the credentials and click **Create credentials**.
5. Click **Download credentials** to save the generated credentials file. Store this file securely — if you lose it, you cannot retrieve the credentials. You would need to create new credentials and delete the old ones.

***

## Step 2: Connect to Seam via Connect Webview

1. Open the [Connect Webview](/core-concepts/connect-webviews) provided by your application.
2. Select **Vingcard Vostio** as the provider.
3. Enter the **username**, **password**, **user pool ID**, and **client ID** from the downloaded credentials file.
4. Once authorized, your Vostio system, entrances, and encoders appear in Seam.

***

## Step 3: Verify the Connection

After connecting, verify that your Vostio ACS system shows as connected, your entrances (guest doors, common doors, entrance doors, elevators) appear, and your encoders are listed.

***

## Troubleshooting

### Authorization fails in Connect Webview

Verify that you are using the correct Vostio Guest API credentials. If you have lost your credentials, log in to the Vostio dashboard and create new ones under **Settings > Integrations > Guest API**.

### Entrances not appearing after authorization

Ensure your Vostio system has doors and rooms configured. Only entrances that are active in the Vostio system appear in Seam.

### Encoder not found

Confirm that your card encoders are registered and active in the Vostio system. Inactive encoders do not appear in Seam.


# Sandbox August Locks
Source: https://docs.seam.co/device-and-system-integration-guides/august-locks/august-locks-sample-data

Add virtual August locks to your Seam sandbox workspace using these sample credentials to test your integration without real hardware.

Use any of the following sets of credentials to add virtual [August locks](/device-and-system-integration-guides/august-locks) to your Seam [sandbox workspace](/core-concepts/workspaces#sandbox-workspaces):

<table>
  <thead>
    <tr>
      <th>Device Region</th>
      <th>Email Address</th>
      <th>Password</th>
      <th>Two Factor or Verification Code</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>North America or Others</td>
      <td>[jane@example.com](mailto:jane@example.com)</td>
      <td>1234</td>
      <td>123456</td>
    </tr>

    <tr>
      <td>North America or Others</td>
      <td>[john@example.com](mailto:john@example.com)</td>
      <td>1234</td>
      <td>123456</td>
    </tr>

    <tr>
      <td>North America or Others</td>
      <td>[sam@example.com](mailto:sam@example.com)</td>
      <td>1234</td>
      <td>123456</td>
    </tr>

    <tr>
      <td>North America or Others</td>
      <td>[frodo@example.com](mailto:frodo@example.com)</td>
      <td>1234</td>
      <td>123456</td>
    </tr>
  </tbody>
</table>

<Info>
  For the "Others" device region, when prompted, select **Email** as the
  two-factor authentication (2FA) method. The Connect Webview automatically
  inserts the email address that you specified previously.
</Info>


# August Setup Guide
Source: https://docs.seam.co/device-and-system-integration-guides/august-locks/august-setup-guide

Connect your August locks to Seam.

## Overview

This guide walks you through connecting your August smart locks to Seam. Your locks must already be physically installed and working before proceeding.

***

## Step 1: Set Up the August Home App

1. Download the [August Home App](https://august.com/pages/app) and create an account if you don't have one.
2. In the August Home App, add your August devices.

***

## Step 2: Connect to Seam

Use your login credentials for the August Home App to log in to the [Connect Webview](/core-concepts/connect-webviews) to add your August devices to Seam.

***

## Step 3: Verify the Connection

After connecting, verify that your August devices appear in your Seam workspace and that each device shows an **online** status.

***

## Troubleshooting

### Devices not appearing after connecting

* Verify that your August devices are added and online in the August Home App.
* If your lock requires the August Connect Wi-Fi Bridge, confirm the bridge is plugged in and connected.

### Lock shows as offline

* Check that the lock has a working Wi-Fi connection, either through built-in Wi-Fi or the August Connect Wi-Fi Bridge.
* Open the August Home App and verify the lock status.


# Get started with August locks
Source: https://docs.seam.co/device-and-system-integration-guides/august-locks/get-started-with-august-locks

Learn how to connect and control August locks with the Seam API.

<picture>
  <source />

  <img alt="August smart locks" />
</picture>

## Overview

Seam provides a universal API to connect and control many brands of IoT devices and systems, including smart locks, access control systems (ACSs), thermostats, and noise sensors.

This guide gives you a rapid introduction to connecting and controlling your [August lock](/device-and-system-integration-guides/august-locks) using the Seam API. For application developers, you can use the Seam API in your app, and your users can authorize your app to control their devices using Seam.

For detailed information about the August devices that Seam supports, see our [August Supported Devices page](https://www.seam.co/manufacturers/august).

To learn more about other IoT device and system brands that Seam supports—such as Yale, Schlage, Google Nest, and many more—visit our [integration page](https://www.seam.co/supported-devices-and-systems).

<Check>
  This guide shows you how to install a Seam SDK and then control your August lock using the Seam API.

  Another easy way to learn about what you can do with the Seam API is to explore the [interactive Seam CLI](/core-concepts/seam-console/seam-online-cli), which you can access from directly within the [Seam Console](/core-concepts/seam-console).

  :arrow\_forward: [Go to the Seam Console!](https://console.seam.co/)
</Check>

***

## Step 1: Install a Seam SDK

Seam provides client libraries for many languages, including JavaScript, Python, Ruby, PHP, and others, as well as a Postman collection and an [OpenAPI](https://connect.getseam.com/openapi.json) spec.

* JavaScript / TypeScript ([npm](https://www.npmjs.com/package/seam), [GitHub](https://github.com/seamapi/javascript))
* Python ([pip](https://pypi.org/project/seam/), [GitHub](https://github.com/seamapi/python))
* Ruby Gem ([rubygem](https://rubygems.org/gems/seam), [GitHub](https://github.com/seamapi/ruby))
* PHP ([packagist](https://packagist.org/packages/seamapi/seam), [GitHub](https://github.com/seamapi/php))
* C# ([nuget](https://www.nuget.org/packages/Seam), [GitHub](https://github.com/seamapi/csharp))

First, install a Seam SDK, as follows:

<Tabs>
  <Tab title="JavaScript">
    ```bash theme={null}
    npm i seam
    ```
  </Tab>

  <Tab title="Python">
    ```bash theme={null}
    pip install seam
    # For some development environments, use pip3 in this command instead of pip.
    ```
  </Tab>

  <Tab title="Ruby">
    ```bash theme={null}
    bundle add seam
    ```
  </Tab>

  <Tab title="PHP">
    ```bash theme={null}
    composer require seamapi/seam
    ```
  </Tab>

  <Tab title="C#">
    Install using [nuget](https://www.nuget.org/packages/Seam).
  </Tab>
</Tabs>

Next, go to [https://console.seam.co/](https://console.seam.co/) and [sign up for Seam](/core-concepts/seam-console#create-a-seam-account) to get your [API key](/core-concepts/authentication/api-keys).

Then, export your API key as an environment variable.

```bash theme={null}
$ export SEAM_API_KEY=seam_test2bMS_94SrGUXuNR2JmJkjtvBQDg5c
```

<Info>
  This guide uses a [sandbox
  workspace](/core-concepts/workspaces#sandbox-workspaces).
  You can only connect virtual devices and systems in this type of workspace. If
  you want to connect a real August lock, use a [non-sandbox
  workspace](/core-concepts/workspaces#production-workspaces)
  and API key.
</Info>

***

## Step 2: Link your August account with Seam

To control your August lock using the Seam API, you must first authorize your Seam workspace to connect to your August account. If your application needs to connect to your users' August accounts, Seam provides fully-embedded, [customizable](/core-concepts/connect-webviews/customizing-connect-webviews) client-side [Connect Webviews](/core-concepts/connect-webviews) to collect their authorization securely. These user-friendly pre-built authorization flows walk your users through the process of granting your Seam workspace permission to control their August locks. The Connect Webview presents a flow that prompts your users to enter their credentials for their August account.

In this guide, you create a Connect Webview object. Then, you display the graphical component of the created Connect Webview and enter a set of sample credentials to connect a sandbox August account.

<Check>
  This guide shows you how to create a Connect Webview programmatically using the Seam API.

  The [Seam Console](/core-concepts/seam-console) provides another easy way to connect devices to your Seam workspace.

  Go to [https://console.seam.co/](https://console.seam.co/). On the **Devices** page, click **+ Add Devices**. Then, see [Authorize your workspace](#authorize-your-workspace) in this guide to complete the Connect Webview authorization flow.

  <img alt="You can also use the Seam Console to add devices." />
</Check>

### Create a Connect Webview

Create a `connect_webview` object and then note the returned URL.

**Code:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  import { Seam } from 'seam'

  const seam = new Seam() // Seam automatically uses your exported SEAM_API_KEY.

  const connectWebview = await seam.connectWebviews.create()

  console.log(connectWebview.login_successful) // false

  // Use the returned Connect Webview URL to display
  // the Connect Webview authorization flow to your user.
  console.log(connectWebview.url)
  ```

  ```bash cURL theme={null}
  curl -X 'POST' \
    'https://connect.getseam.com/connect_webviews/create' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d '{}' | jq -r '"Login Successful (false): " + (.connect_webview.login_successful | tostring),
    "URL: " + .connect_webview.url'
    # Use the returned Connect Webview URL to display
    # the Connect Webview authorization flow to your user.
  ```

  ```python Python theme={null}
  from seam import Seam

  seam = Seam()  # Seam automatically uses your exported SEAM_API_KEY.

  connect_webview = seam.connect_webviews.create()

  assert connect_webview.login_successful is False

  # Use the returned Connect Webview URL to display
  # the Connect Webview authorization flow to your user.
  print(connect_webview.url)
  ```

  ```ruby Ruby theme={null}
  require "seam"

  seam = Seam.new() # Seam automatically uses your exported SEAM_API_KEY.

  connect_webview = seam.connect_webviews.create()

  puts connect_webview.login_successful # false

  # Use the returned Connect Webview URL to display
  # the Connect Webview authorization flow to your user.
  puts connect_webview.url
  ```

  ```php PHP theme={null}
  <?php
  require 'vendor/autoload.php';

  $seam = new Seam\SeamClient(); // Seam automatically uses your exported SEAM_API_KEY.

  $connect_webview = $seam->connect_webviews->create();

  echo $connect_webview->login_successful ? 'true' : 'false', "\n"; // false

  // Use the returned Connect Webview URL to display
  // the Connect Webview authorization flow to your user.
  echo $connect_webview->url;
  ```

  ```csharp C# theme={null}
  using Seam.Client;

  var seam = new SeamClient(apiToken: SEAM_API_KEY);

  var connectWebview = seam.ConnectWebviews.Create();

  Console.WriteLine(connectWebview.LoginSuccessful); // False

  // Use the returned Connect Webview URL to display
  // the Connect Webview authorization flow to your user.
  Console.WriteLine(connectWebview.Url);
  ```
</CodeGroup>

**Output:**

<CodeGroup>
  ```json JavaScript theme={null}
  false
  https://connect.getseam.com/connect_webviews/view?connect_webview_id=12345678-1234-1234-1234-123456789012&auth_token=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
  ```

  ```json cURL theme={null}
  Login Successful (false): false
  https://connect.getseam.com/connect_webviews/view?connect_webview_id=12345678-1234-1234-1234-123456789012&auth_token=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
  ```

  ```json Python theme={null}
  https://connect.getseam.com/connect_webviews/view?connect_webview_id=12345678-1234-1234-1234-123456789012&auth_token=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
  ```

  ```json Ruby theme={null}
  false
  https://connect.getseam.com/connect_webviews/view?connect_webview_id=12345678-1234-1234-1234-123456789012&auth_token=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
  ```

  ```json PHP theme={null}
  false
  https://connect.getseam.com/connect_webviews/view?connect_webview_id=12345678-1234-1234-1234-123456789012&auth_token=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
  ```

  ```json C# theme={null}
  False
  https://connect.getseam.com/connect_webviews/view?connect_webview_id=12345678-1234-1234-1234-123456789012&auth_token=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
  ```
</CodeGroup>

***

### Authorize your workspace

In a web browser, go to the URL that the Connect Webview object returned.

For application developers, you can redirect your user to this Connect Webview URL so that they can authorize your app to control their devices using Seam. We even provide a prebuilt [Connect Account Button](/ui-components/overview/react-components/connect-account-button) within our suite of [Seam Components](/ui-components/overview) that help you build your device management flow.

<Check>
  Because you're using a sandbox workspace, you can connect Seam's test August
  account. We provide [virtual devices](./august-locks-sample-data) for each of
  the brands that we support. These sandbox devices and systems enable you to
  test your app with devices from multiple brands without the need to own all
  the corresponding physical devices.
</Check>

Complete the Connect Webview authorization flow by entering the following [August sandbox account](./august-locks-sample-data) credentials:

* **Device Region:** Others
* **Email:** [jane@example.com](mailto:jane@example.com)
* **Password:** 1234
* **2FA Method:** Email ([jane@example.com](mailto:jane@example.com))
* **Two Factor Code:** 123456

<picture>
  <source />

  <img alt="Use the Seam Connect Webview authorization flow to connect an August account with Seam. This flow varies slightly based on the device manufacturer and region." />
</picture>

Confirm that authorization through the Connect Webview was successful by querying its status.

**Code:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  const updatedConnectWebview = await seam.connectWebviews.get({
    connect_webview_id: connectWebview.connect_webview_id,
  })

  console.log(updatedConnectWebview.login_successful) // true
  ```

  ```bash cURL theme={null}
  curl -X 'GET' \
    'https://connect.getseam.com/connect_webviews/get' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d "{
    \"connect_webview_id\": \"${connect_webview_id}\"
  }" | jq -r '"Login Successful (true): " + (.connect_webview.login_successful | tostring)'
  ```

  ```python Python theme={null}
  updated_connect_webview = seam.connect_webviews.get(connect_webview.connect_webview_id)

  assert updated_connect_webview.login_successful is True # True
  ```

  ```ruby Ruby theme={null}
  updated_connect_webview = seam.connect_webviews.get(
    connect_webview_id: connect_webview.connect_webview_id
  )

  puts updated_connect_webview.login_successful # true
  ```

  ```php PHP theme={null}
  $updated_connect_webview = $seam->connect_webviews->get(
    connect_webview_id: $connect_webview->connect_webview_id
  );

  echo $updated_connect_webview->login_successful ? 'true' : 'false', "\n"; // true
  ```

  ```csharp C# theme={null}
  var updatedConnectWebview = seam.ConnectWebviews.Get(
    connectWebviewId: connectWebview.connectWebviewId
  );

  Console.WriteLine(updatedConnectWebview.LoginSuccessful); // True
  ```
</CodeGroup>

**Output:**

<CodeGroup>
  ```json JavaScript theme={null}
  true
  ```

  ```json cURL theme={null}
  Login Successful (true): true
  ```

  ```json Python theme={null}
  True
  ```

  ```json Ruby theme={null}
  true
  ```

  ```json PHP theme={null}
  true
  ```

  ```json C# theme={null}
  True
  ```
</CodeGroup>

***

## Step 3: Retrieve August lock devices

When you link an August account with Seam, we create a `device` object to represent each August lock in your account. You can then retrieve these August devices using the [List Devices](/api/devices/list) and [Get Device](/api/devices/get) endpoints.

The Seam API exposes each device's properties, such as the door lock status, power status, capabilities, and so on.

**Code:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  // Retrieve all devices, filtered by manufacturer,
  // which is one of several filters that list() supports.
  const allAugustLocks = await seam.devices.list({ manufacturer: 'august' })

  // Select the first device as an example.
  const frontDoor = allAugustLocks[0]

  // Inspect specific properties.
  console.log(frontDoor.properties.online) // true
  console.log(frontDoor.properties.locked) // true

  // View the entire returned device object.
  console.log(frontDoor)
  ```

  ```bash cURL theme={null}
  # Retrieve all devices, filtered by manufacturer, which is
  # one of several filters that the list endpoint supports.
  all_august_locks=$(
    # Use GET or POST.
    curl -X 'GET' \
      'https://connect.getseam.com/devices/list' \
      -H 'accept: application/json' \
      -H "Authorization: Bearer ${SEAM_API_KEY}" \
      -H 'Content-Type: application/json' \
      -d '{
      "manufacturer": "august"
    }')

  # Select the first device as an example.
  front_door=$(jq -r '.devices[0]' <<< ${all_august_locks})

  # Inspect specific properties.
  echo $(jq -r '"Online (true): " + (.properties.online | tostring)' <<< ${front_door})
  echo $(jq -r '"Locked (true): " + (.properties.locked | tostring)' <<< ${front_door})

  # View the entire returned device object.
  echo ${front_door}
  ```

  ```python Python theme={null}
  # Retrieve all devices, filtered by manufacturer,
  # which is one of several filters that list() supports.
  all_august_locks = seam.devices.list(manufacturer="august")

  # Select the first device as an example.
  front_door = all_august_locks[0]

  # Inspect specific properties.
  assert front_door.properties["online"] is True # True
  assert front_door.properties["locked"] is True # True

  # View the entire returned device object.
  pprint(front_door)
  ```

  ```ruby Ruby theme={null}
  # Retrieve all devices, filtered by manufacturer,
  # which is one of several filters that list() supports.
  all_august_locks = seam.devices.list(manufacturer: "august")

  # Select the first device as an example.
  front_door = all_august_locks[0]

  # Inspect specific properties.
  puts front_door.properties.online # true
  puts front_door.properties.locked # true

  # View the entire returned device object.
  puts front_door.inspect
  ```

  ```php PHP theme={null}
  // Retrieve all devices, filtered by manufacturer,
  // which is one of several filters that list() supports.
  $all_august_locks = $seam->devices->list(manufacturer: "august");

  // Select the first device as an example.
  $front_door = $all_august_locks[0];

  // Inspect specific properties.
  echo $front_door->properties->online ? 'true' : 'false', "\n"; // true
  echo $front_door->properties->locked ? 'true' : 'false', "\n"; // true

  // View the entire returned device object.
  echo json_encode($front_door, JSON_PRETTY_PRINT);
  ```

  ```csharp C# theme={null}
  // Retrieve all devices, filtered by manufacturer,
  // which is one of several filters that list() supports.
  var allAugustLocks = seam.Devices.List(
    manufacturer: Seam.Api.Devices.ListRequest.ManufacturerEnum.August
  );

  // Select the first device as an example.
  Device frontDoor = allAugustLocks[0];

  // Inspect specific properties.
  Console.WriteLine(frontDoor.Properties.Online); // true
  Console.WriteLine(frontDoor.Properties.Locked); // true

  // View the entire returned device object.
  Console.WriteLine(frontDoor);
  ```
</CodeGroup>

**Output:**

<CodeGroup>
  ```json JavaScript theme={null}
  true
  true
  {
    device_id: '11111111-1111-1111-1111-444444444444',
    display_name: 'Lock 1',
    workspace_id: '00000000-0000-0000-0000-000000000000',
    connected_account_id: '11111111-1111-1111-1111-222222222222',
    created_at: '2024-05-29T20:08:48.878Z',
    properties: {
      manufacturer: 'august',
      online: true,
      locked: true,
      battery: {
        level: 0.9999532347993827,
        status: 'full'
      },
      ...
    },
    can_remotely_unlock: true,
    ...
  }
  ```

  ```json cURL theme={null}
  Online (true): true
  Locked (true): true
  {
    "device_id": "11111111-1111-1111-1111-444444444444",
    "display_name": "Lock 1",
    "workspace_id": "00000000-0000-0000-0000-000000000000",
    "connected_account_id": "11111111-1111-1111-1111-222222222222",
    "created_at": "2024-05-29T20:08:48.878Z",
    "properties": {
      "manufacturer": "august",
      "locked": true,
      "online": true,
      "battery": {
        "level": 0.9999532347993827,
        "status": "full"
      },
      ...
    },
    "can_remotely_unlock": true,
    ...
  }
  ```

  ```json Python theme={null}
  Device(
    device_id='11111111-1111-1111-1111-444444444444',
    display_name='Lock 1',
    workspace_id='00000000-0000-0000-0000-000000000000'
    connected_account_id='11111111-1111-1111-1111-222222222222',
    created_at='2024-05-29T20:08:48.878Z',
    properties={
      'manufacturer': 'august',
      'online': True,
      'locked': True,
      'battery': {
        'level': 0.9999532347993827,
        'status': 'full'
      },
      ...
    }
    can_remotely_unlock=True,
    ...
  )
  ```

  ```json Ruby theme={null}
  true
  true
  <
    Seam::Device:0x00438
      device_id="11111111-1111-1111-1111-444444444444"
      display_name="Lock 1"
      workspace_id="00000000-0000-0000-0000-000000000000"
      connected_account_id="11111111-1111-1111-1111-222222222222"
      created_at=2024-05-29 20:08:48.878 UTC
      properties={
        "manufacturer"=>"august",
        "online"=>true,
        "locked"=>true,
        "battery"=>{
          "level"=>0.9999532347993827,
          "status"=>"full"
        },
        ...
      }
      can_remotely_unlock=true
      ...
  >
  ```

  ```json PHP theme={null}
  true
  true
  {
    "device_id": "11111111-1111-1111-1111-444444444444",
    "display_name": "Lock 1",
    "workspace_id": "00000000-0000-0000-0000-000000000000",
    "connected_account_id": "11111111-1111-1111-1111-222222222222",
    "created_at": "2024-05-29T20:08:48.878Z",
    "properties": {
      "manufacturer": "august",
      "online": true,
      "locked": true,
      "battery": {
        "level": 0.9999532347993827,
        "status": "full"
      },
      ...
    },
    "can_remotely_unlock": true,
    ...
  }
  ```

  ```json C# theme={null}
  True
  True
  {
    "device_id": "11111111-1111-1111-1111-444444444444",
    "display_name": "Lock 1",
    "workspace_id": "00000000-0000-0000-0000-000000000000",
    "connected_account_id": "11111111-1111-1111-1111-222222222222",
    "created_at": "2024-05-29T20:08:48.878Z",
    "properties": {
      "manufacturer": "august",
      "online": true,
      "locked": true,
      "battery": {
        "level": 0.9999532,
        "status": "full"
      },
      ...
    },
    "can_remotely_unlock": true,
    ...
  }
  ```
</CodeGroup>

***

## Step 4: Control your August lock

Next, you can use the Seam API to control your lock.

Each device that you connect to Seam has a specific set of capabilities. These capabilities define the Seam API actions that you can use, such as [remote unlock actions](/low-level-apis/smart-locks/lock-and-unlock), [programming access codes](/low-level-apis/smart-locks/access-codes), and so on. Seam's intuitive and granular [capability flags](/capability-guides/device-and-system-capabilities#capability-flags) inform your application about what features and behaviors each device supports. Notice the capability flags within the code samples in this guide.

Try out the following actions on your August lock:

* [ ] [Unlock your lock](#unlock-your-lock)
* [ ] [Program access codes on your lock](#program-access-codes-on-your-lock)

### Unlock your lock

To unlock a door, use the [Unlock Door](/api/locks/unlock_door) endpoint. Specify the device that you want to unlock by including the `device_id` in the request body. This endpoint returns an [action attempt](/core-concepts/action-attempts) to track the progress of the unlock operation.

**Code:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  // Confirm that the device can remotely unlock.
  // You're using a capability flag here!
  if (frontDoor.can_remotely_unlock) {
    // Perform the unlock operation
    // and return an action attempt.
    const actionAttempt = await seam.locks.unlockDoor({
      device_id: frontDoor.device_id,
    })
  }
  ```

  ```bash cURL theme={null}
  # Confirm that the device can remotely unlock.
  # You're using a capability flag here!
  if  $(jq -r '.can_remotely_lock' <<< ${front_door}); then \
    # Perform the unlock operation
    # and return an action attempt.
    curl -X 'POST' \
      'https://connect.getseam.com/locks/unlock_door' \
      -H 'accept: application/json' \
      -H "Authorization: Bearer ${SEAM_API_KEY}" \
      -H 'Content-Type: application/json' \
      -d "{
        \"device_id\": \"$(jq -r '.device_id' <<< ${front_door})\"
    }";
  fi
  ```

  ```python Python theme={null}
  # Confirm that the device can remotely unlock.
  # You're using a capability flag here!
  if front_door.can_remotely_unlock:
    # Perform the unlock operation
    # and return an action attempt.
    action_attempt=seam.locks.unlock_door(device_id=front_door.device_id)
  ```

  ```ruby Ruby theme={null}
  # Confirm that the device can remotely unlock.
  # You're using a capability flag here!
  if (front_door.can_remotely_unlock)
    # Perform the unlock operation
    # and return an action attempt.
    action_attempt = seam.locks.unlock_door(device_id: front_door.device_id)
  end
  ```

  ```php PHP theme={null}
  // Confirm that the device can remotely unlock.
  // You're using a capability flag here!
  if ($front_door->can_remotely_unlock) {
    // Perform the unlock operation
    // and return an action attempt.
    $action_attempt = $seam->locks->unlock_door(device_id: $front_door->device_id);
  }
  ```

  ```csharp C# theme={null}
  // Confirm that the device can remotely unlock.
  // You're using a capability flag here!
  if (frontDoor.CanRemotelyUnlock == true) {
    // Perform the unlock operation
    // and return an action attempt.
    ActionAttempt actionAttempt = seam.Locks.UnlockDoor(deviceId: frontDoor.DeviceId);
  }
  ```
</CodeGroup>

**Output:**

<CodeGroup>
  ```json JavaScript theme={null}
  {
    "actionAttempt": {
      "status": "success",
      "action_attempt_id": "11111111-2222-3333-4444-555555555555",
      "action_type": "UNLOCK_DOOR",
      "result": {},
      "error": null
    }
  }
  ```

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

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

  ```json Ruby theme={null}
  <Seam::ActionAttempt:0x00438
    status="pending"
    action_type="UNLOCK_DOOR"
    action_attempt_id="11111111-2222-3333-4444-555555555555"
    result=nil>
  ```

  ```json PHP theme={null}
  {
    "action_attempt_id": "11111111-2222-3333-4444-555555555555",
    "action_type": "UNLOCK_DOOR",
    "error": null,
    "result": {},
    "status": "success"
  }
  ```

  ```json C# theme={null}
  {
    "status": "pending",
    "action_type": "UNLOCK_DOOR",
    "action_attempt_id": "11111111-2222-3333-4444-555555555555"
  }
  ```
</CodeGroup>

You can track the status of the unlock operation to confirm that the device unlocked successfully. Query the `locked` status of the device, [retrieve the action attempt](/api/action_attempts/get) by ID, or look for a [`lock.unlocked` event](/api/locks/events#lock-unlocked).

To query the `locked` status of the device:

**Code:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  // Get the device by ID.
  const updatedFrontDoor = await seam.devices.get({device_id: frontDoor.device_id});

  // Inspect the locked property to confirm
  // that the unlock operation was successful.
  console.log(updatedFrontDoor.properties.locked) // false
  ```

  ```bash cURL theme={null}
  # Get the device by ID.
  updated_front_door=$(
    # Use GET or POST.
    curl -X 'GET' \
      'https://connect.getseam.com/devices/get' \
      -H 'accept: application/json' \
      -H "Authorization: Bearer ${SEAM_API_KEY}" \
      -H 'Content-Type: application/json' \
      -d "{
        \"device_id\": \"$(jq -r '.device_id' <<< ${front_door})\"
    }")

  # Inspect the locked property to confirm
  # that the unlock operation was successful.
  echo $(jq -r '"Locked (false): " + (.device.properties.locked | tostring)' <<< ${updated_front_door})
  ```

  ```python Python theme={null}
  # Get the device by ID.
  updated_front_door = seam.devices.get(device_id=front_door.device_id)

  # Inspect the locked property to confirm
  # that the unlock operation was successful.
  assert updated_front_door.properties["locked"] is False # False
  ```

  ```ruby Ruby theme={null}
  # Get the device by ID.
  updated_front_door = seam.devices.get(device_id: front_door.device_id)

  # Inspect the locked property to confirm
  # that the unlock operation was successful.
  puts updated_front_door.properties.locked # false
  ```

  ```php PHP theme={null}
  // Get the device by ID.
  $updated_front_door = $seam->devices->get(device_id: $front_door->device_id);

  // Inspect the locked property to confirm
  // that the unlock operation was successful.
  echo $updated_front_door->properties->locked ? 'true' : 'false', "\n"; // false
  ```

  ```csharp C# theme={null}
  // Get the device by ID.
  Device updatedFrontDoor = seam.Devices.Get(
    deviceId: frontDoor.DeviceId
  );

  // Inspect the locked property to confirm
  // that the unlock operation was successful.
  Console.WriteLine(updatedFrontDoor.Properties.Locked); // false
  ```
</CodeGroup>

**Output:**

<CodeGroup>
  ```json JavaScript theme={null}
  false
  ```

  ```json cURL theme={null}
  Locked (false): false
  ```

  ```json Python theme={null}
  False
  ```

  ```json Ruby theme={null}
  false
  ```

  ```json PHP theme={null}
  false
  ```

  ```json C# theme={null}
  False
  ```
</CodeGroup>

<Check>
  Now that you have successfully unlocked your lock, you can use the [Lock
  Door](/api/locks/lock_door) endpoint to lock it
  again.
</Check>

***

### Program access codes on your lock

You can use the Seam API to program [online access codes](/low-level-apis/smart-locks/access-codes) on August locks that have an integrated or accessory keypad. Lock users can then enter these access codes using the keypad to unlock the lock.

The Seam API makes it easy to program both [ongoing](/low-level-apis/smart-locks/access-codes#ongoing-access-codes) and [time-bound](/low-level-apis/smart-locks/access-codes#time-bound-access-codes) online access codes.

**Code:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  // Confirm that the device supports online access codes.
  // Here's another capability flag!
  if (updatedFrontDoor.can_program_online_access_codes) {
    // Create an ongoing online access code.
    await seam.accessCodes.create({
      device_id: updatedFrontDoor.device_id,
      name: 'my ongoing code',
      code: '1234',
    })
    // Create a time-bound online access code.
    await seam.accessCodes.create({
      device_id: updatedFrontDoor.device_id,
      name: 'my time-bound code',
      starts_at: '2025-01-01T16:00:00Z',
      ends_at: '2025-01-22T12:00:00Z',
      code: '2345',
    })
    // List all access codes for this device.
    const accessCodes = await seam.accessCodes.list({
      device_id: updatedFrontDoor.device_id,
    })
    console.log(accessCodes)
  }
  ```

  ```bash cURL theme={null}
  # Confirm that the device supports online access codes.
  # Here's another capability flag!
  if  $(jq -r '.device.can_program_online_access_codes' <<< ${updated_front_door}); then \
    # Create an ongoing online access code.
    curl -X 'POST' \
      'https://connect.getseam.com/access_codes/create' \
      -H 'accept: application/json' \
      -H "Authorization: Bearer ${SEAM_API_KEY}" \
      -H 'Content-Type: application/json' \
      -d "{
        \"device_id\": \"$(jq -r '.device.device_id' <<< ${updated_front_door})\",
        \"name\": \"my ongoing code\",
        \"code\": \"1234\"
    }"
    # Create a time-bound online access code.
    curl -X 'POST' \
      'https://connect.getseam.com/access_codes/create' \
      -H 'accept: application/json' \
      -H "Authorization: Bearer ${SEAM_API_KEY}" \
      -H 'Content-Type: application/json' \
      -d "{
        \"device_id\": \"$(jq -r '.device.device_id' <<< ${updated_front_door})\",
        \"name\": \"my time-bound code\",
        \"starts_at\": \"2025-01-01T16:00:00Z\",
        \"ends_at\": \"2025-01-22T12:00:00Z\",
        \"code\": \"2345\"
    }"
    # List all access codes for this device.
    access_codes=$(
    # Use GET or POST.
    curl -X 'GET' \
      'https://connect.getseam.com/access_codes/list' \
      -H 'accept: application/json' \
      -H "Authorization: Bearer ${SEAM_API_KEY}" \
      -H 'Content-Type: application/json' \
      -d "{
        \"device_id\": \"$(jq -r '.device.device_id' <<< ${updated_front_door})\"
    }")
    echo ${access_codes};
  fi
  ```

  ```python Python theme={null}
  # Confirm that the device supports online access codes.
  # Here's another capability flag!
  if updated_front_door.can_program_online_access_codes:
    # Create an ongoing online access code.
    seam.access_codes.create(
      device_id = updated_front_door.device_id,
      name = "my ongoing code",
      code = "1234"
    )
    # Create a time-bound online access code.
    seam.access_codes.create(
      device_id = updated_front_door.device_id,
      name = "my time-bound code",
      starts_at = "2025-01-01T16:00:00Z",
      ends_at = "2025-01-22T12:00:00Z",
      code = "2345"
    )
    # List all access codes for this device.
    access_codes = seam.access_codes.list(
      device_id = updated_front_door.device_id
    )
    pprint(access_codes)
  ```

  ```ruby Ruby theme={null}
  # Confirm that the device supports online access codes.
  # Here's another capability flag!
  if (updated_front_door.can_program_online_access_codes)
    # Create an ongoing online access code.
    seam.access_codes.create(
      device_id: updated_front_door.device_id,
      name: "my ongoing code",
      code: "1234"
    )
    # Create a time-bound online access code.
    seam.access_codes.create(
      device_id: updated_front_door.device_id,
      name: "my time-bound code",
      starts_at: "2025-01-01T16:00:00Z",
      ends_at: "2025-01-22T12:00:00Z",
      code: "2345"
    )
    # List all access codes for this device.
    access_codes = seam.access_codes.list(
      device_id: updated_front_door.device_id
    )
    puts access_codes.inspect
  end
  ```

  ```php PHP theme={null}
  // Confirm that the device supports online access codes.
  // Here's another capability flag!
  if ($updated_front_door->can_program_online_access_codes) {
    // Create an ongoing online access code.
    $seam->access_codes->create(
      device_id: $updated_front_door->device_id,
      name: "my ongoing code",
      code: "1234"
    );
    // Create a time-bound online access code.
    $seam->access_codes->create(
      device_id: $updated_front_door->device_id,
      name: "my time-bound code",
      starts_at:  "2025-01-01T16:00:00Z",
      ends_at: "2025-01-22T12:00:00Z",
      code: "2345"
    );
    // List all access codes for this device.
    $access_codes = $seam->access_codes->list(
      device_id: $updated_front_door->device_id
    );
    echo json_encode($access_codes, JSON_PRETTY_PRINT);
  }
  ```

  ```csharp C# theme={null}
  // Confirm that the device supports online access codes.
  // Here's another capability flag!
  if (updatedFrontDoor.CanProgramOnlineAccessCodes == true) {
    // Create an ongoing online access code.
    seam.AccessCodes.Create(
      deviceId: updatedFrontDoor.DeviceId,
      name: "my ongoing code",
      code: "1234"
    );
    // Create a time-bound online access code.
    seam.AccessCodes.Create(
      deviceId: updatedFrontDoor.DeviceId,
      name: "my time-bound code",
      startsAt: "2025-01-01T16:00:00Z",
      endsAt: "2025-01-22T12:00:00Z",
      code: "2345"
    );
    // List all access codes for this device.
    var accessCodes = seam.AccessCodes.List(
      deviceId: updatedFrontDoor.DeviceId
    );
    foreach (var accessCode in accessCodes)
    {
      Console.WriteLine(accessCode);
    }
  }
  ```
</CodeGroup>

**Output:**

<CodeGroup>
  ```json JavaScript theme={null}
  [
    {
      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-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',
      ...
    }
  ]
  ```

  ```json cURL theme={null}
  {
    "access_codes": [
      {
        "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-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
  }
  ```

  ```json Python theme={null}
  [
    AccessCode(
      access_code_id='11111111-1111-1111-1111-555555555555',
      device_id='11111111-1111-1111-1111-444444444444',
      type='ongoing',
      code='1234',
      name='my ongoing code',
      ...
    )
    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',
      ...
    )
  ]
  ```

  ```json Ruby theme={null}
  [
    <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"
      ...
    >,
    <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
      ...
    >
  ]
  ```

  ```json PHP theme={null}
  [
    {
      "access_code_id": "11111111-1111-1111-1111-555555555555",
      "device_id": "11111111-1111-1111-1111-444444444444",
      "name": "my ongoing code",
      "type": "ongoing",
      "code": "1234",
      ...
    },
    {
      "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",
    }
  ]
  ```

  ```json C# theme={null}
  {
    "type": "ongoing",
    "access_code_id": "11111111-1111-1111-1111-555555555555",
    "device_id": "11111111-1111-1111-1111-444444444444",
    "name": "my ongoing code",
    "code": "1234",
    ...
  }
  {
    "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",
    ...
  }
  ```
</CodeGroup>

***

## Step 5: Connect a real August lock

Now that you have learned the basics of using the Seam API, you can connect and control a real August device. To do so, make sure to switch to a [non-sandbox workspace](/core-concepts/workspaces#production-workspaces) and [API key](/core-concepts/authentication/api-keys).

For more details about setting up your real August lock, see the [August locks integration guide](/device-and-system-integration-guides/august-locks).

***

## Step 6: Build your application!

Seam makes it easy to develop your application. In addition to the robust Seam API and the wide variety of programming languages that our SDKs support, we also provide a suite of [Seam Components](/ui-components/overview). These prebuilt UI components help you to build your device management flow.

For example, you can use the [Device Table Seam Component](/ui-components/overview/react-components/device-table) to display a list of devices and to identify all devices with issues. You can use the [Device Details Seam Component](/ui-components/overview/react-components/device-details) to display a device's properties, settings, and issues, as well as to enable your users to perform actions based on each device's capabilities. The [Access Code Details Seam Component](/ui-components/overview/react-components/access-code-details) provides a similar display and actions for access codes.

Seam Components use a responsive design to fit seamlessly on any screen size. They also provide device debugging flows to help your users.

To learn about all the Seam Components that we provide, see [Seam Components](/ui-components/overview).

***

## Next steps

Now that you've completed this getting started guide for August devices, you can learn more about what you can do with the Seam API.

* [ ] **Explore**\
  See the [other devices and system integrations](/device-and-system-integration-guides) that Seam supports.
* [ ] **Learn**\
  Read about Seam [concepts](/core-concepts/overview) and the [device and system capabilities ](/capability-guides/device-and-system-capabilities)that Seam supports.
* [ ] **Use Seam Components**\
  Find out about [Seam Components](/ui-components/overview), which are prebuilt UI components for building your device management flow.
* [ ] **Use webhooks**\
  Learn how to use [webhooks](/developer-tools/webhooks) as an efficient way to receive device events.
* [ ] **Find out more**\
  Explore the other types of devices and systems that you can control with Seam, including [access control systems](/low-level-apis/access-systems), [thermostats](/capability-guides/thermostats), and [noise sensors](/capability-guides/noise-sensors).
* [ ] **Develop for mobile access**\
  Learn about Seam's [mobile access solution](/capability-guides/mobile-access).

<Info>
  If you have any questions or want to report an issue, email us at
  [support@seam.co](mailto:support@seam.co).
</Info>

***

## Quick links

<CardGroup>
  <Card title="Get an API Key (free)" href="https://console.seam.co/">
    Sign up for the Seam Console and get your API keys. →
  </Card>

  <Card title="Contact Sales" href="https://www.seam.co/contact-us">
    Got a project or a specific question? Contact our team to get answers. →
  </Card>
</CardGroup>


# August Locks
Source: https://docs.seam.co/device-and-system-integration-guides/august-locks/index

Guide for using August locks with Seam

<img alt="August logo" />

## Overview

August produces smart locks for the residential market. Seam integrates directly with the August Wi-Fi Smart Lock, as well as with additional August Smart Locks through the August Connect® Wi-Fi Bridge. In addition, Seam supports the August Smart Keypad accessory.

Each August lock attaches to an existing deadbolt, replacing only the lock component on the inside of a door. Consequently, August locks do not change the exterior of locks, and the existing physical keys still work with installed August locks.

***

## Supported Devices

<DeviceList />

This integration supports all August Smart Lock models that are connected to Wi-Fi, either through built-in Wi-Fi or using the [August Connect Wi-Fi Bridge](https://august.com/products/august-connect). Seam also supports the addition of the optional [August Smart Keypad](https://august.com/products/august-smart-keypad) to enable entering access codes to control the lock.

The following table details the requirements for compatibility with this Seam integration:

<table>
  <thead>
    <tr>
      <th>Product Models</th>
      <th>Compatibility</th>
      <th>Accessories</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        <a href="https://august.com/products/august-wifi-smart-lock">
          Wi-Fi Smart Lock
        </a>
      </td>

      <td>Compatible</td>

      <td>
        <ul>
          <li>Smart Keypad (optional)</li>
        </ul>
      </td>
    </tr>

    <tr>
      <td>
        <a href="https://august.com/products/august-smart-lock-pro-connect">
          Smart Lock Pro
        </a>
      </td>

      <td>Compatible only with Connect Wi-Fi Bridge</td>

      <td>
        <ul>
          <li>Connect Wi-Fi Bridge</li>
          <li>Smart Keypad (optional)</li>
        </ul>
      </td>
    </tr>

    <tr>
      <td>
        <a href="https://august.com/products/august-smart-lock-connect">
          Smart Lock
        </a>
      </td>

      <td>Compatible only with Connect Wi-Fi Bridge</td>

      <td>
        <ul>
          <li>Connect Wi-Fi Bridge</li>
          <li>Smart Keypad (optional)</li>
        </ul>
      </td>
    </tr>
  </tbody>
</table>

For detailed information about the August devices that Seam supports, see our [August Supported Devices page](https://www.seam.co/manufacturers/august):

***

## Supported Features

We support the following features:

* [Triggering web lock and unlock actions](/low-level-apis/smart-locks/lock-and-unlock)
* [Programming access codes](/low-level-apis/smart-locks/access-codes) on locks that have an installed August Smart Keypad

***

### Device Provider Key

Seam identifies these devices with the `august` device provider key. By default, a [Connect Webview](/core-concepts/connect-webviews) displays all of the stable providers that Seam supports, so your users can connect their August devices without you specifying a provider list. To narrow what a Connect Webview displays, see [Customize the Brands to Display in Your Connect Webviews](/core-concepts/connect-webviews/customizing-connect-webviews#customize-the-brands-to-display-in-your-connect-webviews).

***

## Setup Instructions

For instructions on connecting August locks to Seam, see the [August Setup Guide](./august-setup-guide).

***

## Troubleshooting

The following access code errors might appear for an August lock:

<table>
  <thead>
    <tr>
      <th>Error</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        <code>august\_device\_programming\_delay</code>
      </td>

      <td>
        August has acknowledged a request to program the code, but the access
        code has not yet been moved fully to the device. The device likely has
        an unstable internet connection. Seam continues to try to set the code
        on the device.
      </td>
    </tr>

    <tr>
      <td>
        <code>august\_device\_slots\_full</code>
      </td>

      <td>All access code slots on the device are full.</td>
    </tr>

    <tr>
      <td>
        <code>august\_lock\_bad\_access\_code\_format</code>
      </td>

      <td>The access code format is incorrect.</td>
    </tr>

    <tr>
      <td>
        <code>august\_lock\_missing\_keypad</code>
      </td>

      <td>The August lock is missing a keypad.</td>
    </tr>

    <tr>
      <td>
        <code>august\_lock\_temporarily\_offline</code>
      </td>

      <td>
        The August lock was temporarily offline while setting or removing a
        code. The code should be set removed when the lock comes back online.
      </td>
    </tr>
  </tbody>
</table>

***

## Where to Order

Order August locks and accessories directly from the August website or from Amazon.

<table>
  <thead>
    <tr>
      <th />

      <th />

      <th />

      <th />

      <th />
    </tr>
  </thead>

  <tbody>
    <tr>
      <td />

      <td>
        <strong>August</strong>
      </td>

      <td />

      <td>
        <a href="https://august.com/">[https://august.com/](https://august.com/)</a>
      </td>

      <td>
        <a href="/images/august-logo.png">august-logo.png</a>
      </td>
    </tr>

    <tr>
      <td />

      <td>
        <strong>August Products on Amazon</strong>
      </td>

      <td />

      <td>
        <a href="https://amzn.to/3sVFNTl">[https://amzn.to/3sVFNTl](https://amzn.to/3sVFNTl)</a>
      </td>

      <td>
        <a href="/images/august-on-amazon.png">august-on-amazon.png</a>
      </td>
    </tr>
  </tbody>
</table>

***


# Avigilon Alta Access System Sample Data
Source: https://docs.seam.co/device-and-system-integration-guides/avigilon-alta-access-system/avigilon-alta-access-system-sample-data

Add virtual Avigilon Alta access system devices to your Seam sandbox workspace using these sample credentials to test your integration.

Use the following set of credentials to add virtual [Avigilon Alta access system](/device-and-system-integration-guides/avigilon-alta-access-system)-connected devices to your Seam [sandbox workspace](/core-concepts/workspaces#sandbox-workspaces):

| Email Address                               | Password |
| ------------------------------------------- | -------- |
| [jane@example.com](mailto:jane@example.com) | 1234     |


# Avigilon Alta Setup Guide
Source: https://docs.seam.co/device-and-system-integration-guides/avigilon-alta-access-system/avigilon-alta-setup-guide

Connect your Avigilon Alta access system to Seam.

## Overview

This guide walks you through connecting your Avigilon Alta access control system to Seam. Your Avigilon Alta system must already be set up and working before proceeding.

***

## Step 1: Gather Your Credentials

Obtain the credentials for a user within the Avigilon Alta organization to which you want to connect.

***

## Step 2: Verify User Permissions

1. In a web browser, navigate to and log in to your [Avigilon Alta dashboard](https://control.openpath.com/login).
2. In the settings for the user, verify the user's permissions as follows:

   * Make sure that **Portal access** is selected (enabled).
   * Make sure that the **Roles** for the user include **Super Admin**.

   <img alt="Verify user permissions in the Avigilon Alta dashboard." />

***

## Step 3: Connect to Seam

Use the credentials for the user to log in to the [Connect Webview](/core-concepts/connect-webviews) to add your Avigilon Alta access system and devices to Seam.

***

## Step 4: Verify the Connection

After connecting, verify that your Avigilon Alta system and devices appear in your Seam workspace and show a **connected** status.

***

## Troubleshooting

### Connection fails during login

* Double-check that the user credentials are correct.
* Confirm that the user has **Portal access** enabled and the **Super Admin** role assigned.

### Devices not appearing after connecting

* Verify that your devices are registered and online in the [Avigilon Alta dashboard](https://control.openpath.com/login).


# Avigilon Alta Access System
Source: https://docs.seam.co/device-and-system-integration-guides/avigilon-alta-access-system/index

Guide for using the Avigilon Alta access system with Seam

<img alt="Avigilon Alta logo" />

## Overview

Seam integrates with the Avigilon Alta access system that provides cloud-based access control for a variety of industries, including corporate, commercial, hospitality, multifamily residential, and others. With support for doors, elevators, turnstiles, and gates, the Avigilon Alta access control system enables you to secure a single building or multiple buildings using the same system. Further, users need only a single credential for all doors and access points.

***

## Supported Devices

<DeviceList />

This integration supports [all readers, controllers, and wireless locks connected to the Avigilon Alta platform](https://www.avigilon.com/access-control/cloud).

<img alt="Avigilon Alta access system devices" />

For detailed information about the Avigilon Alta-connected devices that Seam supports, see our [Avigilon Alta Supported Devices page](https://www.seam.co/manufacturers/avigilon-alta).

***

## Supported Features

We support the following features:

* [Triggering web lock and unlock actions](/low-level-apis/smart-locks/lock-and-unlock)

***

### Device Provider Key

Seam identifies these devices with the `avigilon_alta` device provider key. By default, a [Connect Webview](/core-concepts/connect-webviews) displays all of the stable providers that Seam supports, so your users can connect their Avigilon Alta access system and devices without you specifying a provider list. To narrow what a Connect Webview displays, see [Customize the Brands to Display in Your Connect Webviews](/core-concepts/connect-webviews/customizing-connect-webviews#customize-the-brands-to-display-in-your-connect-webviews).

***

## Setup Instructions

For instructions on connecting Avigilon Alta access systems to Seam, see the [Avigilon Alta Setup Guide](./avigilon-alta-setup-guide).

***

## Where to Order

To purchase the Avigilon Alta access system and devices, request a quote from Avigilon.

<table>
  <thead>
    <tr>
      <th />

      <th />

      <th />

      <th />

      <th />
    </tr>
  </thead>

  <tbody>
    <tr>
      <td />

      <td>
        <strong>Avigilon Quote Request</strong>
      </td>

      <td />

      <td>
        <a href="https://www.avigilon.com/quote">
          [https://www.avigilon.com/quote](https://www.avigilon.com/quote)
        </a>
      </td>

      <td>
        <a href="/images/avigilon-alta-logo.png">avigilon-alta-logo.png</a>
      </td>
    </tr>
  </tbody>
</table>

***


# Sandbox Brivo Access
Source: https://docs.seam.co/device-and-system-integration-guides/brivo-access/brivo-access-sample-data

Add virtual Brivo Access devices to your Seam sandbox workspace using these sample credentials to test your integration without real hardware.

Use the following set of credentials to add virtual [Brivo Access](/device-and-system-integration-guides/brivo-access)-connected devices to your Seam [sandbox workspace](/core-concepts/workspaces#sandbox-workspaces):

| Brivo Access API Key | Username                                    | Password |
| -------------------- | ------------------------------------------- | -------- |
| 1234                 | [jane@example.com](mailto:jane@example.com) | 1234     |


# Brivo Access Setup Guide
Source: https://docs.seam.co/device-and-system-integration-guides/brivo-access/brivo-access-setup-guide

Onboard your Brivo devices to Seam by obtaining a Brivo API key at the correct tier and connecting your devices through a Connect Webview.

## Steps to onboard your Brivo devices:

1. Obtain a Brivo API key at the correct API tier for your property
2. Onboard your Brivo devices through Connect Webview

### Step 1 - Obtain a Brivo API Key

Activating the Brivo API service requires the following steps:

1. Submit the **Brivo API Account Access Agreement**
   1. Submit the [**Brivo API Account Access Agreement**](https://support.brivo.com/s/article/Brivo-API-Account-Access-Agreement-v13-fillable?language=en_US) to your authorized Brivo Dealer.

      When completing this form, supply the following information:

      1. In the **Which solution(s) will be using the API?** field, type `Seam`.
      2. In the **If applicable, please provide the Developer Account Username** field, type `seamapi`.\\
         <br />
      3. Select the correct API Tier depending on how many devices you have. We suggest up to 20-devices per 100k API calls.
         1. **Up to 20 Devices -** B-OA-API-TX0 = Tier 0: 100k API Calls Per 30 Days
         2. **20 to 100 Devices -** B-OA-API-TX1 = Tier 1: 500k API Calls Per 30 Days
         3. **100 to 200 Devices -** B-OA-API-TX2 = Tier 2: 1MM API Calls Per 30 Days
         4. **200 to 400 Devices -** B-OA-API-TX3 = Tier 3: 2MM API Calls Per 30 Days

2. Your Brivo Dealer executes Part Two of the authorization agreement.

3. Brivo enables the API feature on your account upon execution of Part One and Part Two.

4. Brivo then provides the API key to you securely which will be used in the next Connect Webview step. This is a manual process on Brivo’s end. You can contact their customer service if you have not received your API key in a timely manner at [api@brivo.com](mailto:api@brivo.com)

### Step 2 - Connect Webview Instructions

1. Click the **“Add Device”** button to launch a new Connect Webview
2. Select **“Brivo”** within the list of available providers (your list might look slightly different)
3. Enter your Brivo API Key you obtained in **Step 1** and click “submit”
4. You will be prompted to login with an Admin ID and a password.
   * Your Admin ID is **NOT** the same as your Brivo Access username.
   * Your Admin ID can be found by logging into your Brivo Access account and clicking the account icon in the top right corner. Your Admin ID will be listed under the account’s email address (see example below).
   * Your password is the **same** password used to login to your Brivo Access account.


# Brivo Access
Source: https://docs.seam.co/device-and-system-integration-guides/brivo-access/index

Guide for using the Brivo Access platform with Seam

<img alt="Brivo logo" />

## Overview

Seam integrates with Brivo, which produces an access control platform for applications ranging from small, single-site facilities to multi-site commercial enterprises and multifamily residential properties. Brivo produces readers and control panels. In addition, through these Brivo control panels, the Brivo Access platform integrates with a variety of wireless smart locks, including Allegion, ASSA ABLOY Aperio, Z-Wave, and Salto.

***

## Supported Devices

<DeviceList />

This integration supports all [readers](https://www.brivo.com/products/smart-readers/), [control panels](https://www.brivo.com/products/control-panels/), and [wireless smart locks](https://www.brivo.com/low-level-apis/smart-locks/) connected to the Brivo Access platform. Brivo control panels also integrate with any Wiegand or Open Supervised Device Protocol (OSDP) readers.

The Brivo Access platform supports the following wireless locks:

<table>
  <thead>
    <tr>
      <th>Lock Brand</th>
      <th>Integration Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        <a href="https://resources.brivo.com/data-sheets/allegion-ndele-wireless-locks-data-sheet">
          Allegion
        </a>
      </td>

      <td>
        Brivo partners with Allegion to provide AD Series, LE, NDE, and
        Control® wireless locks for multifamily and commercial real estate
        uses.
      </td>
    </tr>

    <tr>
      <td>
        ASSA ABLOY Aperio™
      </td>

      <td>
        Brivo provides a variety of ASSA ABLOY Aperio locks for small, medium,
        and enterprise uses.
      </td>
    </tr>

    <tr>
      <td>
        Z-Wave
      </td>

      <td>
        Brivo provides a variety of Z-Wave-supported locks for multifamily
        residential doors connected to the

        <a href="https://www.brivo.com/products/smart-home/">
          Brivo Smart Home
        </a>

        .
      </td>
    </tr>

    <tr>
      <td>
        Salto
      </td>

      <td>Brivo supports various Salto wireless locks.</td>
    </tr>
  </tbody>
</table>

For detailed information about the Brivo-connected devices that Seam supports, see our [Brivo Supported Devices page](https://www.seam.co/manufacturers/brivo).

***

## Supported Features

We support the following features:

* [Triggering web lock and unlock actions](/low-level-apis/smart-locks/lock-and-unlock)
* [Programming access codes](/low-level-apis/smart-locks/access-codes) for readers and locks that have a keypad
* [Managing access systems](/low-level-apis/access-systems)

***

### Device Provider Key

Seam identifies these devices with the `brivo` device provider key. By default, a [Connect Webview](/core-concepts/connect-webviews) displays all of the stable providers that Seam supports, so your users can connect their Brivo Access platform and devices without you specifying a provider list. To narrow what a Connect Webview displays, see [Customize the Brands to Display in Your Connect Webviews](/core-concepts/connect-webviews/customizing-connect-webviews#customize-the-brands-to-display-in-your-connect-webviews).

***

## Next Steps

<CardGroup>
  <Card title="Order Brivo Devices" href="https://www.brivo.com/about/contact-us/">
    Submit a request on the Brivo Contact Us Page
  </Card>

  <Card title="Setup your Brivo account" href="/device-and-system-integration-guides/brivo-access/brivo-access-setup-guide">
    See this guide for how to connect your Brivo account with Seam
  </Card>
</CardGroup>

***


# Sandbox ControlByWeb Relays
Source: https://docs.seam.co/device-and-system-integration-guides/controlbyweb-relays/controlbyweb-relays-sample-data

Add virtual ControlByWeb relays to your Seam sandbox workspace using these sample credentials to test your integration without real hardware.

Use the following set of credentials to add virtual ControlByWeb relays to your Seam [sandbox workspace](/core-concepts/workspaces#sandbox-workspaces):

| Username                                    | Password |
| ------------------------------------------- | -------- |
| jane                                        | 1234     |
| Any email address in the example.com domain | 1234     |


# Get started with ControlByWeb Devices
Source: https://docs.seam.co/device-and-system-integration-guides/controlbyweb-relays/index

Learn how to connect and control your ControlByWeb device with the Seam API.

<img alt="ControlByWeb logo" />

<img alt="ControlByWeb Devices" />

## Overview

Seam provides a universal API to connect and control many brands of smart devices. This guide provides a rapid introduction to connecting and controlling your [ControlByWeb](https://www.seam.co/manufacturers/controlbyweb) relay device using the Seam API. To learn more about other smart device brands supported by Seam such as Yale, Schlage, and August, head over to our [integration page](https://www.seam.co/supported-devices-and-systems).

## 1 — Install Seam SDK

Seam provides client libraries for many languages, such as JavaScript, Python, Ruby, PHP, and others, as well as a Postman collection and [OpenAPI](https://connect.getseam.com/openapi.json) spec.

* JavaScript / TypeScript ([npm](https://www.npmjs.com/package/seam), [GitHub](https://github.com/seamapi/javascript))
* Python ([pip](https://pypi.org/project/seam/), [GitHub](https://github.com/seamapi/python))
* Ruby Gem ([rubygem](https://rubygems.org/gems/seam), [GitHub](https://github.com/seamapi/ruby))
* PHP ([packagist](https://packagist.org/packages/seamapi/seam), [GitHub](https://github.com/seamapi/php))
* C# ([nuget](https://www.nuget.org/packages/Seam), [GitHub](https://github.com/seamapi/csharp))

<Tabs>
  <Tab title="JavaScript">
    ```bash theme={null}
    npm i seam
    ```
  </Tab>

  <Tab title="Python">
    ```bash theme={null}
    pip install seam
    # For some development environments, use pip3 in this command instead of pip.
    ```
  </Tab>

  <Tab title="Ruby">
    ```bash theme={null}
    bundle add seam
    ```
  </Tab>

  <Tab title="PHP">
    ```bash theme={null}
    composer require seamapi/seam
    ```
  </Tab>

  <Tab title="C#">
    Install using [nuget](https://www.nuget.org/packages/Seam).
  </Tab>
</Tabs>

Once installed, [sign-up for Seam](https://console.seam.co/) to get your API key, and export it as an environment variable:

```
$ export SEAM_API_KEY=seam_test2ZTo_0mEYQW2TvNDCxG5Atpj85Ffw
```

<Info>
  This guide uses a Sandbox Workspace. Only virtual devices can be connected. If
  you need to connect a real ControlByWeb device, use a non-sandbox workspace
  and API key.
</Info>

## 2 — Link ControlByWeb Account with Seam

To control your ControlByWeb relay device via the Seam API, you must first authorize your Seam workspace against your ControlByWeb Cloud account. To do so, Seam provides[ Connect Webviews](/core-concepts/connect-webviews): pre-built UX flows that walk you through authorizing your application to control your ControlByWeb device.

#### Request a Connect Webview

<CodeGroup>
  ```javascript JavaScript theme={null}
  import { Seam } from 'seam'

  const seam = new Seam()

  const connectWebview = await seam.connectWebviews.create()

  console.log(connectWebview.login_successful) // false

  // Send the webview URL to your user
  console.log(connectWebview.url)
  ```

  ```python Python theme={null}
  from seam import Seam

  seam = Seam()

  webview = seam.connect_webviews.create()

  assert webview.login_successful is False

  # Send the webview URL to your user
  print(webview.url)
  ```

  ```ruby Ruby theme={null}
  require "seam"

  seam = Seam.new(api_key: "MY_API_KEY")

  webview = seam.connect_webviews.create()

  puts webview.login_successful # false

  # Send the webview URL to your user
  puts webview.url
  ```
</CodeGroup>

#### Authorize Your Workspace

Navigate to the URL returned by the Webview object. Since you are using a sandbox workspace, complete the login flow by entering the ControlByWeb [sandbox test account](/device-and-system-integration-guides/controlbyweb-relays/controlbyweb-relays-sample-data) credentials below:

* **username:** jane
* **password:** 1234

<img alt="Seam Connect Webview flow to connect ControlByWeb account with Seam" />

Confirm the Connect Webview was successful by querying its status:

<CodeGroup>
  ```javascript JavaScript theme={null}
  const updatedWebview = await seam.connectWebviews.get(
    connectWebview.connect_webview_id,
  )

  console.log(updatedWebview.login_successful) // true
  ```

  ```python Python theme={null}
  updated_webview = seam.connect_webviews.get(connect_webview_id: webview.connect_webview_id)

  assert updated_webview.login_successful # true
  ```

  ```ruby Ruby theme={null}
  updated_webview = seam.connect_webviews.get(connect_webview_id: webview.connect_webview_id)

  puts updated_webview.login_successful # true
  ```
</CodeGroup>

## 3 — Retrieve ControlByWeb devices

After a ControlByWeb account is linked with Seam, you can retrieve devices for this ControlByWeb account. The main device property currently exposed by the Seam API is whether the device is online and reachable.

<CodeGroup>
  ```javascript JavaScript theme={null}
  const allLocks = await seam.locks.list()

  const someLock = allLocks[0]

  console.log(someLock.properties.online) // true
  console.log(someLock.properties.locked) // true

  console.log(someLock)
  /*
  {
    device_id: '4a570d13-9704-46e0-b69c-9fea80d6a7aa',
    device_type: 'controlbyweb_device',
    capabilities_supported: [ 'lock' ],
    properties: {
      locked: true,
      online: true,
      manufacturer: 'controlbyweb',
      controlbyweb_metadata: {
        device_id: '9997',
        relay_name: 'firstRelay',
        device_name: 'Device 2'
      },
      name: 'Device 2',
      image_url: 'https://connect.getseam.com/assets/images/devices/unknown-lock.png',
      image_alt_text: 'Placeholder Lock Image'
    },
    location: null,
    connected_account_id: '5e0f49ac-3cb5-4e81-8c74-aba262218611',
    workspace_id: '40a179ca-3553-4226-9483-21df4e12f5fe',
    created_at: '2023-04-25T14:34:50.508Z',
    errors: [],
    warnings: []
  }
  */
  ```

  ```python Python theme={null}
  all_locks = seam.locks.list()

  some_lock = all_locks[0]

  assert some_lock.properties["online"] is True
  assert some_lock.properties["locked"] is True

  print(some_lock)
  # Device(
  #   device_id='4a570d13-9704-46e0-b69c-9fea80d6a7aa',
  #   device_type='controlbyweb_device',
  #   location=None,
  #   properties={
  #     'locked': True,
  #     'online': True,
  #     'manufacturer': 'controlbyweb',
  #     'controlbyweb_metadata': {
  #       'device_id': '9997',
  #       'relay_name': 'firstRelay',
  #       'device_name': 'Device 2'
  #     },
  #     'name': 'Device 2',
  #     'image_url': 'https://connect.getseam.com/assets/images/devices/unknown-lock.png',
  #     'image_alt_text': 'Placeholder Lock Image'
  #   },
  #   capabilities_supported=['lock'],
  #   errors=[]
  # )
  ```

  ```ruby Ruby theme={null}
  some_lock = seam.locks.list.first

  puts some_lock.properties.online # true
  puts some_lock.properties.locked # true

  puts some_lock.inspect
  # <Seam::Device:0x00146639380
  #   device_id="4a570d13-9704-46e0-b69c-9fea80d6a7aa"
  #   device_type="controlbyweb_device"
  #   properties={
  #     "locked"=>true,
  #     "online"=>true,
  #     "manufacturer"=>"controlbyweb",
  #     "controlbyweb_metadata"=>{
  #       "device_id"=>"9997",
  #       "relay_name"=>"firstRelay",
  #       "device_name"=>"Device 2"
  #     },
  #     "name"=>"Device 2",
  #     "image_url"=>"https://connect.getseam.com/assets/images/devices/unknown-lock.png",
  #     "image_alt_text"=>"Placeholder Lock Image"
  #   }
  #   created_at=2023-04-25 14:34:50 UTC
  #   errors=[]
  #   warnings=[]
  ```
</CodeGroup>

**4 — Triggering a ControlByWeb relay**

Next, you can perform the basic action of triggering a relay on the device. This action is mapped to an unlock API call in Seam.

#### Unlock a door

<mark>`POST`</mark>
`https://connect.getseam.com/locks/unlock_door`

**Request Body**

| Name       | Type   | Description |
| ---------- | ------ | ----------- |
| device\_id | String |             |

<CodeGroup>
  ```javascript JavaScript theme={null}
  // trigger the relay
  await seam.locks.unlockDoor(someLock.device_id)
  ```

  ```python Python theme={null}
  # trigger the relay
  seam.locks.unlock_door(some_lock)
  ```

  ```ruby Ruby theme={null}
  # trigger the relay
  seam.locks.unlock_door(device_id: some_lock.device_id)
  ```
</CodeGroup>

## Next Steps

Now that you've completed this guide, you can try to connect a real ControlByWeb device. To do so, make sure to switch to a non-sandbox workspace and API key as real devices cannot be connected to sandbox workspaces.

In addition, if you'd like to explore other aspects of Seam, here is a list of helpful resources:

* [Yale Getting Started Guide](../yale-locks/get-started-with-yale-locks)
* [August Getting Started Guide](../august-locks/get-started-with-august-locks)
* [Schlage Getting Started Guide](../schlage-locks/get-started-with-schlage-locks)
* [SmartThings Getting Started Guide](../smartthings-hubs-+-devices/get-started-with-smartthings-hubs-+-smart-locks)
* [Minut Getting Started Guide](../minut-sensors/get-started-with-minut-sensors)
* [Receiving webhook](/developer-tools/webhooks) for [device events](/api/events/list)
* [Core Concepts](/core-concepts/overview)

If you have any questions or want to report an issue, email us at [support@seam.co](mailto:support@seam.co).

## Supported Devices

<DeviceList />


# Dormakaba Ambiance Setup Guide
Source: https://docs.seam.co/device-and-system-integration-guides/dormakaba-ambiance-access-control-system/dormakaba-ambiance-setup-guide

Learn how to configure your Dormakaba Ambiance access control system for integration with Seam.

Use this guide to connect your Dormakaba Ambiance system to Seam and enable automated guest access with plastic cards, mobile keys, and (when available) Apple Wallet. After setup, Seam syncs reservation changes in real time and manages the full guest key lifecycle for you.

***

## Before you begin

Make sure your Ambiance environment is ready for integration.

#### Software

* Ambiance version 2.11.2 or later.
* Mobile Keys (if used) require:
  * A Dormakaba Mobile Access license
  * An active LEGIC Connect account

#### Hardware

* Locks and control units that support BLE/NFC mobile keys must run firmware 1.3.1.0+.
* Plastic card encoders must be installed and paired with your Ambiance server.

***

## 1. Configure Ambiance

Set up Ambiance so that Seam can connect and issue credentials on your behalf.

#### Create an integration operator.

1. Go to **Staff Management** → **New staff member**.
2. Name the user: `Seam Integration`.
3. Save the profile.
4. Enable **Ambiance Operator** and set the role to **Administrator**.
5. Enter any **Operator Username** and **Password** (Store these as your Staff Admin credentials).
6. Save the profile.

#### Create PMS Operator Login credentials

These are the credentials Seam uses to communicate with Ambiance.

1. Open the Seam Integration staff member.
2. Scroll to **PMS Operator Login** → **Add/Update Username & Password**.
3. Create a **Username** and **Password** (Store these as your PMS Operator credentials.).
4. Save the changes.

#### Enable API access

1. Go to **System Settings** → **Security**.
   * Toggle **Enable PMS Authentication**.
   * Save.
2. Go to **System Settings** → **PMS**.
   * Toggle **Enable LGS REST API**.
   * Create a **Client ID** and **Secret Key**.
   * Save.
3. In the same PMS section, toggle **Enable LGS SOAP API** and save.

#### What you should have after setup

* Staff Admin username
* Staff Admin password
* PMS Operator username
* PMS Operator password
* REST API Client ID
* REST API Secret Key

You’ll enter all six in the next step.

***

## 2. Connect Ambiance to Seam

<Info>
  If your Ambiance server is on-premises, [install Seam
  Bridge](/capability-guides/seam-bridge) before
  continuing.\ Seam Bridge provides the secure outbound connection Seam uses to
  reach your Ambiance REST and SOAP APIs.\ Install it on the same computer as
  Ambiance or on a machine with network access to Ambiance and verify it’s
  running.
</Info>

Once Seam Bridge is installed (or if your system is cloud-hosted), you can connect your Dormakaba Ambiance system to Seam.

1. **Choose connection method**

   Select **Bridge application** for on-prem systems, or **Cloud connection** if your Ambiance server is hosted.

2. **(Bridge only) Enter your pairing token**\
   Copy the pairing token from the Seam Bridge app and submit it.\\

3. **Enter your Ambiance operator credentials**\
   These credentials come from the Staff Admin (Operator) account you created in Ambiance.
   * **Ambiance Operator Username**

     Enter the username for your Staff Admin / Operator

   * **Ambiance Operator Password**\
     Enter the password for your Staff Admin / Operator

   * **Ambiance Server URL** (if using Bridge)\
     Enter the URL or IP address of your Ambiance server within the local area network.

     Example: `http://192.168.x.x`

   * **Ambiance Cloud URL** (if Cloud connection)

     Enter the base URL of your cloud-hosted Ambiance environment.\\

4. **Enter your REST API credentials**\
   These fields use the values created under System Settings → PMS in Ambiance.
   * **PMS Operator Username**

     Enter the PMS Operator Login username you created.

   * **PMS Operator Password**

     Enter the PMS Operator Login password.

   * **REST API Client ID**

     Enter the Client ID created when enabling LGS REST API.

   * **REST API Client Secret**

     Enter the Client Secret created alongside the Client ID.\\

Seam will verify the credentials and complete the connection. Once finished, your Ambiance entrances and reservations will begin syncing automatically.

***

## 3. Enable Bluetooth Mobile Keys in Ambiance (Optional)

1. Contact Dormakaba Technical Support at **+1 (800) 999-6213** to begin the Mobile Key License procurement and setup process.
   1. After selecting your language, follow the menu prompts: **Technical Support** → **Product Support** → **Hospitality** → **Ambiance**.
2. Inform them you are utilizing **Seam’s integration for Dormakaba Ambiance Mobile Keys**.
3. Dormakaba will connect your Community property to Seam’s LEGIC account and provide you with a **Project ID** and **API Key**.
4. In Ambiance, go to **System Settings** > **Advanced** > **Mobile Keys** > **LEGIC Configuration Settings** and enter the **Project ID** and **API Key**.
5. Enter **"[https://integration.legicconnect.com](https://integration.legicconnect.com)"** as the **Endpoint address**.
6. Click **Test LEGIC connection settings** to confirm that the settings were set correctly.
7. Click the **Save** icon in the top-right corner to save the changes.

***


# Dormakaba Ambiance Access Control System
Source: https://docs.seam.co/device-and-system-integration-guides/dormakaba-ambiance-access-control-system/index

Guide for using the Dormakaba Ambiance Access Control System with Seam

<img alt="Ambiance logo" />

***

## Overview

Connect Dormakaba Ambiance to Seam to automate guest access with mobile keys, plastic cards, and Apple Wallet. Seam gives you one API to plug Ambiance into your PMS or hospitality platform.

Seam handles the full guest key lifecycle. It issues mobile, card, or wallet keys automatically and expires them at checkout to keep access secure.

When a reservation changes, Seam updates Ambiance in real time. Reservation updates flow straight to Ambiance, ensuring guests always get the key that matches their stay.

<Info>
  **Before you begin**

  Follow the [Dormkaba Ambiance Setup Guide](./dormakaba-ambiance-setup-guide) to configure your Ambiance system settings and connect it to Seam.
</Info>

***

## Key Features

* Automated access – Issue Bluetooth, card, or wallet-based keys without manual steps.
* Secure credentials – Set keys to automatically expire after move-out or visit end.
* Faster move-ins – Seam creates guest profiles and provisions credentials directly from your PMS.
* Streamlined visitor access – Provide visitors with instant, temporary mobile keys that expire automatically.
* Reduced overhead – Eliminate manual key management while improving the guest experience.

***

## Supported Devices

<DeviceList />

This integration supports all wireless locks and readers connected to the Dormakaba Ambiance system.

***

## Related Features

* [**Access Grants**](/use-cases/granting-access/reservation-access-grants) – The universal way to manage access in Seam. Integrate once, and your access model works consistently across all providers, including Dormakaba Ambiance. For advanced, low-level control, you can still work directly with the ACS API.
* [**Mobile Keys**](/capability-guides/mobile-access) – Provision and revoke Bluetooth and wallet-based credentials directly from your PMS or app.
* [**Instant Keys**](/use-cases/granting-access/using-instant-keys) - Instantly issue temporary mobile pass that is shareable via an email or text.
* [**Plastic Card Encoding**](/api/acs/encoders/encode_credential) – Encode and issue physical access cards using Seam’s card management API.

***

## Connecting Dormakaba Ambiance to Seam

To enable your users to [connect an Ambiance system through Connect Webviews](/core-concepts/connect-webviews/customizing-connect-webviews#customize-the-brands-to-display-in-your-connect-webviews), include the Dormakaba Ambiance provider:

```json theme={null}
{
}
```

After the system admin completes the setup steps, they can enter their credentials into the Seam Connect form to complete the connection.

[→ See: Dormakaba Ambiance Setup Guide](../lockly-locks/lockly-setup-guide)

***

## Brand-Specific Restrictions

Note the following restrictions on the Ambiance system:

* Dormakaba Ambiance locks do not support remote web unlock. Unlock operations must occur through a mobile app or using a plastic card.

***

## Next Steps

<CardGroup>
  <Card title="Connect your Dormakaba Ambiance system to Seam" href="/device-and-system-integration-guides/dormakaba-ambiance-access-control-system/dormakaba-ambiance-setup-guide">
    Follow the setup guide to prepare your Dormakaba Ambiance system and enable
    API access.
  </Card>

  <Card title="Order Ambiance Locks" href="https://www.dormakaba.com/us-en/certified-installers">
    Find an installer for Ambiance products at your property.
  </Card>
</CardGroup>


# Sandbox Dormakaba Ambiance Access Control System
Source: https://docs.seam.co/device-and-system-integration-guides/dormakaba-ambiance-access-control-system/sandbox-dormakaba-ambiance-access-control-system

Add a virtual Dormakaba Ambiance access control system to your Seam sandbox workspace using these Connect Webview credentials to test your integration.

Use the following set of credentials to add virtual [Dormakaba Ambiance Access Control System](/device-and-system-integration-guides/dormakaba-ambiance-access-control-system)-connected devices to your Seam [sandbox workspace](/core-concepts/workspaces#sandbox-workspaces):

<Info>
  To use the virtual Ambiance Access Control System (ACS) to issue mobile keys
  in a sandbox workspace, you must also connect a LEGIC Connect account.
</Info>

## Dormakaba Ambiance Connect Webview Credentials

#### 1. Bridge connection pane

| Pairing Token            |
| ------------------------ |
| *<mark>prefilled</mark>* |

#### 2. Dormakaba Ambiance Dashboard Credentials

<table>
  <thead>
    <tr>
      <th>Field</th>
      <th>Value</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>PMS Operator Username</td>
      <td>jane</td>
    </tr>

    <tr>
      <td>PMS Operator Password</td>
      <td>1234</td>
    </tr>

    <tr>
      <td>Ambiance Server IP Address</td>

      <td>
        <em>
          <mark>prefilled</mark>
        </em>
      </td>
    </tr>
  </tbody>
</table>

#### 3. Dormakaba Ambiance API Credentials

<table>
  <thead>
    <tr>
      <th>Field</th>
      <th>Value</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Ambiance API Username</td>
      <td>jane</td>
    </tr>

    <tr>
      <td>Ambiance API Password</td>
      <td>1234</td>
    </tr>

    <tr>
      <td>Client ID</td>
      <td>ABC123ABC</td>
    </tr>

    <tr>
      <td>Client Secret</td>
      <td>ABC123ABC</td>
    </tr>
  </tbody>
</table>

***


# Dormakaba Community Setup Guide
Source: https://docs.seam.co/device-and-system-integration-guides/dormakaba-community-access-control-system/dormakaba-community-setup-guide

Learn how to configure your Dormakaba Community access control system for integration with Seam.

To connect a Dormakaba Community system to Seam, the system administrator must perform a set of setup steps on the computer where the Community server is running.

The setup process has three parts:

1. [**Prepare Community**](#prepare-community-for-seam-integration) – Install the Seam Bridge, enable the Community API, turn on API authentication, and create a dedicated Operator Administrator account.
2. [**Enable Mobile Keys**](#enable-mobile-keys-in-community) – Work with Dormakaba Technical Support to purchase a mobile keys license and link your property to Seam’s LEGIC account.
3. [**Connect Community to Seam**](#connect-community-to-seam) – Use the Seam Connect Webview to pair the Seam Bridge, enter Operator Administrator login credentials, and establish the API connection.

***

## Prepare Community for Seam Integration

1. Install Seam Bridge
   1. Install the [Seam Bridge](/capability-guides/seam-bridge) on the computer hosting the Community System.
2. Enable Community API
   1. Go to **System Settings** > **Community API**.<br />
   2. **Enable Community REST API**.
   3. Create a **Client ID** (max 32 characters) and **Secret Key** (max 512 characters).
   4. Enter these values in the Community API settings, and save these settings.
   5. These values are required later to connect Community to Seam via the Connect Webview.
3. **Enable API Authentication**
   1. Go to **System Settings** > **Security** > **API Integration**.
   2. **Enable API Authentication**.<br />
4. **Set up a New Operator Administrator User for Seam Integration**
   1. Under the top dropdown next to the dormakaba logo, select **Staff/Vendor Management**.
   2. Click **New Staff Member**.
   3. Fill out the required profile details (first name, last name, role, etc.).
   4. Assign this staff member the role of **Operator Administrator** so they have admin-level control of the Community system.
   5. In the new staff profile, go to the **Operator Info** tab.
   6. Under **Local Login**, create a **Username** and **Password** for this Operator Administrator.
      * These values are used later to connect Community to Seam via the Connect Webview.
   7. Still in the **Operator Info** tab, scroll to the **API Login** section.
   8. Click **Add/Update Username & Password**.
   9. Create a unique API username and password.
      * These values are required later to connect Community to Seam via the Connect Webview.
   10. Click the **Save** icon in the top-right corner to confirm changes.

***

## Enable Mobile Keys in Community

1. Contact Dormakaba Technical Support at **+1 (800) 999-6213** to begin the Mobile Key License procurement and setup process.
   1. After selecting your language, follow the menu prompts: **Technical Support** → **Product Support** → **Multihousing** → **Community**.
2. Inform them you are utilizing **Seam’s integration for Dormakaba Community Mobile Keys**.
3. Dormakaba will connect your Community property to Seam’s LEGIC account and provide you with a **Project ID** and **API Key**.
4. In Community, go to **System Settings** > **Advanced** > **Mobile Keys** > **LEGIC Configuration Settings** and enter the **Project ID** and **API Key**.
5. Enter **"[https://integration.legicconnect.com](https://integration.legicconnect.com)"** as the **Endpoint address**.
6. Click **Test LEGIC connection settings** to confirm that the settings were set correctly.
7. Click the **Save** icon in the top-right corner to save the changes.

***

## Connect Community to Seam

1. **Pair Seam Bridge**
   * Make sure **Seam Bridge** is running.
   * In the Connect Webview, enter the **pairing code** from the top-right corner of the Seam Bridge app.
2. **Enter Operator Administrator login**
   * Use the same **username** and **password** you use to log in locally to Community.
   * For the system URL, run `ipconfig` in Command Prompt and use your computer’s IPv4 Address.
3. **Enter API credentials**
   * In the Connect Webview, enter the **Client ID** and **Secret Key** you created in the Community API settings.
   * Enter the **API Username and Password** you created for the Operator Administrator.
4. Click **Submit** to finish connecting Community to Seam.

***


# Dormakaba Community Access Control System
Source: https://docs.seam.co/device-and-system-integration-guides/dormakaba-community-access-control-system/index

Guide for using the Dormakaba Community Access Control System with Seam

<img alt="Community logo" />

***

## Overview

Connect your Dormakaba Community system to Seam to automate access and enable mobile credentials across your properties. Seam provides a single API and management layer, so you can integrate Community directly into your PMS, resident app, or hospitality platform.

This integration automates access for new visitors and residents, making it easy to issue Bluetooth mobile keys, encode cards, or deliver wallet-based keys without manual steps. Credentials can be set to automatically expire, keeping building access secure.

In multifamily settings, property managers often use this integration to streamline move-ins and guest access. When a new resident is added in your property management system, Seam can automatically create their profile in Dormakaba Community and provision the right credentials. Visitors can also be issued temporary mobile keys that work instantly and expire once their visit is over. This reduces operational overhead while creating a smoother, more welcoming experience for residents and guests.

<Info>
  **Before you begin**

  Follow the [Dormkaba Community Setup Guide](./dormakaba-community-setup-guide) to configure your Community system settings and connect it to Seam.
</Info>

***

## Key Benefits

* Automated access – Issue Bluetooth, card, or wallet-based keys without manual steps.
* Secure credentials – Set keys to automatically expire after move-out or visit end.
* Faster move-ins – Seam creates resident profiles and provisions credentials directly from your PMS.
* Streamlined visitor access – Provide visitors with instant, temporary mobile keys that expire automatically.
* Reduced overhead – Eliminate manual key management while improving the resident and guest experience.

***

## Supported Devices

<DeviceList />

This integration supports all wireless locks and readers connected to the Dormakaba Community system.

***

## Related Features

* [**Access Grants**](/use-cases/granting-access/reservation-access-grants) – The universal way to manage access in Seam. Integrate once, and your access model works consistently across all providers, including Dormakaba Community. For advanced, low-level control, you can still work directly with the ACS API.
* [**Mobile Keys**](/capability-guides/mobile-access) – Provision and revoke Bluetooth and wallet-based credentials directly from your PMS or app.
* [**Instant Keys**](/use-cases/granting-access/using-instant-keys) - Instantly issue temporary mobile pass that is shareable via an email or text.
* [**Plastic Card Encoding**](/api/acs/encoders/encode_credential) – Encode and issue physical access cards using Seam’s card management API.

***

## Connecting Dormakaba Ambiance to Seam

To enable your users to [connect a Community system through Connect Webviews](/core-concepts/connect-webviews/customizing-connect-webviews#customize-the-brands-to-display-in-your-connect-webviews), include the Dormakaba Community provider:

```json theme={null}
{
}
```

After the system admin completes the setup steps, they can enter their credentials into the Seam Connect form to complete the connection.

[→ See: Dormakaba Community Setup Guide](../lockly-locks/lockly-setup-guide)

***

## Brand-Specific Restrictions

Note the following restrictions on the Community system:

* Dormakaba Community locks do not support remote web unlock. Unlock operations must occur through a mobile app or using a plastic card.

***

## Where to Order

To purchase the Dormakaba Community access system, locate an installer near the property.

<CardGroup>
  <Card title="Connect your Dormakaba Community system to Seam" href="/device-and-system-integration-guides/dormakaba-community-access-control-system/dormakaba-community-setup-guide">
    Follow the setup guide to prepare your Dormakaba Community system and enable
    API access.
  </Card>

  <Card title="Certified Installers Page" href="https://www.dormakaba.com/us-en/certified-installers">
    Find an installer for Community products at your property.
  </Card>
</CardGroup>

***


# Sandbox Dormakaba Community Access Control System
Source: https://docs.seam.co/device-and-system-integration-guides/dormakaba-community-access-control-system/sandbox-dormakaba-community-access-control-system

Add a virtual Dormakaba Community access control system to your Seam sandbox workspace using these Connect Webview credentials to test your integration.

Use the following set of credentials to add virtual [Dormakaba Community Access Control System](/device-and-system-integration-guides/dormakaba-community-access-control-system)-connected devices to your Seam [sandbox workspace](/core-concepts/workspaces#sandbox-workspaces):

<Info>
  To use the virtual Community Access Control System (ACS) to issue mobile keys
  in a sandbox workspace, you must also connect a LEGIC Connect account.
</Info>

## Dormakaba Connect Webview Credentials

#### 1. Bridge connection pane

| Pairing Token            |
| ------------------------ |
| *<mark>prefilled</mark>* |

#### 2. Dormakaba Community Dashboard Credentials

<table>
  <thead>
    <tr>
      <th>Field</th>
      <th>Value</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>PMS Operator Username</td>
      <td>jane</td>
    </tr>

    <tr>
      <td>PMS Operator Password</td>
      <td>1234</td>
    </tr>

    <tr>
      <td>Ambiance Server IP Address</td>

      <td>
        <em>
          <mark>prefilled</mark>
        </em>
      </td>
    </tr>
  </tbody>
</table>

#### 3. Dormakaba Community API Credentials

<table>
  <thead>
    <tr>
      <th>Field</th>
      <th>Value</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Client ID</td>
      <td>ABC123ABC</td>
    </tr>

    <tr>
      <td>Client Secret</td>
      <td>ABC123ABC</td>
    </tr>

    <tr>
      <td>Community API Username</td>
      <td>jane</td>
    </tr>

    <tr>
      <td>Community API Password</td>
      <td>1234</td>
    </tr>
  </tbody>
</table>

***


# Creating dormakaba Oracode Offline Access Codes
Source: https://docs.seam.co/device-and-system-integration-guides/dormakaba-oracode-locks/creating-dormakaba-oracode-offline-access-codes

Learn how to create dormakaba Oracode offline access codes, including understanding manufacturer-specific requirements.

The Seam integration for dormakaba Oracode enables you to manage [offline access codes](/low-level-apis/smart-locks/access-codes/offline-access-codes) for dormakaba Oracode locks. You generate offline access (PIN) codes remotely, and the manufacturer maintains a server-based registry of synchronized encryption keys (tokens) to enable these offline codes. Then, owners or managers can share these codes with users through messaging or other similar applications, and the users do not need to install a special application to unlock the device.

To learn about the special requirements regarding offline access codes for dormakaba Oracode locks, see [Offline Access Code Requirements](#offline-access-code-requirements). For more information about using offline access codes, see [Offline Access Codes](/low-level-apis/smart-locks/access-codes#offline-access-codes) and [Managing Offline Access Codes](/low-level-apis/smart-locks/access-codes/offline-access-codes).

***

## Offline Access Code Requirements

Seam supports daily-bound and hourly-bound [offline access codes](/low-level-apis/smart-locks/access-codes/offline-access-codes) for dormakaba Oracode locks. Note the following dormakaba Oracode-specific restrictions and requirements for offline access codes:

### Duration

The duration limit for a dormakaba Oracode offline access code is 31 consecutive days.

### Deletion and Access Code Limits

You cannot delete dormakaba Oracode offline access codes. Consequently, it is important to be aware of device- and installation-specific access code limits, especially if you plan to create large numbers of codes simultaneously. For more information about these limits, see the user manual for your dormakaba Oracode lock or contact your dormakaba Oracode support representative.

### User Levels

dormakaba Oracode locks use pre-programmed sets of access code time slots called "user levels" or "user prefixes." All the access codes in a specific user level have the same prefix, for example, `123` in `123456789` and `123987654`. Further, all access codes in a specific user level use the same configuration for the following characteristics:

* Check in and check out time
* Whether the access code is a one-time-use code
* Whether the access code is daily-bound (`is_24_hour`)
* Whether the access code is a biweekly code (that is, a code that is valid for two weeks)
* Whether the access code is a master code that exists indefinitely, for example, for site owners

When you create a dormakaba Oracode offline access code, you must set the duration of the code to match—exactly—one of the time slots on the device. To view a list of all available time slots for a specific device, [get the device](/api/devices/get) and view the `device.properties.dormakaba_oracode_metadata.predefined_time_slots` property for the device.

```json theme={null}
"predefined_time_slots": [
  {
      "name": "Guest RCI D 7am-7pm",
      "prefix": 0,
      "is_master": false,
      "is_24_hour": false,
      "is_one_shot": false,
      "check_in_time": "07:00:00[America/Los_Angeles]",
      "check_out_time": "19:00:00[America/Los_Angeles]",
      "is_biweekly_mode": false,
      "dormakaba_oracode_user_level_id": "f23721ec-6dce-4c54-8971-40d58449a366",
      "ext_dormakaba_oracode_user_level_prefix": 0
  },
  ...
]
```

### Time Zones

All time zone configuration and display for dormakaba Oracode locks occur in the local time zone of the lock, itself. When you [connect your dormakaba Oracode site to Seam](/device-and-system-integration-guides/dormakaba-oracode-locks/index#setup-instructions) initially, you specify the time zone in which the site is located. Consequently, when you configure an access code for a dormakaba Oracode lock, you set the `starts_at` and `ends_at` properties using a time and offset that match the local time zone of the lock.

For example, suppose that your lock includes the following user level:

```json theme={null}
"check_in_time": "07:00:00[America/Los_Angeles]",
"check_out_time": "19:00:00[America/Los_Angeles]"
```

To set an access code that uses this user level, set the times for the `starts_at` and `ends_at` properties as follows:

```json theme={null}
"starts_at": "2024-09-10T07:00:00-07:00",
"ends_at": "2024-09-15T19:00:00-07:00"
```

#### View the Time Zone of a dormakaba Oracode Lock

To view the local time zone of a dormakaba Oracode lock, [get the device](/api/devices/get) and see the `check_in_time` and `check_out_time` within each time slot in the `device.properties.dormakaba_oracode_metadata.predefined_time_slots` property for the device. You can also see the local time zone for a dormakaba Oracode lock in the `dormakaba_oracode_device_metadata.iana_timezone` property.

### Master Codes

Seam does not currently support dormakaba Oracode master offline access codes.

### One-Time-Use Codes

Seam does not currently support dormakaba Oracode one-time-use offline access codes.

***

## Programming dormakaba Oracode Offline Access Codes

You can create hourly- and daily-bound offline access codes for dormakaba Oracode devices.

### Hourly-Bound Offline Access Codes

To [create an hourly-bound offline access code](/low-level-apis/smart-locks/access-codes/offline-access-codes#creating-time-bound-offline-access-codes), issue an access code creation request. Then, poll or use a webhook to confirm that the code was registered successfully in the dormakaba Oracode offline access code server.

#### 1. Create an Hourly-Bound Offline Access Code

To create an hourly-bound offline access code, provide the `device_id` of the lock for which you want to create the code and set `is_offline_access_code` to `true`. Specify the `starts_at` and `ends_at` [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) timestamps to define the active time window for the offline code. Make sure to set the duration of the code to match—exactly—one of the [user levels](#user-levels) on the device. You can also assign an optional `name` to the offline access code.

<Info>
  Make sure to set the `starts_at` and `ends_at` times and offsets to match the
  local time zone of the lock, as configured when the corresponding [dormakaba
  Oracode site was connected to Seam](/device-and-system-integration-guides/dormakaba-oracode-locks/index#setup-instructions).
</Info>

For more details, see the [Create Access Code endpoint](/api/access_codes/create).

**Request:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  // Get the device.
  const device = await seam.locks.get({
    device_id: '11111111-1111-1111-1111-444444444444',
  })

  // Confirm that the device supports offline access codes.
  if (device.can_program_offline_access_codes) {
    // Create the hourly-bound offline access code.
    await seam.accessCodes.create({
      device_id: device.device_id,
      name: 'my hourly-bound offline code',
      // Make sure that the validity period matches
      // a user level for the device.
      starts_at: '2024-09-10T07:00:00-07:00',
      ends_at: '2024-09-15T19:00:00-07:00',
      is_offline_access_code: true,
    })
  }
  ```

  ```sh cURL theme={null}
  # 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 offline access codes.
  if  $(jq -r '.device.can_program_offline_access_codes' <<< ${device}); then \
    # Create the hourly-bound offline access code.
    # Make sure that the validity period matches
    # a user level for the device.
    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 hourly-bound offline code\",
        \"starts_at\": \"2024-09-10T07:00:00-07:00\",
        \"ends_at\": \"2024-09-15T19:00:00-07:00\",
        \"is_offline_access_code\": true
    }";
  fi
  ```

  ```python Python theme={null}
  # Get the device.
  device = seam.locks.get(
    device_id="11111111-1111-1111-1111-444444444444"
  )

  # Confirm that the device supports offline access codes.
  if device.can_program_offline_access_codes:
    # Create the hourly-bound offline access code.
    seam.access_codes.create(
      device_id = device.device_id,
      name = "my hourly-bound offline code",
      # Make sure that the validity period matches
      # a user level for the device.
      starts_at = "2024-09-10T07:00:00-07:00",
      ends_at = "2024-09-15T19:00:00-07:00",
      is_offline_access_code = True
    )
  ```

  ```ruby Ruby theme={null}
  # Get the device.
  device = client.locks.get(device_id: "11111111-1111-1111-1111-444444444444")

  # Confirm that the device supports offline access codes.
  if (device.can_program_offline_access_codes)
    # Create the hourly-bound offline access code.
    client.access_codes.create(
      device_id: device.device_id,
      name: "my hourly-bound offline code",
      # Make sure that the validity period matches
      # a user level for the device.
      starts_at: "2024-09-10T07:00:00-07:00",
      ends_at: "2024-09-15T19:00:00-07:00",
      is_offline_access_code: true
    )
  end
  ```

  ```php PHP theme={null}
  // Get the device.
  $device = $seam->locks->get(device_id: "11111111-1111-1111-1111-444444444444");

  // Confirm that the device supports offline access codes.
  if ($device->can_program_offline_access_codes) {
    // Create the hourly-bound offline access code.
    $seam->access_codes->create(
      device_id: $device->device_id,
      name: "my hourly-bound offline code",
      // Make sure that the validity period matches
      // a user level for the device.
      starts_at: "2024-09-10T07:00:00-07:00",
      ends_at: "2024-09-15T19:00:00-07:00",
      is_offline_access_code: true
    );
  }
  ```

  ```csharp C# theme={null}
  // Get the device.
  Device device = seam.Locks.Get(deviceId: "11111111-1111-1111-1111-444444444444");

  // Confirm that the device supports offline access codes.
  if (device.CanProgramOfflineAccessCodes == true) {
    // Create the hourly-bound offline access code.
    seam.AccessCodes.Create(
      deviceId: device.DeviceId,
      name: "my hourly-bound offline code",
      // Make sure that the validity period matches
      // a user level for the device.
      startsAt: "2024-09-10T07:00:00-07:00",
      endsAt: "2024-09-15T19:00:00-07:00",
      isOfflineAccessCode: true
    );
  }
  ```
</CodeGroup>

**Response:**

<CodeGroup>
  ```json JavaScript theme={null}
  {
    access_code_id: '11111111-1111-1111-1111-777777777777',
    device_id: '11111111-1111-1111-1111-444444444444',
    name: 'my hourly-bound offline code',
    type: 'time_bound',
    starts_at: '2024-09-10T14:00:00.000Z',
    ends_at: '2024-09-16T02:00:00.000Z',
    is_offline_access_code: true,
    ...
  }
  ```

  ```json cURL theme={null}
  {
    "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-777777777777",
      "device_id": "11111111-1111-1111-1111-444444444444",
      "name": "my hourly-bound offline code",
      "type": "time_bound",
      "starts_at": "2024-09-10T14:00:00.000Z",
      "ends_at": "2024-09-16T02:00:00.000Z",
      "is_offline_access_code": true,
      ...
    },
    "ok": true
  }
  ```

  ```json Python theme={null}
  AccessCode(
    access_code_id='11111111-1111-1111-1111-777777777777',
    device_id='11111111-1111-1111-1111-444444444444',
    type='time_bound',
    starts_at='2024-09-10T14:00:00.000Z',
    ends_at='2024-09-16T02:00:00.000Z',
    name='my hourly-bound offline code',
    is_offline_access_code=True,
    ...
  )
  ```

  ```json Ruby theme={null}
  <Seam::AccessCode:0x00438
    access_code_id="11111111-1111-1111-1111-777777777777"
    device_id="11111111-1111-1111-1111-444444444444"
    name="my hourly-bound offline code"
    type="time_bound"
    starts_at=2024-09-10 14:00:00 UTC
    ends_at=2024-09-16 02:00:00 UTC
    is_offline_access_code: true
    ...
  >
  ```

  ```json PHP theme={null}
  {
    "access_code_id": "11111111-1111-1111-1111-777777777777",
    "device_id": "11111111-1111-1111-1111-444444444444",
    "name": "my hourly-bound offline code",
    "type": "time_bound",
    "starts_at": "2024-09-10T14:00:00.000Z",
    "ends_at": "2024-09-16T02:00:00.000Z",
    "is_offline_access_code": true,
    ...
  }
  ```

  ```json C# theme={null}
  {
    "type": "time_bound",
    "access_code_id": "11111111-1111-1111-1111-777777777777",
    "device_id": "11111111-1111-1111-1111-444444444444",
    "name": "my hourly-bound offline code",
    "starts_at": "2024-09-10T14:00:00.000Z",
    "ends_at": "2024-09-16T02:00:00.000Z",
    "is_offline_access_code": true,
    ...
  }
  ```
</CodeGroup>

#### 2. Verify Successful Time-Bound Code Registration

The [lifecycle of a time-bound access code](/low-level-apis/smart-locks/access-codes/lifecycle-of-access-codes) is marked by distinct phases:

1. `Unset`: When initially created on Seam, the offline access code remains in an `unset` state, indicating that it is not yet available for use on the lock due to a configured future activation time.
2. `Setting`: As the scheduled `starts_at` time approaches, Seam initiates the process of readying the code for use on the lock, transitioning the `status` of the offline code to `setting`.
3. `Set`: Upon successful programming, the status updates to `set`, signaling that the code is ready to grant the designated user the ability to unlock the door.

There are two methods to verify that an time-bound offline access code has been registered in the offline access code server that the device manufacturer maintains:

* **Polling**: Continuously query the access code until the `status` is updated. For instructions, see [Polling Method](/low-level-apis/smart-locks/access-codes/creating-access-codes#polling-method).
* **Webhook**: Wait for updates to arrive using webhook requests from the Seam API. For instructions, see [Webhook Events Method](/low-level-apis/smart-locks/access-codes/creating-access-codes#webhook-events-method).

***

### Daily-Bound Offline Access Codes

To [create a daily-bound offline access code](/low-level-apis/smart-locks/access-codes/offline-access-codes#creating-time-bound-offline-access-codes), first issue a creation request. Then, poll or use a webhook to confirm that the code was registered successfully in the dormakaba Oracode offline access code server.

#### 1. Create a Daily-Bound Access Code

To create a daily-bound offline access code, provide the `device_id` of the lock for which you want to create the code and set `is_offline_access_code` to `true`. Specify the `starts_at` and `ends_at` [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) timestamps to define the active time window for the offline code. Make sure to set the duration of the code to match—exactly—one of the [user levels](#user-levels) on the device. For a daily-bound offline access code, you must specify the same time (but not the same date) in the `starts_at` and `ends_at` properties.

<Info>
  Make sure to set the `starts_at` and `ends_at` times and offsets to match the
  local time zone of the lock, as configured when the corresponding [dormakaba
  Oracode site was connected to Seam](/device-and-system-integration-guides/dormakaba-oracode-locks/index#setup-instructions).
</Info>

Because daily-bound offline access codes require day-level duration granularity, you can also set `max_time_rounding` to `1day` (or `1d`), instead of the default `1hour` (or `1h`). Note that the Seam API returns an error if `max_time_rounding` is `1hour` and the necessary rounding amount exceeds one hour.

You can also assign an optional `name` to the offline access code. For more details, see the [Create Access Code endpoint](/api/access_codes/create).

**Request:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  // Get the device.
  const device = await seam.locks.get({
    device_id: '11111111-1111-1111-1111-444444444444',
  })

  // Confirm that the device supports offline access codes.
  if (device.can_program_offline_access_codes) {
    // Create the daily-bound offline access code.
    await seam.accessCodes.create({
      device_id: device.device_id,
      name: 'my daily-bound offline code',
      // Make sure that the validity period matches
      // a user level for the device.
      starts_at: '2024-09-16T00:00:00-07:00',
      ends_at: '2024-09-18T23:59:00-07:00',
      max_time_rounding: '1d',
      is_offline_access_code: true,
    })
  }
  ```

  ```sh cURL theme={null}
  # 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 offline access codes.
  if  $(jq -r '.device.can_program_offline_access_codes' <<< ${device}); then \
    # Create the daily-bound offline access code.
    # Make sure that the validity period matches
    # a user level for the device.
    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 daily-bound offline code\",
        \"starts_at\": \"2024-09-16T00:00:00-07:00\",
        \"ends_at\": \"2024-09-18T23:59:00-07:00\",
        \"max_time_rounding\": \"1d\",
        \"is_offline_access_code\": true
    }";
  fi
  ```

  ```python Python theme={null}
  # Get the device.
  device = seam.locks.get(
    device_id="11111111-1111-1111-1111-444444444444"
  )

  # Confirm that the device supports offline access codes.
  if device.can_program_offline_access_codes:
    # Create the daily-bound offline access code.
    seam.access_codes.create(
      device_id = device.device_id,
      name = "my daily-bound offline code",
      # Make sure that the validity period matches
      # a user level for the device.
      starts_at = "2024-09-16T00:00:00-07:00",
      ends_at = "2024-09-18T23:59:00-07:00",
      max_time_rounding = "1d",
      is_offline_access_code = True
    )
  ```

  ```ruby Ruby theme={null}
  # Get the device.
  device = client.locks.get(device_id: "11111111-1111-1111-1111-444444444444")

  # Confirm that the device supports offline access codes.
  if (device.can_program_offline_access_codes)
    # Create the daily-bound offline access code.
    client.access_codes.create(
      device_id: device.device_id,
      name: "my daily-bound offline code",
      # Make sure that the validity period matches
      # a user level for the device.
      starts_at: "2024-09-16T00:00:00-07:00",
      ends_at: "2024-09-18T23:59:00-07:00",
      max_time_rounding: "1d",
      is_offline_access_code: true
    )
  end
  ```

  ```php PHP theme={null}
  // Get the device.
  $device = $seam->locks->get(device_id: "11111111-1111-1111-1111-444444444444");

  // Confirm that the device supports offline access codes.
  if ($device->can_program_offline_access_codes) {
    // Create the daily-bound offline access code.
    $seam->access_codes->create(
      device_id: $device->device_id,
      name: "my daily-bound offline code",
      // Make sure that the validity period matches
      // a user level for the device.
      starts_at: "2024-09-16T00:00:00-07:00",
      ends_at: "2024-09-18T23:59:00-07:00",
      max_time_rounding: "1d",
      is_offline_access_code: true
    );
  }
  ```

  ```csharp C# theme={null}
  // Get the device.
  Device device = seam.Locks.Get(deviceId: "11111111-1111-1111-1111-444444444444");

  // Confirm that the device supports offline access codes.
  if (device.CanProgramOfflineAccessCodes == true) {
    // Create the daily-bound offline access code.
    seam.AccessCodes.Create(
      deviceId: device.DeviceId,
      name: "my daily-bound offline code",
      // Make sure that the validity period matches
      // a user level for the device.
      startsAt: "2024-09-16T00:00:00-07:00",
      endsAt: "2024-09-18T23:59:00-07:00",
      maxTimeRounding: "1d",
      isOfflineAccessCode: true
    );
  }
  ```
</CodeGroup>

**Response:**

<CodeGroup>
  ```json JavaScript theme={null}
  {
    access_code_id: '11111111-1111-1111-1111-888888888888',
    device_id: '11111111-1111-1111-1111-444444444444',
    name: 'my daily-bound offline code',
    type: 'time_bound',
    starts_at: '2024-09-16T07:00:00.000Z',
    ends_at: '2024-09-19T06:59:00.000Z',
    is_offline_access_code: true,
    ...
  }
  ```

  ```json cURL theme={null}
  {
    "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-888888888888",
      "device_id": "11111111-1111-1111-1111-444444444444",
      "name": "my daily-bound offline code",
      "type": "time_bound",
      "starts_at": "2024-09-16T07:00:00.000Z",
      "ends_at": "2024-09-19T06:59:00.000Z",
      "is_offline_access_code": true,
      ...
    },
    "ok": true
  }
  ```

  ```json Python theme={null}
  AccessCode(
    access_code_id='11111111-1111-1111-1111-888888888888',
    device_id='11111111-1111-1111-1111-444444444444',
    type='time_bound',
    starts_at='2024-09-16T07:00:00.000Z',
    ends_at='2024-09-19T06:59:00.000Z',
    name='my daily-bound offline code',
    is_offline_access_code=True,
    ...
  )
  ```

  ```json Ruby theme={null}
  <Seam::AccessCode:0x00438
    access_code_id="11111111-1111-1111-1111-888888888888"
    device_id="11111111-1111-1111-1111-444444444444"
    name="my daily-bound offline code"
    type="time_bound"
    starts_at=2024-09-16 07:00:00.00 UTC
    ends_at=2024-09-19 06:59:00.00 UTC
    is_offline_access_code: true
    ...
  >
  ```

  ```json PHP theme={null}
  {
    "access_code_id": "11111111-1111-1111-1111-888888888888",
    "device_id": "11111111-1111-1111-1111-444444444444",
    "name": "my daily-bound offline code",
    "type": "time_bound",
    "starts_at": "2024-09-16T07:00:00.000Z",
    "ends_at": "2024-09-19T06:59:00.000Z",
    "is_offline_access_code": true,
    ...
  }
  ```

  ```json C# theme={null}
  {
    "type": "time_bound",
    "access_code_id": "11111111-1111-1111-1111-888888888888",
    "device_id": "11111111-1111-1111-1111-444444444444",
    "name": "my daily-bound offline code",
    "starts_at": "2024-09-16T07:00:00.000Z",
    "ends_at": "2024-09-19T06:59:00.000Z",
    "is_offline_access_code": true,
    ...
  }
  ```
</CodeGroup>

#### 2. Verify Successful Time-Bound Code Registration

The [lifecycle of a time-bound access code](/low-level-apis/smart-locks/access-codes/lifecycle-of-access-codes) is marked by distinct phases:

1. `Unset`: When initially created on Seam, the offline access code remains in an `unset` state, indicating that it is not yet available for use on the lock due to a configured future activation time.
2. `Setting`: As the scheduled `starts_at` time approaches, Seam initiates the process of readying the code for use on the lock, transitioning the `status` of the offline code to `setting`.
3. `Set`: Upon successful programming, the status updates to `set`, signaling that the code is ready to grant the designated user the ability to unlock the door.

There are two methods to verify that an time-bound offline access code has been registered in the offline access code server that the device manufacturer maintains:

* **Polling**: Continuously query the access code until the `status` is updated. For instructions, see [Polling Method](/low-level-apis/smart-locks/access-codes/creating-access-codes#polling-method).
* **Webhook**: Wait for updates to arrive using webhook requests from the Seam API. For instructions, see [Webhook Events Method](/low-level-apis/smart-locks/access-codes/creating-access-codes#webhook-events-method).


# Sandbox Dormakaba Oracode Locks
Source: https://docs.seam.co/device-and-system-integration-guides/dormakaba-oracode-locks/dormakaba-oracode-sample-data

Add virtual Dormakaba Oracode locks to your Seam sandbox workspace using these sample credentials to test your integration without real hardware.

Use the following set of credentials to add virtual [Dormakaba Oracode locks](/device-and-system-integration-guides/dormakaba-oracode-locks) to your Seam [sandbox workspace](/core-concepts/workspaces#sandbox-workspaces):

| Username | Site                  | Time Zone |
| -------- | --------------------- | --------- |
| jane     | Ocean Beach Vacations | Any       |


# Dormakaba Oracode Setup Guide
Source: https://docs.seam.co/device-and-system-integration-guides/dormakaba-oracode-locks/dormakaba-oracode-setup-guide

Connect your Dormakaba Oracode devices to Seam by identifying your Oracode Live sites and asking Dormakaba support to link them to Seam.

To control Dormakaba Oracode devices using Seam, you must prompt the owners or managers of these devices to perform the following steps:

1. **Identify your Oracode Live sites**\
   For each site:
   * Log in to your [Oracode Live account](https://www.kabaecodewireless.com).
   * Note your site name, as shown in the upper-right corner of the Oracode Live portal.

2. **Contact** [**Dormakaba Oracode Support**](mailto:oracode@dormakaba.com)\
   Ask them to to connect your Oracode sites to Seam.

   \
   Sample Email:

   > *Please connect the following sites to the Seam Access Token:*
   >
   > * *\{Insert Site Name}*
   > * *\{Insert Site Name}*

3. **Connect your devices via Seam**\
   In the Connect Webview, enter your dormakaba Oracode username and a comma-separated list of your site names. For each site, select the correct local time zone.

   > **Important:** Site names and time zones must be entered exactly. An incorrect site name will cause the connection to fail. An incorrect timezone will cause access codes to start and end at the wrong times.

4. **Request activation from Seam**\
   Contact [support@getseam.com](mailto:support@getseam.com) to request approval and activation of your Dormakaba Oracode integration.

***

### **Fixing an incorrect time zone**

If you connected a site with the wrong time zone:

1. Start a new Connect Webview.
2. Re-enter your username and site name, then select the correct time zone.


# Get started with dormakaba Oracode Locks
Source: https://docs.seam.co/device-and-system-integration-guides/dormakaba-oracode-locks/get-started-with-dormakaba-oracode-locks

Learn how to connect and control your dormakaba Oracode 480 and 660 locks with the Seam API.

## Overview

Seam provides a universal API to connect and control many brands of locks. This guide provides a rapid introduction to connecting and controlling your [dormakaba Oracode](https://www.seam.co/manufacturers/dormakaba) locks using the Seam API. To learn more about other device brands supported by the Seam API, such as Yale, Schlage, and August, head over to our [integration page](https://www.seam.co/supported-devices-and-systems).

Note that dormakaba offers multiple lines of products, including Lyazon, Sapphire, Oracode, and more. This guide is specifically for dormakaba Oracode.

## 1 — Install the Seam SDK

Seam provides client libraries for many languages, such as JavaScript, Python, Ruby, PHP, and others, as well as a Postman collection and [OpenAPI](https://connect.getseam.com/openapi.json) spec.

* JavaScript / TypeScript ([npm](https://www.npmjs.com/package/seam), [GitHub](https://github.com/seamapi/javascript))
* Python ([pip](https://pypi.org/project/seam/), [GitHub](https://github.com/seamapi/python))
* Ruby Gem ([rubygem](https://rubygems.org/gems/seam), [GitHub](https://github.com/seamapi/ruby))
* PHP ([packagist](https://packagist.org/packages/seamapi/seam), [GitHub](https://github.com/seamapi/php))
* Java ([GitHub](https://github.com/seamapi/java))
* C# ([nuget](https://www.nuget.org/packages/Seam), [GitHub](https://github.com/seamapi/csharp))
* Go ([GitHub](https://github.com/seamapi/go))

<Tabs>
  <Tab title="JavaScript">
    ```bash theme={null}
    npm i seam
    ```
  </Tab>

  <Tab title="Python">
    ```bash theme={null}
    pip install seam
    # For some development environments, use pip3 in this command instead of pip.
    ```
  </Tab>

  <Tab title="Ruby">
    ```bash theme={null}
    bundle add seam
    ```
  </Tab>

  <Tab title="PHP">
    ```bash theme={null}
    composer require seamapi/seam
    ```
  </Tab>

  <Tab title="C#">
    Install using [nuget](https://www.nuget.org/packages/Seam).
  </Tab>
</Tabs>

Once installed, [sign-up for Seam](https://console.seam.co/) to get your API key, and export it as an environment variable:

```
$ export SEAM_API_KEY=seam_test2ZTo_0mEYQW2TvNDCxG5Atpj85Ffw
```

<Info>
  This guide uses a sandbox
  [workspace](/core-concepts/workspaces). You can
  only connect virtual devices to a sandbox workspace. If you need to connect
  real Oracode devices, use a non-sandbox workspace and API key.
</Info>

## 2 — Link Your dormakaba Oracode Account with Seam

To control your dormakaba Oracode locks using the Seam API, the owner or manager of these locks must first authorize your Seam workspace to access their dormakaba Oracode account. To do so, Seam provides[ Connect Webviews](/core-concepts/connect-webviews), which are pre-built UX flows that walk the device owner or manager through authorizing your application to control Oracode locks.

<Info>
  This guide discusses using a Seam sandbox workspace with virtual devices.
  However, to connect real devices to Seam, some manufacturers may require
  additional prerequisite setup steps. For dormakaba Oracode-specific
  instructions, see the [dormakaba Oracode device integration
  guide](/device-and-system-integration-guides/dormakaba-oracode-locks#setup-instructions).
</Info>

#### Request a Connect Webview

<CodeGroup>
  ```javascript JavaScript theme={null}
  import { Seam } from 'seam'

  const seam = new Seam()

  const { connect_webview: connectWebview } = await seam.connectWebviews.create()

  console.log(connectWebview.login_successful) // false

  // Send the Connect Webview URL to your user.
  console.log(connectWebview.url)

  ```

  ```python Python theme={null}
  from seam import Seam

  seam = Seam()

  webview = seam.connect_webviews.create()

  assert webview.login_successful is False

  # Send the Connect Webview URL to your user.
  print(webview.url)
  ```

  ```ruby Ruby theme={null}
  require "seam"

  seam = Seam.new(api_key: 'MY_API_KEY')

  webview = seam.connect_webviews.create()

  puts webview.login_successful # false

  # Send the Connect Webview URL to your user.

  puts webview.url

  ```

  ```php PHP theme={null}
  use Seam\SeamClient;

  $seam = new SeamClient("YOUR_API_KEY");

  $webview = $seam->connect_webviews->create();
  ```
</CodeGroup>

#### Authorize Your Workspace

Navigate to the URL that the Connect Webview object returned. Because you are using a sandbox workspace, complete the login flow by entering the following dormakaba Oracode [sandbox test account ](./dormakaba-oracode-sample-data)credentials:

* **username:** jane
* **site:** Ocean Beach Vacations
* **time zone:** (Any)

Confirm the Connect Webview was successful by querying the status.

<CodeGroup>
  ```javascript JavaScript theme={null}
  const updatedWebview = await seam.connectWebviews.get(
    connectWebview.connect_webview_id,
  )

  console.log(updatedWebview.login_successful) // true

  ```

  ```python Python theme={null}
  updated_webview = seam.connect_webviews.get(connect_webview_id: webview.connect_webview_id)

  assert updated_webview.login_successful # true
  ```

  ```ruby Ruby theme={null}
  updated_webview = seam.connect_webviews.get(connect_webview_id: webview.connect_webview_id)

  puts updated_webview.login_successful # true

  ```

  ```php PHP theme={null}
  $webview = $seam->connect_webviews->get('729847ff-98e0-418d-aeba-1e3cb38157c6');
  assert($webview->status == 'pending');
  ```
</CodeGroup>

## 3 — Retrieve dormakaba Oracode Devices

After a dormakaba Oracode account is linked with Seam, you can retrieve the connected devices.

<CodeGroup>
  ```javascript JavaScript theme={null}
  const allLocks = await seam.locks.list()

  const someLock = allLocks[0]

  console.log(someLock.properties.battery_level)

  console.log(someLock)

  ```

  ```python Python theme={null}
  all_locks = seam.locks.list()

  some_lock = all_locks[0]

  assert some_lock.properties["battery_level"] is True

  print(some_lock)
  ```

  ```ruby Ruby theme={null}
  some_lock = seam.locks.list.first

  puts some_lock.properties.battery_level

  puts some_lock

  ```

  ```php PHP theme={null}
  use Seam\SeamClient;

  $seam = new SeamClient('YOUR_API_KEY');

  $locks = $seam->locks->list();

  echo json_encode($locks);

  */
  ```
</CodeGroup>

### 4 — Programming Access Codes on a dormakaba Oracode Lock

The Seam API enables you to create offline access codes on dormakaba Oracode devices, such as the 480i and 660i locks. Users can then enter these codes to unlock the door. For detailed instructions, see [Creating dormakaba Oracode Offline Access Codes](./creating-dormakaba-oracode-offline-access-codes).

<Info>
  dormakaba Oracode does not let you specify a code for an access code. Instead
  it auto-generates a six-digit code, which the Seam API returns. If you try to
  pass the `code` argument to the access code `create` function, the Seam API
  returns an error.
</Info>

## Next Steps

Now that you've completed this guide, you can try to connect a real dormakaba Oracode device. To do so, make sure to switch to a non-sandbox workspace and API key because you cannot connect real devices to sandbox workspaces.

In addition, if you'd like to explore other aspects of Seam, check out the following helpful resources:

* [Schlage Getting Started Guide](../schlage-locks/get-started-with-schlage-locks)
* [Yale Getting Started Guide](../yale-locks/get-started-with-yale-locks)
* [SmartThings Getting Started Guide](../smartthings-hubs-+-devices/get-started-with-smartthings-hubs-+-smart-locks)
* [Configuring webhooks](/developer-tools/webhooks) for [device events](/api/events/list)
* [Core Concepts](/core-concepts/overview)

If you have any questions or want to report an issue, email us at [support@seam.co](mailto:support@seam.co).


# Dormakaba Oracode Locks
Source: https://docs.seam.co/device-and-system-integration-guides/dormakaba-oracode-locks/index

Guide for using dormakaba Oracode locks with Seam

<img alt="Oracode logo" />

## Overview

Seam integrates with the dormakaba [Oracode Live](https://www.dormakaba.com/us-en/offering/products/vacation-short-term-rental-solutions/access-control-management/oracode-live--ka_128503) access control management platform. Intended for the vacation and short-term rental industries, the Oracode Live platform supports a "no keys, no cards" concept for efficient and secure access. Further, with the Oracode Live platform, codes expire automatically at the end of the authorized period.

The Seam integration supports the generation of [offline access codes for dormakaba Oracode locks](/device-and-system-integration-guides/dormakaba-oracode-locks/creating-dormakaba-oracode-offline-access-codes).

You can use a variety of dormakaba Oracode smart locks with the Oracode Live platform. These strong and durable locks have commercial-grade finishes to withstand a wide range of climates.

***

## Supported Devices

<DeviceList />

This integration supports all locks connected using the [Oracode Live](https://www.dormakaba.com/us-en/offering/products/vacation-short-term-rental-solutions/access-control-management/oracode-live--ka_128503) platform. This integration supports [offline access code](/device-and-system-integration-guides/dormakaba-oracode-locks/creating-dormakaba-oracode-offline-access-codes) provisioning for applicable dormakaba Oracode devices.

For detailed information about the dormakaba Oracode devices that Seam supports, see our [dormakaba Supported Devices page](https://www.seam.co/manufacturers/dormakaba).

***

## Supported Features

We support the following features:

* [Programming offline access codes](/low-level-apis/smart-locks/access-codes/offline-access-codes)

***

### Device Provider Key

Seam identifies these devices with the `dormakaba_oracode` device provider key. By default, a [Connect Webview](/core-concepts/connect-webviews) displays all of the stable providers that Seam supports, so your users can connect their dormakaba Oracode devices without you specifying a provider list. To narrow what a Connect Webview displays, see [Customize the Brands to Display in Your Connect Webviews](/core-concepts/connect-webviews/customizing-connect-webviews#customize-the-brands-to-display-in-your-connect-webviews).

***

## Setup Instructions

For instructions on connecting dormakaba Oracode locks to Seam, see the [dormakaba Oracode Setup Guide](./dormakaba-oracode-setup-guide).

***

## Where to Order

To purchase dormakaba Oracode devices, contact the dormakaba Sales team using the dormakaba **Contact** page or order Oracode Live locks from GoKeyless.

<table>
  <thead>
    <tr>
      <th />

      <th />

      <th />

      <th />

      <th />
    </tr>
  </thead>

  <tbody>
    <tr>
      <td />

      <td>
        <strong>dormakaba Contact Page</strong>
      </td>

      <td />

      <td>
        <a href="https://www.dormakaba.com/us-en/contact">
          [https://www.dormakaba.com/us-en/contact](https://www.dormakaba.com/us-en/contact)
        </a>
      </td>

      <td>
        <a href="/images/dormakaba-logo.png">dormakaba-logo.png</a>
      </td>
    </tr>

    <tr>
      <td />

      <td>
        <strong>GoKeyless</strong>
      </td>

      <td />

      <td>
        <a href="https://www.gokeyless.com/shop/advertised/oracode-i-series-locks/">
          [https://www.gokeyless.com/shop/advertised/oracode-i-series-locks/](https://www.gokeyless.com/shop/advertised/oracode-i-series-locks/)
        </a>
      </td>

      <td>
        <a href="/images/gokeyless-logo.png">gokeyless-logo.png</a>
      </td>
    </tr>
  </tbody>
</table>

***


# Programming Offline Access Codes on Dormakaba Oracode Locks
Source: https://docs.seam.co/device-and-system-integration-guides/dormakaba-oracode-locks/programming-offline-access-codes-on-dormakaba-oracode-locks

Create offline access codes for Dormakaba Oracode locks that work without internet using time slots, and learn the requirements for programming them.

Dormakaba Oracode locks use offline access codes (PIN codes) that are generated remotely and work without requiring the lock to be online. This guide explains how to create these codes and the requirements you need to understand.

### Understanding Oracode offline access codes

[**Offline access codes**](/low-level-apis/smart-locks/access-codes/offline-access-codes) are PIN codes generated by Seam that work on the lock without an internet connection. Dormakaba maintains a server-based registry of synchronized encryption keys that enable these codes to work offline.

Once generated, you can share these codes with guests through messaging or your property management system—guests don't need to install any special app to unlock the door.

***

### Before you create codes

#### Time slot requirements (Required)

**Dormakaba Oracode locks require predefined time slots** (also called "user levels") to create access codes. You cannot create codes with arbitrary check-in/check-out times.

**What are time slots?**

Time slots define check-in and check-out times of day that are pre-configured by your Dormakaba installer. For example, a "4:00 PM → 10:00 AM" slot can be used for any booking that checks in at 4:00 PM and checks out at 10:00 AM, regardless of how many nights the guest stays.

**How Seam matches your bookings:**

When you create an access code, Seam automatically rounds your booking times (within 1 hour) to match an available time slot. The access code will use the time slot's times, not your exact booking times.

Example:

* Your booking: 3:45 PM → 10:15 AM
* Available slot: 4:00 PM → 10:00 AM
* Result: Code created for 4:00 PM → 10:00 AM ✓

If your booking times are more than 1 hour away from any configured slot, code creation will fail.

#### Retrieving available time slots

Before creating access codes, check which time slots are configured for your device:

<CodeGroup>
  ```javascript JavaScript theme={null}
  // Get device and time slots
  const device = await seam.devices.get({
    device_id: "your-device-id"
  });

  const timeSlots = device.properties.dormakaba_oracode_metadata?
    .predefined_time_slots || [];

  console.log(timeSlots)
  print(time_slots)
  [
    {
        "name": "Guest RCI D 7am-7pm",
        "prefix": 0,
        "is_master": false,
        "is_24_hour": false,
        "is_one_shot": false,
        "check_in_time": "07:00:00[America/Los_Angeles]",
        "check_out_time": "19:00:00[America/Los_Angeles]",
        "is_biweekly_mode": false,
        "dormakaba_oracode_user_level_id": "f23721ec-6dce-4c54-8971-40d58449a366",
        "ext_dormakaba_oracode_user_level_prefix": 0
    },
    ...
  ]

  ```

  ```python Python theme={null}
  # Get device and time slots
  device = seam.devices.get(device_id="your-device-id")
  time_slots = device.properties
      .get("dormakaba_oracode_metadata", {})
      .get("predefined_time_slots", [])

  print(time_slots)
  [
    {
        "name": "Guest RCI D 7am-7pm",
        "prefix": 0,
        "is_master": false,
        "is_24_hour": false,
        "is_one_shot": false,
        "check_in_time": "07:00:00[America/Los_Angeles]",
        "check_out_time": "19:00:00[America/Los_Angeles]",
        "is_biweekly_mode": false,
        "dormakaba_oracode_user_level_id": "f23721ec-6dce-4c54-8971-40d58449a366",
        "ext_dormakaba_oracode_user_level_prefix": 0
    },
    ...
  ]

  ```
</CodeGroup>

**Understanding time slot format:**

Time slots use Seam's Time of Day (TOD) format: `15:30:00-08:00[America/Los_Angeles]`

* `15:30:00` - Hour and minute (3:30 PM)
* `-08:00` - UTC offset
* `[America/Los_Angeles]` - IANA timezone

**Time slot properties:**

Each time slot includes:

* `name`: Display name (e.g., "Guest Standard 4pm-10am")
* `check_in_time`: Check-in time in TOD format
* `check_out_time`: Check-out time in TOD format
* `is_24_hour`: Whether this is a daily-bound slot
* `is_biweekly_mode`: Whether this uses biweekly scheduling
* `is_one_shot`: Whether code expires after first use (not currently supported)
* `is_master`: Whether this provides master access (not currently supported)

For detailed guidance on configuring time slots, see our [Time Slot Configuration Guide](https://seam-knowledge-base.help.usepylon.com/articles/3198102890-dormakaba-oracode-time-slot-configuration).

#### Other important limitations

**Duration limit:** Access codes can be valid for a maximum of 31 consecutive days.

**Cannot be updated or deleted:** Dormakaba Oracode access codes cannot be modified after creation. Be mindful of device-specific code limits when creating large numbers of codes.

**Time zone considerations:** All times must be in the lock's local time zone. When creating codes, use the time and offset that match the lock's configured time zone (e.g., `2024-09-10T16:00:00-07:00` for Pacific time).

**View device timezone:**

```python theme={null}
# Python
device = seam.devices.get(device_id="your-device-id")
timezone = device.properties.get("dormakaba_oracode_metadata", {}).get("iana_timezone")
print(f"Device timezone: {timezone}")
```

***

### Creating hourly-bound access codes

Hourly-bound codes let you specify exact check-in and check-out times (within the constraints of available time slots).

#### Step 1: Create the access code

Provide the `device_id`, set `is_offline_access_code` to `true`, and specify `starts_at` and `ends_at` timestamps. Make sure these times match a configured time slot on the device (within 1 hour tolerance).

**Python example:**

```python theme={null}
# Get the device
device = seam.locks.get(
  device_id="11111111-1111-1111-1111-444444444444"
)

# Confirm offline access code support
if device.can_program_offline_access_codes:
  # Create the code
  access_code = seam.access_codes.create(
    device_id=device.device_id,
    name="Guest - Room 101",
    starts_at="2024-09-10T16:00:00-07:00",  # Must match lock's timezone
    ends_at="2024-09-15T10:00:00-07:00",
    is_offline_access_code=True
  )

  print(f"Code created: {access_code.code}")
  print(f"Status: {access_code.status}")
```

#### Step 2: Verify the code was set

Access codes go through three lifecycle phases:

1. **Unset**: Code created but not yet active
2. **Setting**: Seam is registering the code with Dormakaba's server
3. **Set**: Code is ready to use

**Option A: Polling method**

```python theme={null}
import time

# Poll until status is 'set'
access_code = seam.access_codes.get(access_code_id="your-code-id")
while access_code.status != "set":
  time.sleep(1)
  access_code = seam.access_codes.get(access_code_id=access_code.access_code_id)

print(f"Code ready! PIN: {access_code.code}")
```

**Option B: Webhook method**

Subscribe to `access_code.set_on_device` webhook events to receive notifications when codes are ready.

***

### Creating daily-bound access codes

Daily-bound codes are useful when you need day-level granularity and want more flexible rounding.

#### Step 1: Create the access code

For daily-bound codes, specify the same time (but different dates) in `starts_at` and `ends_at`. You can also set `max_time_rounding` to `1day` to allow Seam to round up to a full day to match available slots.

<CodeGroup>
  ```javascript JavaScript theme={null}
  // Create daily-bound code
  const accessCode = await seam.accessCodes.create({
    device_id: device.device_id,
    name: 'Guest - Room 101',
    starts_at: '2024-09-16T00:00:00-07:00',
    ends_at: '2024-09-18T23:59:00-07:00',
    max_time_rounding: '1d', // Allow day-level rounding
    is_offline_access_code: true,
  })

  console.log(`Code created: ${accessCode.code}`)
  ```

  ```python Python theme={null}
  # Create daily-bound code
  access_code = seam.access_codes.create(
    device_id=device.device_id,
    name="Guest - Room 101",
    starts_at="2024-09-16T00:00:00-07:00",
    ends_at="2024-09-18T23:59:00-07:00",
    max_time_rounding="1d",  # Allow day-level rounding
    is_offline_access_code=True
  )

  print(f"Code created: {access_code.code}")
  ```
</CodeGroup>

#### Step 2: Verify the code was set

Use the same polling or webhook methods as hourly-bound codes to confirm the code is ready.

***

### Troubleshooting

**"No time slots found" error**

This means your booking times don't match any configured time slot within the 1-hour tolerance.

**Check what's configured:**

```python theme={null}
# List all time slots for debugging
device = seam.devices.get(device_id="your-device-id")
time_slots = device.properties.get("dormakaba_oracode_metadata", {}).get("predefined_time_slots", [])

if not time_slots:
    print("❌ No time slots configured on this device")
else:
    print(f"✓ {len(time_slots)} time slots configured:")
    for slot in time_slots:
        print(f"  • {slot['name']}")
        print(f"    Check-in: {slot['check_in_time']}")
        print(f"    Check-out: {slot['check_out_time']}")
```

**Solutions:**

* Adjust your booking times to be within 1 hour of an available slot
* Contact your Dormakaba installer to add time slots matching your booking patterns

**Code creation fails silently**

This typically happens with automated systems. Verify that:

* Time slots are configured for the door
* Booking times are within 1 hour of a configured slot
* The device supports offline access codes (`can_program_offline_access_codes` is `true`)

**Different behavior on different doors**

Time slots are configured per door. Check each device individually:

python

```python theme={null}
# Check all devices in an account
devices = seam.devices.list(connected_account_id="your-account-id")

for device in devices:
    time_slots = device.properties.get("dormakaba_oracode_metadata", {}).get("predefined_time_slots", [])
    print(f"{device.properties.get('name')}: {len(time_slots)} time slots")

    if not time_slots:
        print(f"  ⚠️ WARNING: No time slots configured!")
```

***

### Best practices

**Always check for time slots first:** Before attempting to create codes, verify that time slots are configured on the device.

**Plan your time slots carefully:** Work with your installer to configure time slots that match your most common booking patterns. Include a 24-hour slot (12:00 PM → 12:00 PM) for maximum flexibility.

**Test before going live:** After your installer configures time slots, wait 30 minutes for Seam to sync, then create test codes to verify everything works.

**Monitor code limits:** Since codes cannot be deleted, be aware of your device's code limit to avoid reaching capacity.

**Use consistent naming:** Include meaningful names for codes (e.g., "Guest - Room 101 - Sept 10-15") to help with tracking and troubleshooting.

***

### Need help?

* For time slot configuration: Contact your Dormakaba installer
* For Seam API questions: [support@getseam.com](mailto:support@getseam.com)
* For detailed time slot guidance: See our [Time Slot Configuration Guide](https://help.getseam.com/articles/3198102890-dormakaba-oracode-time-slot-configuration)


# Dusaw Setup Guide
Source: https://docs.seam.co/device-and-system-integration-guides/dusaw-locks/dusaw-setup-guide

Connect your Dusaw locks to Seam.

## Overview

This guide walks you through connecting your Dusaw locks to Seam. Your Dusaw locks must already be set up in the Dusaw app and paired with a compatible gateway before proceeding.

***

## Step 1: Connect to Seam via Connect Webview

1. Open the [Connect Webview](/core-concepts/connect-webviews) provided by your application.
2. Select **Dusaw** as the provider.
3. Log in with your Dusaw account credentials.
4. Once authorized, your Dusaw locks appear as devices in Seam.

***

## Step 2: Verify the Connection

After connecting, verify that your Dusaw locks appear as devices and show as online with lock and unlock capabilities.

***

## Troubleshooting

### Locks not appearing after authorization

Ensure your Dusaw locks are set up and paired with a gateway in the Dusaw app. Only locks that are online and connected to a gateway appear in Seam. You must also be the top administrator for each lock you want to connect.

### Remote unlock not working

In the Dusaw app, go to the lock settings and confirm that the **Remote Unlock** feature is enabled. Seam requires this setting to control the lock remotely.

### Gateway pairing issues

Dusaw locks require a compatible Dusaw gateway for remote access. Confirm the gateway is online and paired to the lock in the Dusaw app.


# Dusaw Locks
Source: https://docs.seam.co/device-and-system-integration-guides/dusaw-locks/index

Guide for using Dusaw smart locks with Seam

## Overview

Dusaw produces smart locks built on the Dusaw platform. Their product line includes deadbolts and lever locks for residential and commercial use. Dusaw locks support keypad entry, Bluetooth, and Wi-Fi connectivity through the Dusaw app and a compatible gateway.

Seam integrates with Dusaw locks to provide remote lock and unlock actions and access code programming through a unified API.

***

## Supported Devices

This integration supports Dusaw smart locks that are paired with a compatible Dusaw gateway.

For detailed information about the Dusaw devices that Seam supports, see our [Dusaw Supported Devices page](https://www.seam.co/manufacturers/dusaw).

***

## Supported Features

We support the following features:

* [Triggering web lock and unlock actions](/low-level-apis/smart-locks/lock-and-unlock)
* [Programming access codes](/low-level-apis/smart-locks/access-codes) on locks that have a keypad

***

## Device Provider Key

Seam identifies these devices with the `dusaw` device provider key. By default, a [Connect Webview](/core-concepts/connect-webviews) displays all of the stable providers that Seam supports, so your users can connect their Dusaw devices without you specifying a provider list. To narrow what a Connect Webview displays, see [Customize the Brands to Display in Your Connect Webviews](/core-concepts/connect-webviews/customizing-connect-webviews#customize-the-brands-to-display-in-your-connect-webviews).

***

## Setup Instructions

For instructions on connecting Dusaw locks to Seam, see the [Dusaw Setup Guide](./dusaw-setup-guide).

***

## Where to Order

<CardGroup>
  <Card title="Dusaw - Smart Locks" href="https://www.dusaw.com/" />
</CardGroup>


# Sandbox ecobee Thermostats
Source: https://docs.seam.co/device-and-system-integration-guides/ecobee-thermostats/ecobee-sample-data

Add virtual ecobee thermostats to your Seam sandbox workspace using these sample credentials to test your integration without real hardware.

Use the following set of credentials to add virtual [ecobee thermostats](/device-and-system-integration-guides/ecobee-thermostats) to your Seam [sandbox workspace](/core-concepts/workspaces#sandbox-workspaces):

| Email Address                               | Password |
| ------------------------------------------- | -------- |
| [jane@example.com](mailto:jane@example.com) | 1234     |


# ecobee Setup Guide
Source: https://docs.seam.co/device-and-system-integration-guides/ecobee-thermostats/ecobee-setup-guide

Connect your ecobee thermostats to Seam.

This guide walks you through connecting your ecobee thermostats to Seam. Your thermostats must already be set up and working in the ecobee app before proceeding.

## 1. Create an ecobee account

If you don't already have one, download the [ecobee app](https://www.ecobee.com/en-us/installation/) and create an account. Add your ecobee thermostats in the app and confirm they are online.

## 2. Connect ecobee to Seam

Use the login credentials for your ecobee account to log in through the [Seam Connect Webview](/core-concepts/connect-webviews) and authorize Seam to access your devices.

<Info>
  Make sure that you're authenticating with the user to whom the devices are
  registered. ecobee devices can only be registered to a single user.
</Info>

## 3. Verify the connection

After completing the Connect Webview, confirm that your ecobee thermostats appear in your Seam workspace and show an **online** status.

***

## Troubleshooting

If your devices don't appear after connecting:

* Confirm that your ecobee thermostats are online in the ecobee app.
* Verify that you logged in with the same ecobee account that owns the thermostats.
* Wait a few minutes for the initial sync to complete, then refresh your device list.


# Get Started with ecobee Thermostats
Source: https://docs.seam.co/device-and-system-integration-guides/ecobee-thermostats/get-started-with-ecobee-thermostats

Learn how to connect and control ecobee thermostats with the Seam API.

<picture>
  <source />

  <img alt="" />
</picture>

## Overview

Seam provides a universal API to connect and control many brands of IoT devices and systems, including thermostats, smart locks, access control systems (ACSs), and noise sensors.

This guide gives you a rapid introduction to connecting and controlling your [ecobee](https://www.seam.co/manufacturers/ecobee) thermostats using the Seam API. For application developers, you can use the Seam API in your app, and your users can authorize your app to control their devices using Seam.

For detailed information about the ecobee devices that Seam supports, see our [ecobee Supported Devices page](https://www.seam.co/manufacturers/ecobee).

To learn more about other IoT device and system brands that Seam supports—such as Honeywell Resideo, Google Nest, Yale, Schlage, and many more—visit our [integration page](https://www.seam.co/supported-devices-and-systems).

<Check>
  This guide shows you how to install a Seam SDK and then control your ecobee thermostat using the Seam API.

  Another easy way to learn about what you can do with the Seam API is to explore the [interactive Seam CLI](/core-concepts/seam-console/seam-online-cli), which you can access from directly within the [Seam Console](/core-concepts/seam-console).

  :arrow\_forward: [Go to the Seam Console!](https://console.seam.co/)
</Check>

***

## Step 1: Install a Seam SDK

Seam provides client libraries for many languages, including JavaScript, Python, Ruby, PHP, and others, as well as a Postman collection and an [OpenAPI](https://connect.getseam.com/openapi.json) spec.

* JavaScript / TypeScript ([npm](https://www.npmjs.com/package/seam), [GitHub](https://github.com/seamapi/javascript))
* Python ([pip](https://pypi.org/project/seam/), [GitHub](https://github.com/seamapi/python))
* Ruby Gem ([rubygem](https://rubygems.org/gems/seam), [GitHub](https://github.com/seamapi/ruby))
* PHP ([packagist](https://packagist.org/packages/seamapi/seam), [GitHub](https://github.com/seamapi/php))
* C# ([nuget](https://www.nuget.org/packages/Seam), [GitHub](https://github.com/seamapi/csharp))

First, install a Seam SDK, as follows:

<Tabs>
  <Tab title="JavaScript">
    ```bash theme={null}
    npm i seam
    ```
  </Tab>

  <Tab title="Python">
    ```bash theme={null}
    pip install seam
    # For some development environments, use pip3 in this command instead of pip.
    ```
  </Tab>

  <Tab title="Ruby">
    ```bash theme={null}
    bundle add seam
    ```
  </Tab>

  <Tab title="PHP">
    ```bash theme={null}
    composer require seamapi/seam
    ```
  </Tab>

  <Tab title="C#">
    Install using [nuget](https://www.nuget.org/packages/Seam).
  </Tab>
</Tabs>

Next, go to [https://console.seam.co/](https://console.seam.co/) and [sign up for Seam](/core-concepts/seam-console#create-a-seam-account) to get your [API key](/core-concepts/authentication/api-keys).

Then, export your API key as an environment variable.

```bash theme={null}
$ export SEAM_API_KEY=seam_test2bMS_94SrGUXuNR2JmJkjtvBQDg5c
```

<Info>
  This guide uses a [sandbox
  workspace](/core-concepts/workspaces#sandbox-workspaces).
  You can only connect virtual devices and systems in this type of workspace. If
  you want to connect a real ecobee thermostat, use a [non-sandbox
  workspace](/core-concepts/workspaces#production-workspaces)
  and API key.
</Info>

***

## Step 2: Link your ecobee account with Seam

To control your ecobee thermostat using the Seam API, you must first authorize your Seam workspace to connect to your ecobee account. If your application needs to connect to your users' ecobee accounts, Seam provides fully-embedded, [customizable](/core-concepts/connect-webviews/customizing-connect-webviews) client-side [Connect Webviews](/core-concepts/connect-webviews) to collect their authorization securely. These user-friendly pre-built authorization flows walk your users through the process of granting your Seam workspace permission to control their ecobee thermostats. The Connect Webview presents a flow that prompts your users to enter their credentials for their ecobee account.

In this guide, you create a Connect Webview object. Then, you display the graphical component of the created Connect Webview and enter a set of sample credentials to connect a sandbox ecobee account.

<Check>
  This guide shows you how to create a Connect Webview programmatically using the Seam API.

  The [Seam Console](/core-concepts/seam-console) provides another easy way to connect devices to your Seam workspace.

  Go to [https://console.seam.co/](https://console.seam.co/). On the **Devices** page, click **+ Add Devices**. Then, see [Authorize your workspace](#authorize-your-workspace) in this guide to complete the Connect Webview authorization flow.

  <img alt="You can also use the Seam Console to add devices." />
</Check>

### Create a Connect Webview

Create a `connect_webview` object and then note the returned URL.

**Code:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  import { Seam } from 'seam'

  const seam = new Seam() // Seam automatically uses your exported SEAM_API_KEY.

  const connectWebview = await seam.connectWebviews.create()

  console.log(connectWebview.login_successful) // false

  // Use the returned Connect Webview URL to display
  // the Connect Webview authorization flow to your user.
  console.log(connectWebview.url)
  ```

  ```bash cURL theme={null}
  curl -X 'POST' \
    'https://connect.getseam.com/connect_webviews/create' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d '{}' | jq -r '"Login Successful (false): " + (.connect_webview.login_successful | tostring),
    "URL: " + .connect_webview.url'
    # Use the returned Connect Webview URL to display
    # the Connect Webview authorization flow to your user.
  ```

  ```python Python theme={null}
  from seam import Seam

  seam = Seam()  # Seam automatically uses your exported SEAM_API_KEY.

  connect_webview = seam.connect_webviews.create()

  assert connect_webview.login_successful is False

  # Use the returned Connect Webview URL to display
  # the Connect Webview authorization flow to your user.
  print(connect_webview.url)
  ```

  ```ruby Ruby theme={null}
  require "seam"

  seam = Seam.new() # Seam automatically uses your exported SEAM_API_KEY.

  connect_webview = seam.connect_webviews.create()

  puts connect_webview.login_successful # false

  # Use the returned Connect Webview URL to display
  # the Connect Webview authorization flow to your user.
  puts connect_webview.url
  ```

  ```php PHP theme={null}
  <?php
  require 'vendor/autoload.php';

  $seam = new Seam\SeamClient(); // Seam automatically uses your exported SEAM_API_KEY.

  $connect_webview = $seam->connect_webviews->create();

  echo $connect_webview->login_successful ? 'true' : 'false', "\n"; // false

  // Use the returned Connect Webview URL to display
  // the Connect Webview authorization flow to your user.
  echo $connect_webview->url;
  ```

  ```csharp C# theme={null}
  using Seam.Client;

  var seam = new SeamClient(apiToken: SEAM_API_KEY);

  var connectWebview = seam.ConnectWebviews.Create();

  Console.WriteLine(connectWebview.LoginSuccessful); // False

  // Use the returned Connect Webview URL to display
  // the Connect Webview authorization flow to your user.
  Console.WriteLine(connectWebview.Url);
  ```
</CodeGroup>

**Output:**

<CodeGroup>
  ```json JavaScript theme={null}
  false
  https://connect.getseam.com/connect_webviews/view?connect_webview_id=12345678-1234-1234-1234-123456789012&auth_token=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
  ```

  ```json cURL theme={null}
  Login Successful (false): false
  https://connect.getseam.com/connect_webviews/view?connect_webview_id=12345678-1234-1234-1234-123456789012&auth_token=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
  ```

  ```json Python theme={null}
  https://connect.getseam.com/connect_webviews/view?connect_webview_id=12345678-1234-1234-1234-123456789012&auth_token=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
  ```

  ```json Ruby theme={null}
  false
  https://connect.getseam.com/connect_webviews/view?connect_webview_id=12345678-1234-1234-1234-123456789012&auth_token=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
  ```

  ```json PHP theme={null}
  false
  https://connect.getseam.com/connect_webviews/view?connect_webview_id=12345678-1234-1234-1234-123456789012&auth_token=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
  ```

  ```json C# theme={null}
  False
  https://connect.getseam.com/connect_webviews/view?connect_webview_id=12345678-1234-1234-1234-123456789012&auth_token=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
  ```
</CodeGroup>

***

### Authorize Your Workspace

In a web browser, go to the URL that the Connect Webview object returned.

For application developers, you can redirect your user to this Connect Webview URL so that they can authorize your app to control their devices using Seam. We even provide a prebuilt [Connect Account Button](/ui-components/overview/react-components/connect-account-button) within our suite of [Seam Components](/ui-components/overview) that help you build your device management flow.

<Check>
  Because you're using a sandbox workspace, you can connect Seam's test ecobee
  account. We provide [virtual devices](./ecobee-sample-data) for each of the
  brands that we support. These sandbox devices and systems enable you to test
  your app with devices from multiple brands without the need to own all the
  corresponding physical devices.
</Check>

Complete the Connect Webview authorization flow by entering the following [ecobee sandbox account](./ecobee-sample-data) credentials:

* **Email:** [jane@example.com](mailto:jane@example.com)
* **Password:** 1234

<picture>
  <source />

  <img alt="Use the Seam Connect Webview authorization flow to connect an ecobee account with Seam. This flow varies slightly based on the device manufacturer." />
</picture>

Confirm that authorization through the Connect Webview was successful by querying its status.

**Code:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  const updatedConnectWebview = await seam.connectWebviews.get({
    connect_webview_id: connectWebview.connect_webview_id,
  })

  console.log(updatedConnectWebview.login_successful) // true
  ```

  ```bash cURL theme={null}
  curl -X 'GET' \
    'https://connect.getseam.com/connect_webviews/get' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d "{
    \"connect_webview_id\": \"${connect_webview_id}\"
  }" | jq -r '"Login Successful (true): " + (.connect_webview.login_successful | tostring)'
  ```

  ```python Python theme={null}
  updated_connect_webview = seam.connect_webviews.get(connect_webview.connect_webview_id)

  assert updated_connect_webview.login_successful is True # True
  ```

  ```ruby Ruby theme={null}
  updated_connect_webview = seam.connect_webviews.get(
    connect_webview_id: connect_webview.connect_webview_id
  )

  puts updated_connect_webview.login_successful # true
  ```

  ```php PHP theme={null}
  $updated_connect_webview = $seam->connect_webviews->get(
    connect_webview_id: $connect_webview->connect_webview_id
  );

  echo $updated_connect_webview->login_successful ? 'true' : 'false', "\n"; // true
  ```

  ```csharp C# theme={null}
  var updatedConnectWebview = seam.ConnectWebviews.Get(
    connectWebviewId: connectWebview.connectWebviewId
  );

  Console.WriteLine(updatedConnectWebview.LoginSuccessful); // True
  ```
</CodeGroup>

**Output:**

<CodeGroup>
  ```json JavaScript theme={null}
  true
  ```

  ```json cURL theme={null}
  Login Successful (true): true
  ```

  ```json Python theme={null}
  True
  ```

  ```json Ruby theme={null}
  true
  ```

  ```json PHP theme={null}
  true
  ```

  ```json C# theme={null}
  True
  ```
</CodeGroup>

***

## Step 3: Retrieve ecobee thermostat devices

When you link an ecobee account with Seam, we create a `device` object to represent each ecobee thermostat in your account. You can then retrieve these ecobee devices using the [List Devices](/api/devices/list) and [Get Device](/api/devices/get) endpoints.

The Seam API exposes each device's properties, such as the current temperature reading in Fahrenheit and Celsius, current HVAC and fan modes, available climate presets, thermostat-specific constraints, and much more.

**Code:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  // Retrieve all devices, filtered by manufacturer,
  // which is one of several filters that list() supports.
  const allEcobeeThermostats = await seam.devices.list({ manufacturer: 'ecobee' })

  // Select the first device as an example.
  const livingRoomThermostat = allEcobeeThermostats[0]

  // Inspect specific properties.
  console.log(
    'Current temperature: ' +
      livingRoomThermostat.properties.temperature_fahrenheit,
  )
  console.log('Fan running: ' + livingRoomThermostat.properties.is_fan_running)

  // View the entire returned device object.
  console.log(livingRoomThermostat)
  ```

  ```bash cURL theme={null}
  # Retrieve all devices, filtered by manufacturer, which is
  # one of several filters that the list endpoint supports.
  all_ecobee_thermostats=$(
    # Use GET or POST.
    curl -X 'GET' \
      'https://connect.getseam.com/devices/list' \
      -H 'accept: application/json' \
      -H "Authorization: Bearer ${SEAM_API_KEY}" \
      -H 'Content-Type: application/json' \
      -d '{
      "manufacturer": "ecobee"
    }')

  # Select the first device as an example.
  living_room_thermostat=$(jq -r '.devices[0]' <<< ${all_ecobee_thermostats})

  # Inspect specific properties.
  echo $(jq -r '"Current temperature: " + (.properties.temperature_fahrenheit | tostring)' <<< ${living_room_thermostat})
  echo $(jq -r '"Fan running: " + (.properties.is_fan_running | tostring)' <<< ${living_room_thermostat})

  # View the entire returned device object.
  echo ${living_room_thermostat}
  ```

  ```python Python theme={null}
  # Retrieve all devices, filtered by manufacturer,
  # which is one of several filters that list() supports.
  all_ecobee_thermostats = seam.devices.list(manufacturer="ecobee")

  # Select the first device as an example.
  living_room_thermostat = all_ecobee_thermostats[0]

  # Inspect specific properties.
  pprint("Current temperature: " + str(living_room_thermostat.properties["temperature_fahrenheit"]))
  pprint("Fan running: " + str(living_room_thermostat.properties["is_fan_running"]))

  # View the entire returned device object.
  pprint(living_room_thermostat)
  ```

  ```ruby Ruby theme={null}
  # Retrieve all devices, filtered by manufacturer,
  # which is one of several filters that list() supports.
  all_ecobee_thermostats = seam.devices.list(manufacturer: "ecobee")

  # Select the first device as an example.
  living_room_thermostat = all_ecobee_thermostats[0]

  # Inspect specific properties.
  puts "Current temperature: " + living_room_thermostat.properties.temperature_fahrenheit.to_s
  puts "Fan running: " + living_room_thermostat.properties.is_fan_running.to_s

  # View the entire returned device object.
  puts living_room_thermostat.inspect
  ```

  ```php PHP theme={null}
  // Retrieve all devices, filtered by manufacturer,
  // which is one of several filters that list() supports.
  $all_ecobee_thermostats = $seam->devices->list(manufacturer: "ecobee");

  // Select the first device as an example.
  $living_room_thermostat = $all_ecobee_thermostats[0];

  // Inspect specific properties.
  echo "Current temperature: ", $living_room_thermostat->properties->temperature_fahrenheit, "\n";
  echo "Fan running: ", $living_room_thermostat->properties->is_fan_running ? 'true' : 'false', "\n";

  // View the entire returned device object.
  echo json_encode($living_room_thermostat, JSON_PRETTY_PRINT);
  ```

  ```csharp C# theme={null}
  // Coming soon!
  ```
</CodeGroup>

**Output:**

<CodeGroup>
  ```json JavaScript theme={null}
  Current temperature: 70
  Fan running: false
  {
    device_id: '11111111-1111-1111-2222-444444444444',
    workspace_id: '00000000-0000-0000-0000-000000000000',
    connected_account_id: '11111111-1111-1111-1111-222222222222',
    created_at: '2024-10-03T22:12:15.666Z',
    properties: {
      manufacturer: 'ecobee',
      online: true,
      temperature_celsius: 21.11111111111111,
      temperature_fahrenheit: 70,
      relative_humidity: 0.36,
      is_cooling: false,
      is_heating: false,
      is_fan_running: false,
      current_climate_setting: {
        display_name: 'Manual Setting',
        fan_mode_setting: 'auto',
        hvac_mode_setting: 'heat',
        manual_override_allowed: true,
        heating_set_point_celsius: 21.11111111111111,
        heating_set_point_fahrenheit: 70
      },
      ...
    },
    can_hvac_cool: true,
    can_hvac_heat: true,
    can_hvac_heat_cool: true,
    can_turn_off_hvac: true,
    ...
  }
  ```

  ```json cURL theme={null}
  Current temperature: 70
  Fan running: false
  {
    "device_id": "11111111-1111-1111-2222-444444444444",
    "workspace_id": "00000000-0000-0000-0000-000000000000",
    "connected_account_id": "11111111-1111-1111-1111-222222222222",
    "created_at": "2024-10-03T22:12:15.666Z",
    "properties": {
      "manufacturer": "ecobee",
      "online": true,
      "temperature_celsius": 21.11111111111111,
      "temperature_fahrenheit": 70,
      "relative_humidity": 0.36,
      "is_cooling": false,
      "is_heating": false,
      "is_fan_running": false,
      "current_climate_setting": {
        "display_name": "Manual Setting",
        "fan_mode_setting": "auto",
        "hvac_mode_setting": "heat",
        "manual_override_allowed": true,
        "heating_set_point_celsius": 21.11111111111111,
        "heating_set_point_fahrenheit": 70
      },
      ...
    },
    "can_hvac_cool": true,
    "can_hvac_heat": true,
    "can_hvac_heat_cool": true,
    "can_turn_off_hvac": true,
    ...
  }
  ```

  ```json Python theme={null}
  'Current temperature: 70'
  'Fan running: False'
  Device(
    device_id='11111111-1111-1111-2222-444444444444',
    workspace_id='00000000-0000-0000-0000-000000000000',
    connected_account_id='11111111-1111-1111-1111-222222222222',
    created_at='2024-10-03T22:12:15.666Z',
    properties={
      'manufacturer': 'ecobee',
      'online': True,
      'temperature_celsius': 21.11111111111111,
      'temperature_fahrenheit': 70,
      'relative_humidity': 0.36,
      'is_cooling': False,
      'is_heating': False,
      'is_fan_running': False,
      'current_climate_setting': {
        'display_name': 'Manual Setting',
        'fan_mode_setting': 'auto',
        'heating_set_point_celsius': 21.11111111111111,
        'heating_set_point_fahrenheit': 70,
        'hvac_mode_setting': 'heat',
        'manual_override_allowed': True
      },
      ...
    },
    can_hvac_cool=True,
    can_hvac_heat=True,
    can_hvac_heat_cool=True,
    can_turn_off_hvac=True,
    ...
  )
  ```

  ```json Ruby theme={null}
  Current temperature: 70
  Fan running: false
  <Seam::Resources::Device:0x005f0
    device_id="11111111-1111-1111-2222-444444444444"
    workspace_id="00000000-0000-0000-0000-000000000000"
    connected_account_id="11111111-1111-1111-1111-222222222222"
    created_at=2024-10-03 22:12:15.666 UTC
    properties=#<Seam::DeepHashAccessor:0x0000016b1791f068 @data={
      "manufacturer"=>"ecobee",
      "online"=>true,
      "temperature_celsius"=>21.11111111111111,
      "temperature_fahrenheit"=>70,
      "relative_humidity"=>0.36,
      "is_cooling"=>false,
      "is_heating"=>false,
      "is_fan_running"=>false,
      "current_climate_setting"=>{
        "display_name"=>"Manual Setting",
        "fan_mode_setting"=>"auto",
        "hvac_mode_setting"=>"heat",
        "manual_override_allowed"=>true,
        "heating_set_point_celsius"=>21.11111111111111,
        "heating_set_point_fahrenheit"=>70
      },
      ...
    }>
    can_hvac_cool=true
    can_hvac_heat=true
    can_hvac_heat_cool=true
    can_turn_off_hvac=true
    ...
  >
  ```

  ```json PHP theme={null}
  Current temperature: 70
  Fan running: false
  {
    "device_id": "11111111-1111-1111-2222-444444444444",
    "workspace_id": "00000000-0000-0000-0000-000000000000",
    "connected_account_id": "11111111-1111-1111-1111-222222222222",
    "created_at": "2024-10-03T22:12:15.666Z",
    "properties": {
      "manufacturer": "ecobee",
      "online": true,
      "temperature_celsius": 21.11111111111111,
      "temperature_fahrenheit": 70,
      "relative_humidity": 0.36,
      "is_cooling": false,
      "is_heating": false,
      "is_fan_running": false,
      "current_climate_setting": {
        "display_name": "Manual Setting",
        "fan_mode_setting": "auto",
        "heating_set_point_celsius": 21.11111111111111,
        "heating_set_point_fahrenheit": 70,
        "hvac_mode_setting": "heat",
        "manual_override_allowed": true,
        ...
      },
      ...
    },
    "can_hvac_cool": true,
    "can_hvac_heat": true,
    "can_hvac_heat_cool": true,
    "can_turn_off_hvac": true,
    ...
  }
  ```

  ```json C# theme={null}
  // Coming soon!
  ```
</CodeGroup>

***

## Step 4: Control your ecobee thermostat

Next, you can use the Seam API to control your ecobee thermostat.

Each device that you connect to Seam has a specific set of capabilities. These capabilities define the Seam API actions that you can use. For thermostats, device-specific capabilities include whether you can [set the HVAC mode](/capability-guides/thermostats/configure-current-climate-settings) to `heat`, `cool`, or `heat_cool`. Seam's intuitive and granular [capability flags](/capability-guides/device-and-system-capabilities#capability-flags) inform your application about what features and behaviors each device supports. Notice the capability flags within the code samples in this guide.

Seam provides additional actions for thermostats, such as setting the fan mode, creating and scheduling climate presets, setting temperature thresholds, and configuring weekly thermostat programs. You can also monitor for Seam thermostat-related events, such as reported temperatures outside your set thresholds.

Try out the following actions on your ecobee thermostat:

* [ ] [Set the HVAC mode](#set-the-hvac-mode)
* [ ] [Create and schedule climate presets](#create-and-schedule-climate-presets)
* [ ] [Configure a weekly thermostat program](#configure-a-weekly-thermostat-program)

### Set the HVAC mode

To set the HVAC mode, use any of the following endpoints or their equivalents in the Seam SDKs:

* `/thermostats/heat`
* `/thermostats/cool`
* `/thermostats/heat_cool`
* `/thermostats/off`
* `/thermostats/set_hvac_mode`

  This endpoint is a consolidated version of the other four endpoints.

Specify the thermostat that you want to control by including the `device_id` in the request body. Also, include the desired temperature [set point](/capability-guides/thermostats/understanding-thermostat-concepts/set-points).

In this example, set the HVAC mode to `heat` and the desired heating set point to 68 °F.

Each of these HVAC mode endpoints returns an [action attempt](/core-concepts/action-attempts) to track the progress of the operation.

**Code:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  // Confirm that the device supports heat mode.
  // You're using a capability flag here!
  if (livingRoomThermostat.can_hvac_heat) {
    // Set the HVAC mode
    // and return an action attempt.
    const actionAttempt = await seam.thermostats.heat({
      device_id: livingRoomThermostat.device_id,
      heating_set_point_fahrenheit: 68,
    })
  }
  ```

  ```bash cURL theme={null}
  # Confirm that the device supports heat mode.
  # You're using a capability flag here!
  if  $(jq -r '.can_hvac_heat' <<< ${living_room_thermostat}); then \
    # Set the HVAC mode
    # and return an action attempt.
    curl -X 'POST' \
      'https://connect.getseam.com/thermostats/heat' \
      -H 'accept: application/json' \
      -H "Authorization: Bearer ${SEAM_API_KEY}" \
      -H 'Content-Type: application/json' \
      -d "{
        \"device_id\": \"$(jq -r '.device_id' <<< ${living_room_thermostat})\",
        \"heating_set_point_fahrenheit\": 68
    }";
  fi
  ```

  ```python Python theme={null}
  # Confirm that the device supports heat mode.
  # You're using a capability flag here!
  if living_room_thermostat.can_hvac_heat:
    # Set the HVAC mode
    # and return an action attempt.
    action_attempt = seam.thermostats.heat(
      device_id = living_room_thermostat.device_id,
      heating_set_point_fahrenheit = 68
    )
  ```

  ```ruby Ruby theme={null}
  # Confirm that the device supports heat mode.
  # You're using a capability flag here!
  if (living_room_thermostat.can_hvac_heat)
    # Set the HVAC mode
    # and return an action attempt.
    action_attempt = seam.thermostats.heat(
      device_id: living_room_thermostat.device_id,
      heating_set_point_fahrenheit: 68
    )
  end
  ```

  ```php PHP theme={null}
  // Confirm that the device supports heat mode.
  // You're using a capability flag here!
  if ($living_room_thermostat->can_hvac_heat) {
    // Set the HVAC mode
    // and return an action attempt.
    $action_attempt = $seam->thermostats->heat(
      device_id: $living_room_thermostat->device_id,
      heating_set_point_fahrenheit: 68
    );
  }
  ```

  ```csharp C# theme={null}
  // Coming soon!
  ```
</CodeGroup>

**Output:**

<CodeGroup>
  ```json JavaScript theme={null}
  {
    "actionAttempt": {
      "status": "success",
      "action_attempt_id": "11111111-2222-3333-4444-555555555555",
      "action_type": "SET_HVAC_MODE",
      "result": {},
      "error": null
    }
  }
  ```

  ```json cURL theme={null}
  {
    "action_attempt": {
      "status": "pending",
      "action_type": "SET_HVAC_MODE",
      "action_attempt_id": "11111111-2222-3333-4444-555555555555",
      "result": null,
      "error": null
    },
    "ok": true
  }
  ```

  ```json Python theme={null}
  ActionAttempt(
    action_attempt_id='11111111-2222-3333-4444-555555555555',
    action_type='SET_HVAC_MODE',
    status='success',
    result={},
    error=None
  )
  ```

  ```json Ruby theme={null}
  <Seam::Resources::ActionAttempt:0x005f0
    status="success"
    action_type="SET_HVAC_MODE"
    action_attempt_id="11111111-2222-3333-4444-555555555555"
    result={}
    error=nil>
  ```

  ```json PHP theme={null}
  {
    "action_attempt_id": "11111111-2222-3333-4444-555555555555",
    "action_type": "SET_HVAC_MODE",
    "error": null,
    "result": {},
    "status": "success"
  }
  ```

  ```json C# theme={null}
  // Coming soon!
  ```
</CodeGroup>

You can track the status of the operation to confirm that the device was set to heat mode successfully. Query `properties.current_climate_setting.hvac_mode_setting` for the device, [retrieve the action attempt](/api/action_attempts/get) by ID, or look for a [`thermostat.manually_adjusted` event](/api/thermostats/events#thermostat-manually_adjusted). Further, if you wanted to find out whether the HVAC system was currently heating, you could inspect `properties.is_heating` for the device.

To query `properties.current_climate_setting.hvac_mode_setting` for the device:

**Code:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  // Get the device by ID.
  const updatedLivingRoomThermostat = await seam.devices.get({
    device_id: livingRoomThermostat.device_id,
  })

  // Inspect properties.current_climate_setting.hvac_mode_setting
  // to confirm that setting the HVAC mode to heat was successful.
  console.log(
    updatedLivingRoomThermostat.properties.current_climate_setting
      .hvac_mode_setting,
  )
  ```

  ```bash cURL theme={null}
  # Get the device by ID.
  updated_living_room_thermostat=$(
    # Use GET or POST.
    curl -X 'GET' \
      'https://connect.getseam.com/devices/get' \
      -H 'accept: application/json' \
      -H "Authorization: Bearer ${SEAM_API_KEY}" \
      -H 'Content-Type: application/json' \
      -d "{
        \"device_id\": \"$(jq -r '.device_id' <<< ${living_room_thermostat})\"
    }")

  # Inspect properties.current_climate_setting.hvac_mode_setting
  # to confirm that setting the HVAC mode to heat was successful.
  echo $(jq -r '(.device.properties.current_climate_setting.hvac_mode_setting)' <<< ${updated_living_room_thermostat})
  ```

  ```python Python theme={null}
  # Get the device by ID.
  updated_living_room_thermostat = seam.devices.get(
    device_id = living_room_thermostat.device_id
  )

  # Inspect properties.current_climate_setting.hvac_mode_setting
  # to confirm that setting the HVAC mode to heat was successful.
  pprint(
    updated_living_room_thermostat.
    properties["current_climate_setting"]["hvac_mode_setting"]
  )
  ```

  ```ruby Ruby theme={null}
  # Get the device by ID.
  updated_living_room_thermostat = seam.devices.get(
    device_id: living_room_thermostat.device_id
  )

  # Inspect properties.current_climate_setting.hvac_mode_setting
  # to confirm that setting the HVAC mode to heat was successful.
  puts updated_living_room_thermostat.
    properties.current_climate_setting.hvac_mode_setting
  ```

  ```php PHP theme={null}
  // Get the device by ID.
  $updated_living_room_thermostat = $seam->devices->get(
    device_id: $living_room_thermostat->device_id
  );

  // Inspect properties.current_climate_setting.hvac_mode_setting
  // to confirm that setting the HVAC mode to heat was successful.
  echo $updated_living_room_thermostat->properties->
    current_climate_setting->hvac_mode_setting;
  ```

  ```csharp C# theme={null}
  // Coming soon!
  ```
</CodeGroup>

**Output:**

<CodeGroup>
  ```json JavaScript theme={null}
  heat
  ```

  ```json cURL theme={null}
  heat
  ```

  ```json Python theme={null}
  'heat'
  ```

  ```json Ruby theme={null}
  heat
  ```

  ```json PHP theme={null}
  heat
  ```

  ```json C# theme={null}
  // Coming soon!
  ```
</CodeGroup>

***

### Create and schedule climate presets

You can use the Seam API to create climate presets for ecobee thermostats. Each climate preset is a saved group of settings, such as HVAC mode, fan mode, and temperature set points. Climate presets make it quick and easy to apply consistent climate settings for different scenarios. For example, you could create two climate presets: a comfort preset for when a vacation rental is occupied and an eco preset for when the vacation rental is empty.

You can schedule climate presets to start and stop whenever you'd like. You can even set a fallback climate preset, such as eco.

In this example, create comfort and eco climate presets, set eco as the fallback, and schedule the comfort climate preset to coincide with two vacation rental reservations.

**Code:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  // Confirm that the thermostat supports heat_cool mode
  // so that the climate presets can use this mode.
  if (updatedLivingRoomThermostat.can_hvac_heat_cool) {
    // Create the climate presets.
    await seam.thermostats.createClimatePreset({
      device_id: updatedLivingRoomThermostat.device_id,
      climate_preset_key: 'comfort',
      name: 'Comfort',
      fan_mode_setting: 'auto',
      hvac_mode_setting: 'heat_cool',
      cooling_set_point_celsius: 25,
      heating_set_point_celsius: 20,
    })

    await seam.thermostats.createClimatePreset({
      device_id: updatedLivingRoomThermostat.device_id,
      climate_preset_key: 'eco',
      name: 'Eco',
      fan_mode_setting: 'auto',
      hvac_mode_setting: 'heat_cool',
      cooling_set_point_celsius: 30,
      heating_set_point_celsius: 15,
    })

    // Then, set eco as the fallback climate setting.
    await seam.thermostats.setFallbackClimatePreset({
      device_id: updatedLivingRoomThermostat.device_id,
      climate_preset_key: 'eco',
    })

    // Now, schedule the comfort preset to coincide with two reservations.
    await seam.thermostats.schedules.create({
      device_id: updatedLivingRoomThermostat.device_id,
      name: "Jim's stay",
      climate_preset_key: 'comfort',
      starts_at: '2025-03-10T15:00:00Z',
      ends_at: '2025-03-15T12:00:00Z',
      is_override_allowed: true,
      max_override_period_minutes: 90,
    })

    await seam.thermostats.schedules.create({
      device_id: updatedLivingRoomThermostat.device_id,
      name: "Jane's stay",
      climate_preset_key: 'comfort',
      starts_at: '2025-03-17T15:00:00Z',
      ends_at: '2025-03-20T12:00:00Z',
      is_override_allowed: true,
      max_override_period_minutes: 90,
    })
  }
  ```

  ```bash cURL theme={null}
  # Confirm that the thermostat supports heat_cool mode
  # so that the climate presets can use this mode.
  if  $(jq -r '.device.can_hvac_heat_cool' <<< ${updated_living_room_thermostat}); then \
    # Create the climate presets.
    curl -X 'POST' \
      'https://connect.getseam.com/thermostats/create_climate_preset' \
      -H 'accept: application/json' \
      -H "Authorization: Bearer ${SEAM_API_KEY}" \
      -H 'Content-Type: application/json' \
      -d "{
        \"device_id\": \"$(jq -r '.device.device_id' <<< ${updated_living_room_thermostat})\",
        \"climate_preset_key\": \"comfort\",
        \"name\": \"Comfort\",
        \"fan_mode_setting\": \"auto\",
        \"hvac_mode_setting\": \"heat_cool\",
        \"cooling_set_point_celsius\": 25,
        \"heating_set_point_celsius\": 20
    }";

    curl -X 'POST' \
      'https://connect.getseam.com/thermostats/create_climate_preset' \
      -H 'accept: application/json' \
      -H "Authorization: Bearer ${SEAM_API_KEY}" \
      -H 'Content-Type: application/json' \
      -d "{
        \"device_id\": \"$(jq -r '.device.device_id' <<< ${updated_living_room_thermostat})\",
        \"climate_preset_key\": \"eco\",
        \"name\": \"Eco\",
        \"fan_mode_setting\": \"auto\",
        \"hvac_mode_setting\": \"heat_cool\",
        \"cooling_set_point_celsius\": 30,
        \"heating_set_point_celsius\": 15
    }";

    # Then, set eco as the fallback climate setting.
    curl -X 'POST' \
      'https://connect.getseam.com/thermostats/set_fallback_climate_preset' \
      -H 'accept: application/json' \
      -H "Authorization: Bearer ${SEAM_API_KEY}" \
      -H 'Content-Type: application/json' \
      -d "{
        \"device_id\": \"$(jq -r '.device.device_id' <<< ${updated_living_room_thermostat})\",
        \"climate_preset_key\": \"eco\"
    }";

    # Now, schedule the comfort preset to coincide with two reservations.
    curl -X 'POST' \
    'https://connect.getseam.com/thermostats/schedules/create' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d "{
      \"device_id\": \"$(jq -r '.device.device_id' <<< ${updated_living_room_thermostat})\",
      \"name\":  \"Jim's stay\",
      \"climate_preset_key\": \"comfort\",
      \"starts_at\": \"2025-03-10T15:00:00Z\",
      \"ends_at\": \"2025-03-15T12:00:00Z\",
      \"is_override_allowed\": true,
      \"max_override_period_minutes\": 90
    }";

    curl -X 'POST' \
    'https://connect.getseam.com/thermostats/schedules/create' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d "{
      \"device_id\": \"$(jq -r '.device.device_id' <<< ${updated_living_room_thermostat})\",
      \"name\":  \"Jane's stay\",
      \"climate_preset_key\": \"comfort\",
      \"starts_at\": \"2025-03-17T15:00:00Z\",
      \"ends_at\": \"2025-03-20T12:00:00Z\",
      \"is_override_allowed\": true,
      \"max_override_period_minutes\": 90
    }";
  fi
  ```

  ```python Python theme={null}
  # Confirm that the thermostat supports heat_cool mode
  # so that the climate presets can use this mode.
  if updated_living_room_thermostat.can_hvac_heat_cool:
    # Create the climate presets.
    seam.thermostats.create_climate_preset(
      device_id = updated_living_room_thermostat.device_id,
      climate_preset_key = "comfort",
      name = "Comfort",
      fan_mode_setting = "auto",
      hvac_mode_setting = "heat_cool",
      cooling_set_point_celsius = 25,
      heating_set_point_celsius = 20
    )

    seam.thermostats.create_climate_preset(
      device_id: updated_living_room_thermostat.device_id,
      climate_preset_key = "eco",
      name = "Eco",
      fan_mode_setting = "auto",
      hvac_mode_setting = "heat_cool",
      cooling_set_point_celsius = 30,
      heating_set_point_celsius = 15
    )

    # Then, set eco as the fallback climate setting.
    seam.thermostats.set_fallback_climate_preset(
      device_id = updated_living_room_thermostat.device_id,
      climate_preset_key = "eco"
    )

    # Now, schedule the comfort preset to coincide with two reservations.
    seam.thermostats.schedules.create(
      device_id = updated_living_room_thermostat.device_id,
      name = "Jim's stay",
      climate_preset_key = "comfort",
      starts_at = "2025-03-10T15:00:00Z",
      ends_at = "2025-03-15T12:00:00Z",
      is_override_allowed = True,
      max_override_period_minutes = 90
    )

    seam.thermostats.schedules.create(
      device_id = updated_living_room_thermostat.device_id,
      name = "Jane's stay",
      climate_preset_key = "comfort",
      starts_at = "2025-03-17T15:00:00Z",
      ends_at = "2025-03-20T12:00:00Z",
      is_override_allowed = True,
      max_override_period_minutes = 90
    )
  ```

  ```ruby Ruby theme={null}
  # Confirm that the thermostat supports heat_cool mode
  # so that the climate presets can use this mode.
  if (updated_living_room_thermostat.can_hvac_heat_cool)
    # Create the climate presets.
    seam.thermostats.create_climate_preset(
      device_id: updated_living_room_thermostat.device_id,
      climate_preset_key: "comfort",
      name: "Comfort",
      fan_mode_setting: "auto",
      hvac_mode_setting: "heat_cool",
      cooling_set_point_celsius: 25,
      heating_set_point_celsius: 20
    )

    seam.thermostats.create_climate_preset(
      device_id: updated_living_room_thermostat.device_id,
      climate_preset_key: "eco",
      name: "Eco",
      fan_mode_setting: "auto",
      hvac_mode_setting: "heat_cool",
      cooling_set_point_celsius: 30,
      heating_set_point_celsius: 15
    )

    # Then, set eco as the fallback climate setting.
    seam.thermostats.set_fallback_climate_preset(
      device_id: updated_living_room_thermostat.device_id,
      climate_preset_key: "eco"
    )

    # Now, schedule the comfort preset to coincide with two reservations.
    seam.thermostats.schedules.create(
      device_id: updated_living_room_thermostat.device_id,
      name: "Jim's stay",
      climate_preset_key: "comfort",
      starts_at: "2025-03-10T15:00:00Z",
      ends_at: "2025-03-15T12:00:00Z",
      is_override_allowed: true,
      max_override_period_minutes: 90
    )

    await seam.thermostats.schedules.create(
      device_id: updated_living_room_thermostat.device_id,
      name: "Jane's stay",
      climate_preset_key: "comfort",
      starts_at: "2025-03-17T15:00:00Z",
      ends_at: "2025-03-20T12:00:00Z",
      is_override_allowed: true,
      max_override_period_minutes: 90
    )
  end
  ```

  ```php PHP theme={null}
  // Confirm that the thermostat supports heat_cool mode
  // so that the climate presets can use this mode.
  if ($updated_living_room_thermostat->can_hvac_heat_cool) {
    // Create the climate presets.
    $seam->thermostats->create_climate_preset(
      device_id: $updated_living_room_thermostat->device_id,
      climate_preset_key: "comfort",
      name: "Comfort",
      fan_mode_setting: "auto",
      hvac_mode_setting: "heat_cool",
      cooling_set_point_celsius: 25,
      heating_set_point_celsius: 20
    );

    $seam->thermostats->create_climate_preset(
      device_id: $updated_living_room_thermostat->device_id,
      climate_preset_key: "eco",
      name: "Eco",
      fan_mode_setting: "auto",
      hvac_mode_setting: "heat_cool",
      cooling_set_point_celsius: 30,
      heating_set_point_celsius: 15
    );

    // Then, set eco as the fallback climate setting.
    $seam->thermostats->set_fallback_climate_preset(
      device_id: $updated_living_room_thermostat->device_id,
      climate_preset_key: "eco"
    );

    // Now, schedule the comfort preset to coincide with two reservations.
    $seam->thermostats->schedules->create(
      device_id: $updated_living_room_thermostat->device_id,
      name: "Jim's stay",
      climate_preset_key: "comfort",
      starts_at: "2025-03-10T15:00:00Z",
      ends_at: "2025-03-15T12:00:00Z",
      is_override_allowed: true,
      max_override_period_minutes: 90
    );

    $seam->thermostats->schedules->create(
      device_id: updated_living_room_thermostat.device_id,
      name: "Jane's stay",
      climate_preset_key: "comfort",
      starts_at: "2025-03-17T15:00:00Z",
      ends_at: "2025-03-20T12:00:00Z",
      is_override_allowed: true,
      max_override_period_minutes: 90
    );
  }
  ```

  ```csharp C# theme={null}
  // Coming soon!
  ```
</CodeGroup>

**Output:**

<CodeGroup>
  ```json JavaScript theme={null}
  {
    thermostat_schedule_id: '88888888-1111-1111-1111-111111111111',
    name: "Jim's stay",
    device_id: '11111111-1111-1111-2222-444444444444',
    climate_preset_key: 'comfort',
    starts_at: '2025-03-10T15:00:00.000Z',
    ends_at: '2025-03-15T12:00:00.000Z',
    is_override_allowed: true,
    max_override_period_minutes: 90,
    ...
  }
  {
    thermostat_schedule_id: '88888888-1111-1111-1111-222222222222',
    name: "Jane's stay",
    device_id: '11111111-1111-1111-2222-444444444444',
    climate_preset_key: 'comfort',
    starts_at: '2025-03-17T15:00:00.000Z',
    ends_at: '2025-03-20T12:00:00.000Z',
    is_override_allowed: true,
    max_override_period_minutes: 90,
    ...
  }
  ```

  ```json cURL theme={null}
  {
    "thermostat_schedule":{
      "thermostat_schedule_id":"88888888-1111-1111-1111-111111111111",
      "name":"Jim's stay",
      "device_id":"11111111-1111-1111-2222-444444444444",
      "climate_preset_key":"comfort",
      "starts_at":"2025-03-10T15:00:00.000Z",
      "ends_at":"2025-03-15T12:00:00.000Z",
      "is_override_allowed":true,
      "max_override_period_minutes":90,
      ...
    },
    "ok":true
  }
  {
    "thermostat_schedule":{
      "thermostat_schedule_id":"88888888-1111-1111-1111-222222222222",
      "name":"Jane's stay",
      "device_id":"11111111-1111-1111-2222-444444444444",
      "climate_preset_key":"comfort",
      "starts_at":"2025-03-17T15:00:00.000Z",
      "ends_at":"2025-03-20T12:00:00.000Z",
      "is_override_allowed":true,
      "max_override_period_minutes":90,
      ...
    },
    "ok":true
  }
  ```

  ```json Python theme={null}
  ThermostatSchedule(
    thermostat_schedule_id='88888888-1111-1111-1111-111111111111',
    name="Jim's stay",
    device_id='11111111-1111-1111-2222-444444444444',
    climate_preset_key='comfort',
    starts_at='2025-03-10T15:00:00.000Z',
    ends_at='2025-03-15T12:00:00.000Z',
    is_override_allowed=True,
    max_override_period_minutes=90,
    ...
  )
  ThermostatSchedule(
    thermostat_schedule_id='88888888-1111-1111-1111-222222222222',
    name="Jane's stay",
    device_id='11111111-1111-1111-2222-444444444444',
    climate_preset_key='comfort',
    starts_at='2025-03-17T15:00:00.000Z',
    ends_at='2025-03-20T12:00:00.000Z',
    is_override_allowed=True,
    max_override_period_minutes=90,
    ...
  )
  ```

  ```json Ruby theme={null}
  <Seam::Resources::ThermostatSchedule:0x005f0
    thermostat_schedule_id="88888888-1111-1111-1111-111111111111"
    name="Jim's stay"
    device_id="11111111-1111-1111-2222-444444444444"
    climate_preset_key="comfort"
    starts_at=2025-03-10 15:00:00 UTC
    ends_at=2025-03-15 12:00:00 UTC
    is_override_allowed=true
    max_override_period_minutes=90
    ...
  >
  <Seam::Resources::ThermostatSchedule:0x005f0
    thermostat_schedule_id="88888888-1111-1111-1111-222222222222"
    name="Jane's stay"
    device_id="11111111-1111-1111-2222-444444444444"
    climate_preset_key="comfort"
    starts_at=2025-03-17 15:00:00 UTC
    ends_at=2025-03-20 12:00:00 UTC
    is_override_allowed=true
    max_override_period_minutes=90
    ...
  >
  ```

  ```json PHP theme={null}
  {
    "thermostat_schedule_id":"88888888-1111-1111-1111-111111111111",
    "name":"Jim's stay",
    "device_id":"11111111-1111-1111-2222-444444444444",
    "climate_preset_key":"comfort",
    "starts_at":"2025-03-10T15:00:00.000Z",
    "ends_at":"2025-03-15T12:00:00.000Z",
    "is_override_allowed":true,
    "max_override_period_minutes":90,
    ...
  }
  {
    "thermostat_schedule_id":"88888888-1111-1111-1111-222222222222",
    "name":"Jane's stay",
    "device_id":"11111111-1111-1111-2222-444444444444",
    "climate_preset_key":"comfort",
    "starts_at":"2025-03-17T15:00:00.000Z",
    "ends_at":"2025-03-20T12:00:00.000Z",
    "is_override_allowed":true,
    "max_override_period_minutes":90,
    ...
  }
  ```

  ```json C# theme={null}
  // Coming soon!
  ```
</CodeGroup>

***

### Configure a weekly thermostat program

You can use the Seam API to create a thermostat weekly program for your ecobee thermostat. This standard feature of smart thermostats enables you to define full-week programs that are made up of reusable daily programs. Each daily program consists of a set of thermostat daily program periods, that is, time blocks with associated climate presets.

In this example, create a weekday daily program and a weekend daily program. Then, combine these daily programs into a weekly program by assigning a daily program to each day of the week.

**Code:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  // Create the daily programs.
  const weekdayProgram = await seam.thermostats.dailyPrograms.create({
    device_id: updatedLivingRoomThermostat.device_id,
    name: 'Weekday Program',
    periods: [
      { starts_at_time: '07:00:00', climate_preset_key: 'Home' },
      { starts_at_time: '09:00:00', climate_preset_key: 'Away' },
      { starts_at_time: '18:00:00', climate_preset_key: 'Home' },
      { starts_at_time: '22:00:00', climate_preset_key: 'Sleep' },
    ],
  })

  const weekendProgram = await seam.thermostats.dailyPrograms.create({
    device_id: updatedLivingRoomThermostat.device_id,
    name: 'Weekend Program',
    periods: [
      { starts_at_time: '08:00:00', climate_preset_key: 'Home' },
      { starts_at_time: '23:00:00', climate_preset_key: 'Sleep' },
    ],
  })

  // Use the daily programs to set the weekly program.
  await seam.thermostats.updateWeeklyProgram({
    device_id: updatedLivingRoomThermostat.device_id,
    monday_program_id: weekdayProgram.thermostat_daily_program_id,
    tuesday_program_id: weekdayProgram.thermostat_daily_program_id,
    wednesday_program_id: weekdayProgram.thermostat_daily_program_id,
    thursday_program_id: weekdayProgram.thermostat_daily_program_id,
    friday_program_id: weekdayProgram.thermostat_daily_program_id,
    saturday_program_id: weekendProgram.thermostat_daily_program_id,
    sunday_program_id: weekendProgram.thermostat_daily_program_id,
  })
  ```

  ```bash cURL theme={null}
  # Create the daily programs.
  weekday_program=$(curl -X 'POST' \
    'https://connect.getseam.com/thermostats/daily_programs/create' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d "{
      \"device_id\": \"$(jq -r '.device.device_id' <<< ${updated_living_room_thermostat})\",
      \"name\":  \"Weekday Program\",
      \"periods\": [
      { \"starts_at_time\": \"07:00:00\", \"climate_preset_key\": \"Home\" },
      { \"starts_at_time\": \"09:00:00\", \"climate_preset_key\": \"Away\" },
      { \"starts_at_time\": \"18:00:00\", \"climate_preset_key\": \"Home\" },
      { \"starts_at_time\": \"22:00:00\", \"climate_preset_key\": \"Sleep\" }
    ]
  }")
  weekday_program_id=$(jq -r '.thermostat_daily_program_id' <<< ${weekday_program})

  weekend_program=$(curl -X 'POST' \
    'https://connect.getseam.com/thermostats/daily_programs/create' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d "{
      \"device_id\": \"$(jq -r '.device.device_id' <<< ${updated_living_room_thermostat})\",
      \"name\":  \"Weekend Program\",
      \"periods\": [
      { \"starts_at_time\": \"08:00:00\", \"climate_preset_key\": \"Home\" },
      { \"starts_at_time\": \"23:00:00\", \"climate_preset_key\": \"Sleep\" }
    ]
  }")
  weekend_program_id=$(jq -r '.thermostat_daily_program_id' <<< ${weekend_program})

  # Use the daily programs to set the weekly program.
  curl -X 'POST' \
    'https://connect.getseam.com/thermostats/update_weekly_program' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d "{
      \"device_id\": \"$(jq -r '.device.device_id' <<< ${updated_living_room_thermostat})\",
      \"monday_program_id\": \"${weekday_program_id}\",
      \"tuesday_program_id\": \"${weekday_program_id}\",
      \"wednesday_program_id\": \"${weekday_program_id}\",
      \"thursday_program_id\": \"${weekday_program_id}\",
      \"friday_program_id\": \"${weekday_program_id}\",
      \"saturday_program_id\": \"${weekend_program_id}\",
      \"sunday_program_id\": \"${weekend_program_id}\"
  }"
  ```

  ```python Python theme={null}
  # Create the daily programs.
  weekday_program = seam.thermostats.daily_programs.create(
    device_id = updated_living_room_thermostat.device_id,
    name = "Weekday Program",
    periods = [
      { "starts_at_time": "07:00:00", "climate_preset_key": "Home" },
      { "starts_at_time": "09:00:00", "climate_preset_key": "Away" },
      { "starts_at_time": "18:00:00", "climate_preset_key": "Home" },
      { "starts_at_time": "22:00:00", "climate_preset_key": "Sleep" }
    ]
  )

  weekend_program = seam.thermostats.daily_programs.create(
    device_id = updated_living_room_thermostat.device_id,
    name = "Weekend Program",
    periods = [
      { "starts_at_time": "08:00:00", "climate_preset_key": "Home" },
      { "starts_at_time": "23:00:00", "climate_preset_key": "Sleep" }
    ]
  )

  # Use the daily programs to set the weekly program.
  seam.thermostats.update_weekly_program(
    device_id = updated_living_room_thermostat.device_id,
    monday_program_id = weekday_program.thermostat_daily_program_id,
    tuesday_program_id = weekday_program.thermostat_daily_program_id,
    wednesday_program_id = weekday_program.thermostat_daily_program_id,
    thursday_program_id = weekday_program.thermostat_daily_program_id,
    friday_program_id = weekday_program.thermostat_daily_program_id,
    saturday_program_id = weekend_program.thermostat_daily_program_id,
    sunday_program_id = weekend_program.thermostat_daily_program_id
  )
  ```

  ```ruby Ruby theme={null}
  # Create the daily programs.
  weekday_program = seam.thermostats.daily_programs.create(
    device_id: updated_living_room_thermostat.device_id,
    name: "Weekday Program",
    periods: [
      { "starts_at_time": "07:00:00", "climate_preset_key": "Home" },
      { "starts_at_time": "09:00:00", "climate_preset_key": "Away" },
      { "starts_at_time": "18:00:00", "climate_preset_key": "Home" },
      { "starts_at_time": "22:00:00", "climate_preset_key": "Sleep" }
    ]
  )

  weekend_program = seam.thermostats.daily_programs.create(
    device_id: updated_living_room_thermostat.device_id,
    name: "Weekend Program",
    periods: [
      { "starts_at_time": "08:00:00", "climate_preset_key": "Home" },
      { "starts_at_time": "23:00:00", "climate_preset_key": "Sleep" }
    ]
  )

  # Use the daily programs to set the weekly program.
  seam.thermostats.update_weekly_program(
    device_id: updated_living_room_thermostat.device_id,
    monday_program_id: weekday_program.thermostat_daily_program_id,
    tuesday_program_id: weekday_program.thermostat_daily_program_id,
    wednesday_program_id: weekday_program.thermostat_daily_program_id,
    thursday_program_id: weekday_program.thermostat_daily_program_id,
    friday_program_id: weekday_program.thermostat_daily_program_id,
    saturday_program_id: weekend_program.thermostat_daily_program_id,
    sunday_program_id: weekend_program.thermostat_daily_program_id
  )
  ```

  ```php PHP theme={null}
  // Create the daily programs.
  $weekday_program = $seam->thermostats->daily_programs->create(
    device_id: $updated_living_room_thermostat->device_id,
    name: "Weekday Program",
    periods: [
      { "starts_at_time": "07:00:00", "climate_preset_key": "Home" },
      { "starts_at_time": "09:00:00", "climate_preset_key": "Away" },
      { "starts_at_time": "18:00:00", "climate_preset_key": "Home" },
      { "starts_at_time": "22:00:00", "climate_preset_key": "Sleep" }
    ]
  );

  $weekend_program = $seam->thermostats->daily_programs->create(
    device_id: $updated_living_room_thermostat->device_id,
    name: "Weekend Program",
    periods: [
      { "starts_at_time": "08:00:00", "climate_preset_key": "Home" },
      { "starts_at_time": "23:00:00", "climate_preset_key": "Sleep" }
    ]
  );

  // Use the daily programs to set the weekly program.
  $seam->thermostats->update_weekly_program(
    device_id: $updated_living_room_thermostat->device_id,
    monday_program_id: $weekday_program->thermostat_daily_program_id,
    tuesday_program_id: $weekday_program->thermostat_daily_program_id,
    wednesday_program_id: $weekday_program->thermostat_daily_program_id,
    thursday_program_id: $weekday_program->thermostat_daily_program_id,
    friday_program_id: $weekday_program->thermostat_daily_program_id,
    saturday_program_id: $weekend_program->thermostat_daily_program_id,
    sunday_program_id: $weekend_program->thermostat_daily_program_id
  );
  ```

  ```csharp C# theme={null}
  // Coming soon!
  ```
</CodeGroup>

**Output:**

<CodeGroup>
  ```json JavaScript theme={null}
  {
    "status": "success",
    "action_attempt_id": "11111111-2222-3333-4444-666666666666",
    "action_type": "PUSH_THERMOSTAT_PROGRAMS",
    "result": {},
    "error": null
  }
  ```

  ```json cURL theme={null}
  {
    "action_attempt": {
      "status": "pending",
      "action_type": "PUSH_THERMOSTAT_PROGRAMS",
      "action_attempt_id": "11111111-2222-3333-4444-666666666666",
      "result": null,
      "error": null
    },
    "ok": true
  }
  ```

  ```json Python theme={null}
  ActionAttempt(
    action_attempt_id='11111111-2222-3333-4444-666666666666',
    action_type='PUSH_THERMOSTAT_PROGRAMS',
    status='success',
    result={},
    error=None
  )
  ```

  ```json Ruby theme={null}
  <Seam::Resources::ActionAttempt:0x005f0
    status="success"
    action_type="PUSH_THERMOSTAT_PROGRAMS"
    action_attempt_id="11111111-2222-3333-4444-666666666666"
    result={}
    error=nil>
  ```

  ```json PHP theme={null}
  {
    "status": "success",
    "action_attempt_id": "11111111-2222-3333-4444-666666666666",
    "action_type": "PUSH_THERMOSTAT_PROGRAMS",
    "result": {},
    "error": null
  }
  ```

  ```json C# theme={null}
  // Coming soon!
  ```
</CodeGroup>

***

## Step 5: Connect a real ecobee thermostat

Now that you have learned the basics of using the Seam API, you can connect and control a real ecobee device. To do so, make sure to switch to a [non-sandbox workspace](/core-concepts/workspaces#production-workspaces) and [API key](/core-concepts/authentication/api-keys).

For more details about setting up your real ecobee thermostat, see the [ecobee thermostats integration guide](./).

***

## Step 6: Build your application!

Seam makes it easy to develop your application. The robust Seam API and Seam SDKs in a wide variety of programming languages provide robust, up-to-date information about your thermostats. We also provide helpful thermostat-related events that enable you to monitor the status of your thermostats and the connected HVAC systems. Further, our simulation endpoints make it easy for you to test your thermostat app against events that can be difficult to orchestrate in your quality assurance (QA) environment using real devices.

***

## Next steps

Now that you've completed this getting started guide for ecobee devices, you can learn more about what you can do with the Seam API.

* [ ] **Explore**\
  See the [other devices and system integrations](/device-and-system-integration-guides) that Seam supports.
* [ ] **Learn**\
  Read about Seam [concepts](/core-concepts/overview) and the [device and system capabilities ](/capability-guides/device-and-system-capabilities)that Seam supports.
* [ ] **Expand your abilities**\
  Find out what other [thermostat actions](/capability-guides/thermostats) you can perform using the Seam API.
* [ ] **Use webhooks**\
  Learn how to use [webhooks](/developer-tools/webhooks) as an efficient way to receive device events.
* [ ] **Find out more**\
  Explore the other types of devices and systems that you can control with Seam, including [smart locks](/low-level-apis/smart-locks), [access control systems](/low-level-apis/access-systems), and [noise sensors](/capability-guides/noise-sensors).
* [ ] **Develop for mobile access**\
  Learn about Seam's [mobile access solution](/capability-guides/mobile-access).

<Info>
  If you have any questions or want to report an issue, email us at
  [support@seam.co](mailto:support@seam.co).
</Info>

***

## Quick links

<CardGroup>
  <Card title="Get an API Key (free)" href="https://console.seam.co/">
    Sign up for the Seam Console and get your API keys. →
  </Card>

  <Card title="Contact Sales" href="https://www.seam.co/contact-us">
    Got a project or a specific question? Contact our team to get answers. →
  </Card>
</CardGroup>


# ecobee Thermostats
Source: https://docs.seam.co/device-and-system-integration-guides/ecobee-thermostats/index

Guide for using ecobee thermostats with Seam

<img alt="ecobee logo" />

<picture>
  <source />

  <img alt="ecobee Thermostats" />
</picture>

## Overview

ecobee smart thermostats are designed to lower energy costs. In addition to energy efficiency features, such as climate setting scheduling, occupancy sensors, and automatic air conditioning pause when a window or door is left open, ecobee thermostats are hard-wired, instead of battery-powered, for reliability.

***

## Supported Devices

<DeviceList />

This integration supports all [ecobee thermostats](https://www.ecobee.com/en-us/smart-thermostats/).

For detailed information about the ecobee devices that Seam supports, see our [ecobee Supported Devices page](https://www.seam.co/manufacturers/ecobee).

***

## Supported Features

We support the following features:

* [Configuring current thermostat settings](/capability-guides/thermostats/configure-current-climate-settings)
* [Creating and managing climate presets](/capability-guides/thermostats/creating-and-managing-climate-presets)
* [Creating and managing thermostat schedules](/capability-guides/thermostats/creating-and-managing-thermostat-schedules)
* [Creating and managing thermostat weekly programs](/capability-guides/thermostats/creating-and-managing-thermostat-programs)
* [Setting and monitoring temperature thresholds](/capability-guides/thermostats/setting-and-monitoring-temperature-thresholds)

***

### Device Provider Key

Seam identifies these devices with the `ecobee` device provider key. By default, a [Connect Webview](/core-concepts/connect-webviews) displays all of the stable providers that Seam supports, so your users can connect their ecobee devices without you specifying a provider list. To narrow what a Connect Webview displays, see [Customize the Brands to Display in Your Connect Webviews](/core-concepts/connect-webviews/customizing-connect-webviews#customize-the-brands-to-display-in-your-connect-webviews).

***

## Setup Instructions

For instructions on connecting ecobee thermostats to Seam, see the [ecobee Setup Guide](./ecobee-setup-guide).

***

## Where to Order

To purchase ecobee thermostats, visit the ecobee online store.

<table>
  <thead>
    <tr>
      <th />

      <th />

      <th />

      <th />

      <th />
    </tr>
  </thead>

  <tbody>
    <tr>
      <td />

      <td>
        <strong>ecobee Online Store</strong>
      </td>

      <td />

      <td>
        <a href="https://www.ecobee.com/en-us/smart-thermostats/">
          [https://www.ecobee.com/en-us/smart-thermostats/](https://www.ecobee.com/en-us/smart-thermostats/)
        </a>
      </td>

      <td>
        <a href="/images/ecobee-logo.png">ecobee-logo.png</a>
      </td>
    </tr>
  </tbody>
</table>

***


# First Alert Setup Guide
Source: https://docs.seam.co/device-and-system-integration-guides/first-alert-thermostats/first-alert-setup-guide

Connect your First Alert thermostats to Seam.

## Overview

This guide walks you through connecting your First Alert thermostats to Seam. Your First Alert devices must already be set up and visible in the First Alert app before proceeding.

***

## Step 1: Connect to Seam via Connect Webview

1. Open the [Connect Webview](/core-concepts/connect-webviews) provided by your application.
2. Select First Alert as the provider.
3. Log in with your First Alert account credentials.
4. Once authorized, your First Alert thermostats appear as devices in Seam.

***

## Step 2: Verify the Connection

After connecting, verify that your First Alert thermostats appear as devices and show as online with heating, cooling, and thermostat program capabilities.

***

## Troubleshooting

### Authorization fails in Connect Webview

Verify that you are using the correct First Alert account credentials.

### Devices not appearing after authorization

Ensure your First Alert thermostats are set up and online in the First Alert app. Only devices that are active and connected appear in Seam.


# First Alert Thermostats
Source: https://docs.seam.co/device-and-system-integration-guides/first-alert-thermostats/index

Guide for using First Alert thermostats with Seam

## Overview

First Alert produces smart thermostats for residential climate control, offering features designed to help homeowners manage energy costs while maintaining comfortable temperatures. Seam integrates with First Alert thermostats to provide heating, cooling, and thermostat program management through a unified API.

***

## Supported Devices

<DeviceList />

This integration supports [First Alert smart thermostats](https://www.firstalert.com/).

For detailed information about the First Alert devices that Seam supports, see our [First Alert Supported Devices page](https://www.seam.co/manufacturers/first_alert).

***

## Supported Features

We support the following features:

* [Configuring current thermostat settings](/capability-guides/thermostats/configure-current-climate-settings)
* [Creating and managing climate presets](/capability-guides/thermostats/creating-and-managing-climate-presets)
* [Creating and managing thermostat schedules](/capability-guides/thermostats/creating-and-managing-thermostat-schedules)
* [Creating and managing thermostat weekly programs](/capability-guides/thermostats/creating-and-managing-thermostat-programs)
* [Setting and monitoring temperature thresholds](/capability-guides/thermostats/setting-and-monitoring-temperature-thresholds)

***

## Device Provider Key

Seam identifies these devices with the `first_alert` device provider key. By default, a [Connect Webview](/core-concepts/connect-webviews) displays all of the stable providers that Seam supports, so your users can connect their First Alert devices without you specifying a provider list. To narrow what a Connect Webview displays, see [Customize the Brands to Display in Your Connect Webviews](/core-concepts/connect-webviews/customizing-connect-webviews#customize-the-brands-to-display-in-your-connect-webviews).

***

## Setup Instructions

For instructions on connecting First Alert thermostats to Seam, see the [First Alert Setup Guide](./first-alert-setup-guide).

***

## Where to Order

<CardGroup>
  <Card title="First Alert - Products" href="https://www.firstalert.com/" />
</CardGroup>


# Genie Garage Openers Sample Data
Source: https://docs.seam.co/device-and-system-integration-guides/genie-garage-openers/genie-sample-data

Add virtual Genie garage openers to your Seam sandbox workspace using these sample credentials to test your integration without real hardware.

Use the following set of credentials to add virtual Genie garage openers to your Seam [sandbox workspace](/core-concepts/workspaces#sandbox-workspaces):

| Email Address                               | Password |
| ------------------------------------------- | -------- |
| [john@example.com](mailto:john@example.com) | 1234     |


# Genie Garage Openers
Source: https://docs.seam.co/device-and-system-integration-guides/genie-garage-openers/index

Guide for using Genie garage openers with Seam

<img alt="Genie logo" />

## Overview

Seam integrates with Genie garage openers.

## Supported Devices

<DeviceList />


# Get Started with Nest Thermostats
Source: https://docs.seam.co/device-and-system-integration-guides/google-nest-thermostats/get-started-with-nest-thermostats

Learn how to connect and control Google Nest thermostats with the Seam API.

## Overview

Seam provides a universal API to connect and control many brands of IoT devices and systems, including thermostats, smart locks, access control systems (ACSs), and noise sensors.

This guide gives you a rapid introduction to connecting and controlling your [Google Nest](https://www.seam.co/manufacturers/nest) thermostats using the Seam API. For application developers, you can use the Seam API in your app, and your users can authorize your app to control their devices using Seam.

For detailed information about the Google Nest devices that Seam supports, see our [Google Nest Supported Devices page](https://www.seam.co/manufacturers/nest).

To learn more about other IoT device and system brands that Seam supports—such as Honeywell Resideo, ecobee, Yale, Schlage, and many more—visit our [integration page](https://www.seam.co/supported-devices-and-systems).

<Check>
  This guide shows you how to install a Seam SDK and then control your Google Nest thermostat using the Seam API.

  Another easy way to learn about what you can do with the Seam API is to explore the [interactive Seam CLI](/core-concepts/seam-console/seam-online-cli), which you can access from directly within the [Seam Console](/core-concepts/seam-console).

  :arrow\_forward: [Go to the Seam Console!](https://console.seam.co/)
</Check>

***

## Step 1: Install a Seam SDK

Seam provides client libraries for many languages, including JavaScript, Python, Ruby, PHP, and others, as well as a Postman collection and an [OpenAPI](https://connect.getseam.com/openapi.json) spec.

* JavaScript / TypeScript ([npm](https://www.npmjs.com/package/seam), [GitHub](https://github.com/seamapi/javascript))
* Python ([pip](https://pypi.org/project/seam/), [GitHub](https://github.com/seamapi/python))
* Ruby Gem ([rubygem](https://rubygems.org/gems/seam), [GitHub](https://github.com/seamapi/ruby))
* PHP ([packagist](https://packagist.org/packages/seamapi/seam), [GitHub](https://github.com/seamapi/php))
* Java ([GitHub](https://github.com/seamapi/java))
* C# ([nuget](https://www.nuget.org/packages/Seam), [GitHub](https://github.com/seamapi/csharp))
* Go ([GitHub](https://github.com/seamapi/go))

First, install a Seam SDK, as follows:

<Tabs>
  <Tab title="JavaScript">
    ```bash theme={null}
    npm i seam
    ```
  </Tab>

  <Tab title="Python">
    ```bash theme={null}
    pip install seam
    # For some development environments, use pip3 in this command instead of pip.
    ```
  </Tab>

  <Tab title="Ruby">
    ```bash theme={null}
    bundle add seam
    ```
  </Tab>

  <Tab title="PHP">
    ```bash theme={null}
    composer require seamapi/seam
    ```
  </Tab>

  <Tab title="C#">
    Install using [nuget](https://www.nuget.org/packages/Seam).
  </Tab>
</Tabs>

Next, go to [https://console.seam.co/](https://console.seam.co/) and [sign up for Seam](/core-concepts/seam-console#create-a-seam-account) to get your [API key](/core-concepts/authentication/api-keys).

Then, export your API key as an environment variable.

```bash theme={null}
$ export SEAM_API_KEY=seam_test2bMS_94SrGUXuNR2JmJkjtvBQDg5c
```

<Info>
  This guide uses a [sandbox
  workspace](/core-concepts/workspaces#sandbox-workspaces).
  You can only connect virtual devices and systems in this type of workspace. If
  you want to connect a real Google Nest thermostat, use a [non-sandbox
  workspace](/core-concepts/workspaces#production-workspaces)
  and API key.
</Info>

***

## Step 2: Link your Google Nest account with Seam

To control your Google Nest thermostat using the Seam API, you must first authorize your Seam workspace to connect to your Google Nest account. If your application needs to connect to your users' Google Nest accounts, Seam provides fully-embedded, [customizable](/core-concepts/connect-webviews/customizing-connect-webviews) client-side [Connect Webviews](/core-concepts/connect-webviews) to collect their authorization securely. These user-friendly pre-built authorization flows walk your users through the process of granting your Seam workspace permission to control their Google Nest thermostats. The Connect Webview presents a flow that prompts your users to enter their credentials for their Google Nest account.

In this guide, you create a Connect Webview object. Then, you display the graphical component of the created Connect Webview and enter a set of sample credentials to connect a sandbox Google Nest account.

<Check>
  This guide shows you how to create a Connect Webview programmatically using the Seam API.

  The [Seam Console](/core-concepts/seam-console) provides another easy way to connect devices to your Seam workspace.

  Go to [https://console.seam.co/](https://console.seam.co/). On the **Devices** page, click **+ Add Devices**. Then, see [Authorize your workspace](#authorize-your-workspace) in this guide to complete the Connect Webview authorization flow.
</Check>

### Create a Connect Webview

Create a `connect_webview` object and then note the returned URL.

**Code:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  import { Seam } from 'seam'

  const seam = new Seam() // Seam automatically uses your exported SEAM_API_KEY.

  const connectWebview = await seam.connectWebviews.create()

  console.log(connectWebview.login_successful) // false

  // Use the returned Connect Webview URL to display
  // the Connect Webview authorization flow to your user.
  console.log(connectWebview.url)
  ```

  ```bash cURL theme={null}
  curl -X 'POST' \
    'https://connect.getseam.com/connect_webviews/create' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d '{}' | jq -r '"Login Successful (false): " + (.connect_webview.login_successful | tostring),
    "URL: " + .connect_webview.url'
    # Use the returned Connect Webview URL to display
    # the Connect Webview authorization flow to your user.
  ```

  ```python Python theme={null}
  from seam import Seam

  seam = Seam()  # Seam automatically uses your exported SEAM_API_KEY.

  connect_webview = seam.connect_webviews.create()

  assert connect_webview.login_successful is False

  # Use the returned Connect Webview URL to display
  # the Connect Webview authorization flow to your user.
  print(connect_webview.url)
  ```

  ```ruby Ruby theme={null}
  require "seam"

  seam = Seam.new() # Seam automatically uses your exported SEAM_API_KEY.

  connect_webview = seam.connect_webviews.create()

  puts connect_webview.login_successful # false

  # Use the returned Connect Webview URL to display
  # the Connect Webview authorization flow to your user.
  puts connect_webview.url
  ```

  ```php PHP theme={null}
  <?php
  require 'vendor/autoload.php';

  $seam = new Seam\SeamClient(); // Seam automatically uses your exported SEAM_API_KEY.

  $connect_webview = $seam->connect_webviews->create();

  echo $connect_webview->login_successful ? 'true' : 'false', "\n"; // false

  // Use the returned Connect Webview URL to display
  // the Connect Webview authorization flow to your user.
  echo $connect_webview->url;
  ```

  ```csharp C# theme={null}
  using Seam.Client;

  var seam = new SeamClient(apiToken: SEAM_API_KEY);

  var connectWebview = seam.ConnectWebviews.Create();

  Console.WriteLine(connectWebview.LoginSuccessful); // False

  // Use the returned Connect Webview URL to display
  // the Connect Webview authorization flow to your user.
  Console.WriteLine(connectWebview.Url);
  ```
</CodeGroup>

**Output:**

<CodeGroup>
  ```json JavaScript theme={null}
  false
  https://connect.getseam.com/connect_webviews/view?connect_webview_id=12345678-1234-1234-1234-123456789012&auth_token=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
  ```

  ```json cURL theme={null}
  Login Successful (false): false
  https://connect.getseam.com/connect_webviews/view?connect_webview_id=12345678-1234-1234-1234-123456789012&auth_token=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
  ```

  ```json Python theme={null}
  https://connect.getseam.com/connect_webviews/view?connect_webview_id=12345678-1234-1234-1234-123456789012&auth_token=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
  ```

  ```json Ruby theme={null}
  false
  https://connect.getseam.com/connect_webviews/view?connect_webview_id=12345678-1234-1234-1234-123456789012&auth_token=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
  ```

  ```json PHP theme={null}
  false
  https://connect.getseam.com/connect_webviews/view?connect_webview_id=12345678-1234-1234-1234-123456789012&auth_token=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
  ```

  ```json C# theme={null}
  False
  https://connect.getseam.com/connect_webviews/view?connect_webview_id=12345678-1234-1234-1234-123456789012&auth_token=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
  ```
</CodeGroup>

***

### Authorize Your Workspace

In a web browser, go to the URL that the Connect Webview object returned.

For application developers, you can redirect your user to this Connect Webview URL so that they can authorize your app to control their devices using Seam. We even provide a prebuilt [Connect Account Button](/ui-components/overview/react-components/connect-account-button) within our suite of [Seam Components](/ui-components/overview) that help you build your device management flow.

<Check>
  Because you're using a sandbox workspace, you can connect Seam's test Google
  Nest account. We provide [virtual
  devices](./google-nest-thermostats-sample-data) for each of the brands that
  we support. These sandbox devices and systems enable you to test your app with
  devices from multiple brands without the need to own all the corresponding
  physical devices.
</Check>

Complete the Connect Webview authorization flow by entering the following [Google Nest sandbox account](./google-nest-thermostats-sample-data) credentials:

* **Email:** [jane@example.com](mailto:jane@example.com)
* **Password:** 1234

Confirm that authorization through the Connect Webview was successful by querying its status.

**Code:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  const updatedConnectWebview = await seam.connectWebviews.get({
    connect_webview_id: connectWebview.connect_webview_id,
  })

  console.log(updatedConnectWebview.login_successful) // true
  ```

  ```bash cURL theme={null}
  curl -X 'GET' \
    'https://connect.getseam.com/connect_webviews/get' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d "{
    \"connect_webview_id\": \"${connect_webview_id}\"
  }" | jq -r '"Login Successful (true): " + (.connect_webview.login_successful | tostring)'
  ```

  ```python Python theme={null}
  updated_connect_webview = seam.connect_webviews.get(connect_webview.connect_webview_id)

  assert updated_connect_webview.login_successful is True # True
  ```

  ```ruby Ruby theme={null}
  updated_connect_webview = seam.connect_webviews.get(
    connect_webview_id: connect_webview.connect_webview_id
  )

  puts updated_connect_webview.login_successful # true
  ```

  ```php PHP theme={null}
  $updated_connect_webview = $seam->connect_webviews->get(
    connect_webview_id: $connect_webview->connect_webview_id
  );

  echo $updated_connect_webview->login_successful ? 'true' : 'false', "\n"; // true
  ```

  ```csharp C# theme={null}
  var updatedConnectWebview = seam.ConnectWebviews.Get(
    connectWebviewId: connectWebview.connectWebviewId
  );

  Console.WriteLine(updatedConnectWebview.LoginSuccessful); // True
  ```
</CodeGroup>

**Output:**

<CodeGroup>
  ```json JavaScript theme={null}
  true
  ```

  ```json cURL theme={null}
  Login Successful (true): true
  ```

  ```json Python theme={null}
  True
  ```

  ```json Ruby theme={null}
  true
  ```

  ```json PHP theme={null}
  true
  ```

  ```json C# theme={null}
  True
  ```
</CodeGroup>

***

## Step 3: Retrieve Google Nest thermostat devices

When you link a Google Nest account with Seam, we create a `device` object to represent each Google Nest thermostat in your account. You can then retrieve these Google Nest devices using the [List Devices](/api/devices/list) and [Get Device](/api/devices/get) endpoints.

The Seam API exposes each device's properties, such as the current temperature reading in Fahrenheit and Celsius, current HVAC and fan modes, available climate presets, thermostat-specific constraints, and much more.

**Code:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  // Retrieve all devices, filtered by manufacturer,
  // which is one of several filters that list() supports.
  const allGoogleNestThermostats = await seam.devices.list({
    manufacturer: 'nest',
  })

  // Select the first device as an example.
  const livingRoomThermostat = allGoogleNestThermostats[0]

  // Inspect specific properties.
  console.log(
    'Current temperature: ' +
      livingRoomThermostat.properties.temperature_fahrenheit,
  )
  console.log('Fan running: ' + livingRoomThermostat.properties.is_fan_running)

  // View the entire returned device object.
  console.log(livingRoomThermostat)
  ```

  ```bash cURL theme={null}
  # Retrieve all devices, filtered by manufacturer, which is
  # one of several filters that the list endpoint supports.
  all_google_nest_thermostats=$(
    # Use GET or POST.
    curl -X 'GET' \
      'https://connect.getseam.com/devices/list' \
      -H 'accept: application/json' \
      -H "Authorization: Bearer ${SEAM_API_KEY}" \
      -H 'Content-Type: application/json' \
      -d '{
      "manufacturer": "nest"
    }')

  # Select the first device as an example.
  living_room_thermostat=$(jq -r '.devices[0]' <<< ${all_google_nest_thermostats})

  # Inspect specific properties.
  echo $(jq -r '"Current temperature: " + (.properties.temperature_fahrenheit | tostring)' <<< ${living_room_thermostat})
  echo $(jq -r '"Fan running: " + (.properties.is_fan_running | tostring)' <<< ${living_room_thermostat})

  # View the entire returned device object.
  echo ${living_room_thermostat}
  ```

  ```python Python theme={null}
  # Retrieve all devices, filtered by manufacturer,
  # which is one of several filters that list() supports.
  all_google_nest_thermostats = seam.devices.list(manufacturer="nest")

  # Select the first device as an example.
  living_room_thermostat = all_google_nest_thermostats[0]

  # Inspect specific properties.
  pprint("Current temperature: " + str(living_room_thermostat.properties["temperature_fahrenheit"]))
  pprint("Fan running: " + str(living_room_thermostat.properties["is_fan_running"]))

  # View the entire returned device object.
  pprint(living_room_thermostat)
  ```

  ```ruby Ruby theme={null}
  # Retrieve all devices, filtered by manufacturer,
  # which is one of several filters that list() supports.
  all_google_nest_thermostats = seam.devices.list(manufacturer: "nest")

  # Select the first device as an example.
  living_room_thermostat = all_google_nest_thermostats[0]

  # Inspect specific properties.
  puts "Current temperature: " + living_room_thermostat.properties.temperature_fahrenheit.to_s
  puts "Fan running: " + living_room_thermostat.properties.is_fan_running.to_s

  # View the entire returned device object.
  puts living_room_thermostat.inspect
  ```

  ```php PHP theme={null}
  // Retrieve all devices, filtered by manufacturer,
  // which is one of several filters that list() supports.
  $all_google_nest_thermostats = $seam->devices->list(manufacturer: "nest");

  // Select the first device as an example.
  $living_room_thermostat = $all_google_nest_thermostats[0];

  // Inspect specific properties.
  echo "Current temperature: ", $living_room_thermostat->properties->temperature_fahrenheit, "\n";
  echo "Fan running: ", $living_room_thermostat->properties->is_fan_running ? 'true' : 'false', "\n";

  // View the entire returned device object.
  echo json_encode($living_room_thermostat, JSON_PRETTY_PRINT);
  ```

  ```csharp C# theme={null}
  // Coming soon!
  ```
</CodeGroup>

**Output:**

<CodeGroup>
  ```json JavaScript theme={null}
  Current temperature: 70
  Fan running: false
  {
    device_id: '11111111-1111-1111-2222-444444444444',
    workspace_id: '00000000-0000-0000-0000-000000000000',
    connected_account_id: '11111111-1111-1111-1111-222222222222',
    created_at: '2024-10-03T22:12:15.666Z',
    properties: {
      manufacturer: 'nest',
      online: true,
      temperature_celsius: 21.11111111111111,
      temperature_fahrenheit: 70,
      relative_humidity: 0.36,
      is_cooling: false,
      is_heating: false,
      is_fan_running: false,
      current_climate_setting: {
        display_name: 'Manual Setting',
        fan_mode_setting: 'auto',
        hvac_mode_setting: 'heat',
        manual_override_allowed: true,
        heating_set_point_celsius: 21.11111111111111,
        heating_set_point_fahrenheit: 70
      },
      ...
    },
    can_hvac_cool: true,
    can_hvac_heat: true,
    can_hvac_heat_cool: true,
    can_turn_off_hvac: true,
    ...
  }
  ```

  ```json cURL theme={null}
  Current temperature: 70
  Fan running: false
  {
    "device_id": "11111111-1111-1111-2222-444444444444",
    "workspace_id": "00000000-0000-0000-0000-000000000000",
    "connected_account_id": "11111111-1111-1111-1111-222222222222",
    "created_at": "2024-10-03T22:12:15.666Z",
    "properties": {
      "manufacturer": "nest",
      "online": true,
      "temperature_celsius": 21.11111111111111,
      "temperature_fahrenheit": 70,
      "relative_humidity": 0.36,
      "is_cooling": false,
      "is_heating": false,
      "is_fan_running": false,
      "current_climate_setting": {
        "display_name": "Manual Setting",
        "fan_mode_setting": "auto",
        "hvac_mode_setting": "heat",
        "manual_override_allowed": true,
        "heating_set_point_celsius": 21.11111111111111,
        "heating_set_point_fahrenheit": 70
      },
      ...
    },
    "can_hvac_cool": true,
    "can_hvac_heat": true,
    "can_hvac_heat_cool": true,
    "can_turn_off_hvac": true,
    ...
  }
  ```

  ```json Python theme={null}
  'Current temperature: 70'
  'Fan running: False'
  Device(
    device_id='11111111-1111-1111-2222-444444444444',
    workspace_id='00000000-0000-0000-0000-000000000000',
    connected_account_id='11111111-1111-1111-1111-222222222222',
    created_at='2024-10-03T22:12:15.666Z',
    properties={
      'manufacturer': 'nest',
      'online': True,
      'temperature_celsius': 21.11111111111111,
      'temperature_fahrenheit': 70,
      'relative_humidity': 0.36,
      'is_cooling': False,
      'is_heating': False,
      'is_fan_running': False,
      'current_climate_setting': {
        'display_name': 'Manual Setting',
        'fan_mode_setting': 'auto',
        'heating_set_point_celsius': 21.11111111111111,
        'heating_set_point_fahrenheit': 70,
        'hvac_mode_setting': 'heat',
        'manual_override_allowed': True
      },
      ...
    },
    can_hvac_cool=True,
    can_hvac_heat=True,
    can_hvac_heat_cool=True,
    can_turn_off_hvac=True,
    ...
  )
  ```

  ```json Ruby theme={null}
  Current temperature: 70
  Fan running: false
  <Seam::Resources::Device:0x005f0
    device_id="11111111-1111-1111-2222-444444444444"
    workspace_id="00000000-0000-0000-0000-000000000000"
    connected_account_id="11111111-1111-1111-1111-222222222222"
    created_at=2024-10-03 22:12:15.666 UTC
    properties=#<Seam::DeepHashAccessor:0x0000016b1791f068 @data={
      "manufacturer"=>"nest",
      "online"=>true,
      "temperature_celsius"=>21.11111111111111,
      "temperature_fahrenheit"=>70,
      "relative_humidity"=>0.36,
      "is_cooling"=>false,
      "is_heating"=>false,
      "is_fan_running"=>false,
      "current_climate_setting"=>{
        "display_name"=>"Manual Setting",
        "fan_mode_setting"=>"auto",
        "hvac_mode_setting"=>"heat",
        "manual_override_allowed"=>true,
        "heating_set_point_celsius"=>21.11111111111111,
        "heating_set_point_fahrenheit"=>70
      },
      ...
    }>
    can_hvac_cool=true
    can_hvac_heat=true
    can_hvac_heat_cool=true
    can_turn_off_hvac=true
    ...
  >
  ```

  ```json PHP theme={null}
  Current temperature: 70
  Fan running: false
  {
    "device_id": "11111111-1111-1111-2222-444444444444",
    "workspace_id": "00000000-0000-0000-0000-000000000000",
    "connected_account_id": "11111111-1111-1111-1111-222222222222",
    "created_at": "2024-10-03T22:12:15.666Z",
    "properties": {
      "manufacturer": "nest",
      "online": true,
      "temperature_celsius": 21.11111111111111,
      "temperature_fahrenheit": 70,
      "relative_humidity": 0.36,
      "is_cooling": false,
      "is_heating": false,
      "is_fan_running": false,
      "current_climate_setting": {
        "display_name": "Manual Setting",
        "fan_mode_setting": "auto",
        "heating_set_point_celsius": 21.11111111111111,
        "heating_set_point_fahrenheit": 70,
        "hvac_mode_setting": "heat",
        "manual_override_allowed": true,
        ...
      },
      ...
    },
    "can_hvac_cool": true,
    "can_hvac_heat": true,
    "can_hvac_heat_cool": true,
    "can_turn_off_hvac": true,
    ...
  }
  ```

  ```json C# theme={null}
  // Coming soon!
  ```
</CodeGroup>

***

## Step 4: Control your Google Nest thermostat

Next, you can use the Seam API to control your Google Nest thermostat.

Each device that you connect to Seam has a specific set of capabilities. These capabilities define the Seam API actions that you can use. For thermostats, device-specific capabilities include whether you can [set the HVAC mode](/capability-guides/thermostats/configure-current-climate-settings) to `heat`, `cool`, or `heat_cool`. Seam's intuitive and granular [capability flags](/capability-guides/device-and-system-capabilities#capability-flags) inform your application about what features and behaviors each device supports. Notice the capability flags within the code samples in this guide.

Seam provides additional actions for thermostats, such as setting the fan mode, creating and scheduling climate presets, setting temperature thresholds, and configuring weekly thermostat programs. You can also monitor for Seam thermostat-related events, such as reported temperatures outside your set thresholds.

Try out the following actions on your Google Nest thermostat:

* [ ] [Set the HVAC mode](#set-the-hvac-mode)
* [ ] [Create and schedule climate presets](#create-and-schedule-climate-presets)
* [ ] [Configure a weekly thermostat program](#configure-a-weekly-thermostat-program)

### Set the HVAC mode

To set the HVAC mode, use any of the following endpoints or their equivalents in the Seam SDKs:

* `/thermostats/heat`
* `/thermostats/cool`
* `/thermostats/heat_cool`
* `/thermostats/off`
* `/thermostats/set_hvac_mode`

  This endpoint is a consolidated version of the other four endpoints.

Specify the thermostat that you want to control by including the `device_id` in the request body. Also, include the desired temperature [set point](/capability-guides/thermostats/understanding-thermostat-concepts/set-points).

In this example, set the HVAC mode to `heat` and the desired heating set point to 68 °F.

Each of these HVAC mode endpoints returns an [action attempt](/core-concepts/action-attempts) to track the progress of the operation.

**Code:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  // Confirm that the device supports heat mode.
  // You're using a capability flag here!
  if (livingRoomThermostat.can_hvac_heat) {
    // Set the HVAC mode
    // and return an action attempt.
    const actionAttempt = await seam.thermostats.heat({
      device_id: livingRoomThermostat.device_id,
      heating_set_point_fahrenheit: 68,
    })
  }
  ```

  ```bash cURL theme={null}
  # Confirm that the device supports heat mode.
  # You're using a capability flag here!
  if  $(jq -r '.can_hvac_heat' <<< ${living_room_thermostat}); then \
    # Set the HVAC mode
    # and return an action attempt.
    curl -X 'POST' \
      'https://connect.getseam.com/thermostats/heat' \
      -H 'accept: application/json' \
      -H "Authorization: Bearer ${SEAM_API_KEY}" \
      -H 'Content-Type: application/json' \
      -d "{
        \"device_id\": \"$(jq -r '.device_id' <<< ${living_room_thermostat})\",
        \"heating_set_point_fahrenheit\": 68
    }";
  fi
  ```

  ```python Python theme={null}
  # Confirm that the device supports heat mode.
  # You're using a capability flag here!
  if living_room_thermostat.can_hvac_heat:
    # Set the HVAC mode
    # and return an action attempt.
    action_attempt = seam.thermostats.heat(
      device_id = living_room_thermostat.device_id,
      heating_set_point_fahrenheit = 68
    )
  ```

  ```ruby Ruby theme={null}
  # Confirm that the device supports heat mode.
  # You're using a capability flag here!
  if (living_room_thermostat.can_hvac_heat)
    # Set the HVAC mode
    # and return an action attempt.
    action_attempt = seam.thermostats.heat(
      device_id: living_room_thermostat.device_id,
      heating_set_point_fahrenheit: 68
    )
  end
  ```

  ```php PHP theme={null}
  // Confirm that the device supports heat mode.
  // You're using a capability flag here!
  if ($living_room_thermostat->can_hvac_heat) {
    // Set the HVAC mode
    // and return an action attempt.
    $action_attempt = $seam->thermostats->heat(
      device_id: $living_room_thermostat->device_id,
      heating_set_point_fahrenheit: 68
    );
  }
  ```

  ```csharp C# theme={null}
  // Coming soon!
  ```
</CodeGroup>

**Output:**

<CodeGroup>
  ```json JavaScript theme={null}
  {
    "actionAttempt": {
      "status": "success",
      "action_attempt_id": "11111111-2222-3333-4444-555555555555",
      "action_type": "SET_HVAC_MODE",
      "result": {},
      "error": null
    }
  }
  ```

  ```json cURL theme={null}
  {
    "action_attempt": {
      "status": "pending",
      "action_type": "SET_HVAC_MODE",
      "action_attempt_id": "11111111-2222-3333-4444-555555555555",
      "result": null,
      "error": null
    },
    "ok": true
  }
  ```

  ```json Python theme={null}
  ActionAttempt(
    action_attempt_id='11111111-2222-3333-4444-555555555555',
    action_type='SET_HVAC_MODE',
    status='success',
    result={},
    error=None
  )
  ```

  ```json Ruby theme={null}
  <Seam::Resources::ActionAttempt:0x005f0
    status="success"
    action_type="SET_HVAC_MODE"
    action_attempt_id="11111111-2222-3333-4444-555555555555"
    result={}
    error=nil>
  ```

  ```json PHP theme={null}
  {
    "action_attempt_id": "11111111-2222-3333-4444-555555555555",
    "action_type": "SET_HVAC_MODE",
    "error": null,
    "result": {},
    "status": "success"
  }
  ```

  ```json C# theme={null}
  // Coming soon!
  ```
</CodeGroup>

You can track the status of the operation to confirm that the device was set to heat mode successfully. Query `properties.current_climate_setting.hvac_mode_setting` for the device, [retrieve the action attempt](/api/action_attempts/get) by ID, or look for a [`thermostat.manually_adjusted` event](/api/thermostats/events#thermostat-manually_adjusted). Further, if you wanted to find out whether the HVAC system was currently heating, you could inspect `properties.is_heating` for the device.

To query `properties.current_climate_setting.hvac_mode_setting` for the device:

**Code:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  // Get the device by ID.
  const updatedLivingRoomThermostat = await seam.devices.get({
    device_id: livingRoomThermostat.device_id,
  })

  // Inspect properties.current_climate_setting.hvac_mode_setting
  // to confirm that setting the HVAC mode to heat was successful.
  console.log(
    updatedLivingRoomThermostat.properties.current_climate_setting
      .hvac_mode_setting,
  )
  ```

  ```bash cURL theme={null}
  # Get the device by ID.
  updated_living_room_thermostat=$(
    # Use GET or POST.
    curl -X 'GET' \
      'https://connect.getseam.com/devices/get' \
      -H 'accept: application/json' \
      -H "Authorization: Bearer ${SEAM_API_KEY}" \
      -H 'Content-Type: application/json' \
      -d "{
        \"device_id\": \"$(jq -r '.device_id' <<< ${living_room_thermostat})\"
    }")

  # Inspect properties.current_climate_setting.hvac_mode_setting
  # to confirm that setting the HVAC mode to heat was successful.
  echo $(jq -r '(.device.properties.current_climate_setting.hvac_mode_setting)' <<< ${updated_living_room_thermostat})
  ```

  ```python Python theme={null}
  # Get the device by ID.
  updated_living_room_thermostat = seam.devices.get(
    device_id = living_room_thermostat.device_id
  )

  # Inspect properties.current_climate_setting.hvac_mode_setting
  # to confirm that setting the HVAC mode to heat was successful.
  pprint(
    updated_living_room_thermostat.
    properties["current_climate_setting"]["hvac_mode_setting"]
  )
  ```

  ```ruby Ruby theme={null}
  # Get the device by ID.
  updated_living_room_thermostat = seam.devices.get(
    device_id: living_room_thermostat.device_id
  )

  # Inspect properties.current_climate_setting.hvac_mode_setting
  # to confirm that setting the HVAC mode to heat was successful.
  puts updated_living_room_thermostat.
    properties.current_climate_setting.hvac_mode_setting
  ```

  ```php PHP theme={null}
  // Get the device by ID.
  $updated_living_room_thermostat = $seam->devices->get(
    device_id: $living_room_thermostat->device_id
  );

  // Inspect properties.current_climate_setting.hvac_mode_setting
  // to confirm that setting the HVAC mode to heat was successful.
  echo $updated_living_room_thermostat->properties->
    current_climate_setting->hvac_mode_setting;
  ```

  ```csharp C# theme={null}
  // Coming soon!
  ```
</CodeGroup>

**Output:**

<CodeGroup>
  ```json JavaScript theme={null}
  heat
  ```

  ```json cURL theme={null}
  heat
  ```

  ```json Python theme={null}
  'heat'
  ```

  ```json Ruby theme={null}
  heat
  ```

  ```json PHP theme={null}
  heat
  ```

  ```json C# theme={null}
  // Coming soon!
  ```
</CodeGroup>

***

### Create and schedule climate presets

You can use the Seam API to create climate presets for Google Nest thermostats. Each climate preset is a saved group of settings, such as HVAC mode, fan mode, and temperature set points. Climate presets make it quick and easy to apply consistent climate settings for different scenarios. For example, you could create two climate presets: a comfort preset for when a vacation rental is occupied and an eco preset for when the vacation rental is empty.

You can schedule climate presets to start and stop whenever you'd like. You can even set a fallback climate preset, such as eco.

In this example, create comfort and eco climate presets, set eco as the fallback, and schedule the comfort climate preset to coincide with two vacation rental reservations.

**Code:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  // Confirm that the thermostat supports heat_cool mode
  // so that the climate presets can use this mode.
  if (updatedLivingRoomThermostat.can_hvac_heat_cool) {
    // Create the climate presets.
    await seam.thermostats.createClimatePreset({
      device_id: updatedLivingRoomThermostat.device_id,
      climate_preset_key: 'comfort',
      name: 'Comfort',
      fan_mode_setting: 'auto',
      hvac_mode_setting: 'heat_cool',
      cooling_set_point_celsius: 25,
      heating_set_point_celsius: 20,
    })

    await seam.thermostats.createClimatePreset({
      device_id: updatedLivingRoomThermostat.device_id,
      climate_preset_key: 'eco',
      name: 'Eco',
      fan_mode_setting: 'auto',
      hvac_mode_setting: 'heat_cool',
      cooling_set_point_celsius: 30,
      heating_set_point_celsius: 15,
    })

    // Then, set eco as the fallback climate setting.
    await seam.thermostats.setFallbackClimatePreset({
      device_id: updatedLivingRoomThermostat.device_id,
      climate_preset_key: 'eco',
    })

    // Now, schedule the comfort preset to coincide with two reservations.
    await seam.thermostats.schedules.create({
      device_id: updatedLivingRoomThermostat.device_id,
      name: "Jim's stay",
      climate_preset_key: 'comfort',
      starts_at: '2025-03-10T15:00:00Z',
      ends_at: '2025-03-15T12:00:00Z',
      is_override_allowed: true,
      max_override_period_minutes: 90,
    })

    await seam.thermostats.schedules.create({
      device_id: updatedLivingRoomThermostat.device_id,
      name: "Jane's stay",
      climate_preset_key: 'comfort',
      starts_at: '2025-03-17T15:00:00Z',
      ends_at: '2025-03-20T12:00:00Z',
      is_override_allowed: true,
      max_override_period_minutes: 90,
    })
  }
  ```

  ```bash cURL theme={null}
  # Confirm that the thermostat supports heat_cool mode
  # so that the climate presets can use this mode.
  if  $(jq -r '.device.can_hvac_heat_cool' <<< ${updated_living_room_thermostat}); then \
    # Create the climate presets.
    curl -X 'POST' \
      'https://connect.getseam.com/thermostats/create_climate_preset' \
      -H 'accept: application/json' \
      -H "Authorization: Bearer ${SEAM_API_KEY}" \
      -H 'Content-Type: application/json' \
      -d "{
        \"device_id\": \"$(jq -r '.device.device_id' <<< ${updated_living_room_thermostat})\",
        \"climate_preset_key\": \"comfort\",
        \"name\": \"Comfort\",
        \"fan_mode_setting\": \"auto\",
        \"hvac_mode_setting\": \"heat_cool\",
        \"cooling_set_point_celsius\": 25,
        \"heating_set_point_celsius\": 20
    }";

    curl -X 'POST' \
      'https://connect.getseam.com/thermostats/create_climate_preset' \
      -H 'accept: application/json' \
      -H "Authorization: Bearer ${SEAM_API_KEY}" \
      -H 'Content-Type: application/json' \
      -d "{
        \"device_id\": \"$(jq -r '.device.device_id' <<< ${updated_living_room_thermostat})\",
        \"climate_preset_key\": \"eco\",
        \"name\": \"Eco\",
        \"fan_mode_setting\": \"auto\",
        \"hvac_mode_setting\": \"heat_cool\",
        \"cooling_set_point_celsius\": 30,
        \"heating_set_point_celsius\": 15
    }";

    # Then, set eco as the fallback climate setting.
    curl -X 'POST' \
      'https://connect.getseam.com/thermostats/set_fallback_climate_preset' \
      -H 'accept: application/json' \
      -H "Authorization: Bearer ${SEAM_API_KEY}" \
      -H 'Content-Type: application/json' \
      -d "{
        \"device_id\": \"$(jq -r '.device.device_id' <<< ${updated_living_room_thermostat})\",
        \"climate_preset_key\": \"eco\"
    }";

    # Now, schedule the comfort preset to coincide with two reservations.
    curl -X 'POST' \
    'https://connect.getseam.com/thermostats/schedules/create' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d "{
      \"device_id\": \"$(jq -r '.device.device_id' <<< ${updated_living_room_thermostat})\",
      \"name\":  \"Jim's stay\",
      \"climate_preset_key\": \"comfort\",
      \"starts_at\": \"2025-03-10T15:00:00Z\",
      \"ends_at\": \"2025-03-15T12:00:00Z\",
      \"is_override_allowed\": true,
      \"max_override_period_minutes\": 90
    }";

    curl -X 'POST' \
    'https://connect.getseam.com/thermostats/schedules/create' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d "{
      \"device_id\": \"$(jq -r '.device.device_id' <<< ${updated_living_room_thermostat})\",
      \"name\":  \"Jane's stay\",
      \"climate_preset_key\": \"comfort\",
      \"starts_at\": \"2025-03-17T15:00:00Z\",
      \"ends_at\": \"2025-03-20T12:00:00Z\",
      \"is_override_allowed\": true,
      \"max_override_period_minutes\": 90
    }";
  fi
  ```

  ```python Python theme={null}
  # Confirm that the thermostat supports heat_cool mode
  # so that the climate presets can use this mode.
  if updated_living_room_thermostat.can_hvac_heat_cool:
    # Create the climate presets.
    seam.thermostats.create_climate_preset(
      device_id = updated_living_room_thermostat.device_id,
      climate_preset_key = "comfort",
      name = "Comfort",
      fan_mode_setting = "auto",
      hvac_mode_setting = "heat_cool",
      cooling_set_point_celsius = 25,
      heating_set_point_celsius = 20
    )

    seam.thermostats.create_climate_preset(
      device_id: updated_living_room_thermostat.device_id,
      climate_preset_key = "eco",
      name = "Eco",
      fan_mode_setting = "auto",
      hvac_mode_setting = "heat_cool",
      cooling_set_point_celsius = 30,
      heating_set_point_celsius = 15
    )

    # Then, set eco as the fallback climate setting.
    seam.thermostats.set_fallback_climate_preset(
      device_id = updated_living_room_thermostat.device_id,
      climate_preset_key = "eco"
    )

    # Now, schedule the comfort preset to coincide with two reservations.
    seam.thermostats.schedules.create(
      device_id = updated_living_room_thermostat.device_id,
      name = "Jim's stay",
      climate_preset_key = "comfort",
      starts_at = "2025-03-10T15:00:00Z",
      ends_at = "2025-03-15T12:00:00Z",
      is_override_allowed = True,
      max_override_period_minutes = 90
    )

    seam.thermostats.schedules.create(
      device_id = updated_living_room_thermostat.device_id,
      name = "Jane's stay",
      climate_preset_key = "comfort",
      starts_at = "2025-03-17T15:00:00Z",
      ends_at = "2025-03-20T12:00:00Z",
      is_override_allowed = True,
      max_override_period_minutes = 90
    )
  ```

  ```ruby Ruby theme={null}
  # Confirm that the thermostat supports heat_cool mode
  # so that the climate presets can use this mode.
  if (updated_living_room_thermostat.can_hvac_heat_cool)
    # Create the climate presets.
    seam.thermostats.create_climate_preset(
      device_id: updated_living_room_thermostat.device_id,
      climate_preset_key: "comfort",
      name: "Comfort",
      fan_mode_setting: "auto",
      hvac_mode_setting: "heat_cool",
      cooling_set_point_celsius: 25,
      heating_set_point_celsius: 20
    )

    seam.thermostats.create_climate_preset(
      device_id: updated_living_room_thermostat.device_id,
      climate_preset_key: "eco",
      name: "Eco",
      fan_mode_setting: "auto",
      hvac_mode_setting: "heat_cool",
      cooling_set_point_celsius: 30,
      heating_set_point_celsius: 15
    )

    # Then, set eco as the fallback climate setting.
    seam.thermostats.set_fallback_climate_preset(
      device_id: updated_living_room_thermostat.device_id,
      climate_preset_key: "eco"
    )

    # Now, schedule the comfort preset to coincide with two reservations.
    seam.thermostats.schedules.create(
      device_id: updated_living_room_thermostat.device_id,
      name: "Jim's stay",
      climate_preset_key: "comfort",
      starts_at: "2025-03-10T15:00:00Z",
      ends_at: "2025-03-15T12:00:00Z",
      is_override_allowed: true,
      max_override_period_minutes: 90
    )

    await seam.thermostats.schedules.create(
      device_id: updated_living_room_thermostat.device_id,
      name: "Jane's stay",
      climate_preset_key: "comfort",
      starts_at: "2025-03-17T15:00:00Z",
      ends_at: "2025-03-20T12:00:00Z",
      is_override_allowed: true,
      max_override_period_minutes: 90
    )
  end
  ```

  ```php PHP theme={null}
  // Confirm that the thermostat supports heat_cool mode
  // so that the climate presets can use this mode.
  if ($updated_living_room_thermostat->can_hvac_heat_cool) {
    // Create the climate presets.
    $seam->thermostats->create_climate_preset(
      device_id: $updated_living_room_thermostat->device_id,
      climate_preset_key: "comfort",
      name: "Comfort",
      fan_mode_setting: "auto",
      hvac_mode_setting: "heat_cool",
      cooling_set_point_celsius: 25,
      heating_set_point_celsius: 20
    );

    $seam->thermostats->create_climate_preset(
      device_id: $updated_living_room_thermostat->device_id,
      climate_preset_key: "eco",
      name: "Eco",
      fan_mode_setting: "auto",
      hvac_mode_setting: "heat_cool",
      cooling_set_point_celsius: 30,
      heating_set_point_celsius: 15
    );

    // Then, set eco as the fallback climate setting.
    $seam->thermostats->set_fallback_climate_preset(
      device_id: $updated_living_room_thermostat->device_id,
      climate_preset_key: "eco"
    );

    // Now, schedule the comfort preset to coincide with two reservations.
    $seam->thermostats->schedules->create(
      device_id: $updated_living_room_thermostat->device_id,
      name: "Jim's stay",
      climate_preset_key: "comfort",
      starts_at: "2025-03-10T15:00:00Z",
      ends_at: "2025-03-15T12:00:00Z",
      is_override_allowed: true,
      max_override_period_minutes: 90
    );

    $seam->thermostats->schedules->create(
      device_id: updated_living_room_thermostat.device_id,
      name: "Jane's stay",
      climate_preset_key: "comfort",
      starts_at: "2025-03-17T15:00:00Z",
      ends_at: "2025-03-20T12:00:00Z",
      is_override_allowed: true,
      max_override_period_minutes: 90
    );
  }
  ```

  ```csharp C# theme={null}
  // Coming soon!
  ```
</CodeGroup>

**Output:**

<CodeGroup>
  ```json JavaScript theme={null}
  {
    thermostat_schedule_id: '88888888-1111-1111-1111-111111111111',
    name: "Jim's stay",
    device_id: '11111111-1111-1111-2222-444444444444',
    climate_preset_key: 'comfort',
    starts_at: '2025-03-10T15:00:00.000Z',
    ends_at: '2025-03-15T12:00:00.000Z',
    is_override_allowed: true,
    max_override_period_minutes: 90,
    ...
  }
  {
    thermostat_schedule_id: '88888888-1111-1111-1111-222222222222',
    name: "Jane's stay",
    device_id: '11111111-1111-1111-2222-444444444444',
    climate_preset_key: 'comfort',
    starts_at: '2025-03-17T15:00:00.000Z',
    ends_at: '2025-03-20T12:00:00.000Z',
    is_override_allowed: true,
    max_override_period_minutes: 90,
    ...
  }
  ```

  ```json cURL theme={null}
  {
    "thermostat_schedule":{
      "thermostat_schedule_id":"88888888-1111-1111-1111-111111111111",
      "name":"Jim's stay",
      "device_id":"11111111-1111-1111-2222-444444444444",
      "climate_preset_key":"comfort",
      "starts_at":"2025-03-10T15:00:00.000Z",
      "ends_at":"2025-03-15T12:00:00.000Z",
      "is_override_allowed":true,
      "max_override_period_minutes":90,
      ...
    },
    "ok":true
  }
  {
    "thermostat_schedule":{
      "thermostat_schedule_id":"88888888-1111-1111-1111-222222222222",
      "name":"Jane's stay",
      "device_id":"11111111-1111-1111-2222-444444444444",
      "climate_preset_key":"comfort",
      "starts_at":"2025-03-17T15:00:00.000Z",
      "ends_at":"2025-03-20T12:00:00.000Z",
      "is_override_allowed":true,
      "max_override_period_minutes":90,
      ...
    },
    "ok":true
  }
  ```

  ```json Python theme={null}
  ThermostatSchedule(
    thermostat_schedule_id='88888888-1111-1111-1111-111111111111',
    name="Jim's stay",
    device_id='11111111-1111-1111-2222-444444444444',
    climate_preset_key='comfort',
    starts_at='2025-03-10T15:00:00.000Z',
    ends_at='2025-03-15T12:00:00.000Z',
    is_override_allowed=True,
    max_override_period_minutes=90,
    ...
  )
  ThermostatSchedule(
    thermostat_schedule_id='88888888-1111-1111-1111-222222222222',
    name="Jane's stay",
    device_id='11111111-1111-1111-2222-444444444444',
    climate_preset_key='comfort',
    starts_at='2025-03-17T15:00:00.000Z',
    ends_at='2025-03-20T12:00:00.000Z',
    is_override_allowed=True,
    max_override_period_minutes=90,
    ...
  )
  ```

  ```json Ruby theme={null}
  <Seam::Resources::ThermostatSchedule:0x005f0
    thermostat_schedule_id="88888888-1111-1111-1111-111111111111"
    name="Jim's stay"
    device_id="11111111-1111-1111-2222-444444444444"
    climate_preset_key="comfort"
    starts_at=2025-03-10 15:00:00 UTC
    ends_at=2025-03-15 12:00:00 UTC
    is_override_allowed=true
    max_override_period_minutes=90
    ...
  >
  <Seam::Resources::ThermostatSchedule:0x005f0
    thermostat_schedule_id="88888888-1111-1111-1111-222222222222"
    name="Jane's stay"
    device_id="11111111-1111-1111-2222-444444444444"
    climate_preset_key="comfort"
    starts_at=2025-03-17 15:00:00 UTC
    ends_at=2025-03-20 12:00:00 UTC
    is_override_allowed=true
    max_override_period_minutes=90
    ...
  >
  ```

  ```json PHP theme={null}
  {
    "thermostat_schedule_id":"88888888-1111-1111-1111-111111111111",
    "name":"Jim's stay",
    "device_id":"11111111-1111-1111-2222-444444444444",
    "climate_preset_key":"comfort",
    "starts_at":"2025-03-10T15:00:00.000Z",
    "ends_at":"2025-03-15T12:00:00.000Z",
    "is_override_allowed":true,
    "max_override_period_minutes":90,
    ...
  }
  {
    "thermostat_schedule_id":"88888888-1111-1111-1111-222222222222",
    "name":"Jane's stay",
    "device_id":"11111111-1111-1111-2222-444444444444",
    "climate_preset_key":"comfort",
    "starts_at":"2025-03-17T15:00:00.000Z",
    "ends_at":"2025-03-20T12:00:00.000Z",
    "is_override_allowed":true,
    "max_override_period_minutes":90,
    ...
  }
  ```

  ```json C# theme={null}
  // Coming soon!
  ```
</CodeGroup>

***

### Configure a weekly thermostat program

You can use the Seam API to create a thermostat weekly program for your Google Nest thermostat. This standard feature of smart thermostats enables you to define full-week programs that are made up of reusable daily programs. Each daily program consists of a set of thermostat daily program periods, that is, time blocks with associated climate presets.

In this example, create a weekday daily program and a weekend daily program. Then, combine these daily programs into a weekly program by assigning a daily program to each day of the week.

**Code:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  // Create the daily programs.
  const weekdayProgram = await seam.thermostats.dailyPrograms.create({
    device_id: updatedLivingRoomThermostat.device_id,
    name: 'Weekday Program',
    periods: [
      { starts_at_time: '07:00:00', climate_preset_key: 'Home' },
      { starts_at_time: '09:00:00', climate_preset_key: 'Away' },
      { starts_at_time: '18:00:00', climate_preset_key: 'Home' },
      { starts_at_time: '22:00:00', climate_preset_key: 'Sleep' },
    ],
  })

  const weekendProgram = await seam.thermostats.dailyPrograms.create({
    device_id: updatedLivingRoomThermostat.device_id,
    name: 'Weekend Program',
    periods: [
      { starts_at_time: '08:00:00', climate_preset_key: 'Home' },
      { starts_at_time: '23:00:00', climate_preset_key: 'Sleep' },
    ],
  })

  // Use the daily programs to set the weekly program.
  await seam.thermostats.updateWeeklyProgram({
    device_id: updatedLivingRoomThermostat.device_id,
    monday_program_id: weekdayProgram.thermostat_daily_program_id,
    tuesday_program_id: weekdayProgram.thermostat_daily_program_id,
    wednesday_program_id: weekdayProgram.thermostat_daily_program_id,
    thursday_program_id: weekdayProgram.thermostat_daily_program_id,
    friday_program_id: weekdayProgram.thermostat_daily_program_id,
    saturday_program_id: weekendProgram.thermostat_daily_program_id,
    sunday_program_id: weekendProgram.thermostat_daily_program_id,
  })
  ```

  ```bash cURL theme={null}
  # Create the daily programs.
  weekday_program=$(curl -X 'POST' \
    'https://connect.getseam.com/thermostats/daily_programs/create' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d "{
      \"device_id\": \"$(jq -r '.device.device_id' <<< ${updated_living_room_thermostat})\",
      \"name\":  \"Weekday Program\",
      \"periods\": [
      { \"starts_at_time\": \"07:00:00\", \"climate_preset_key\": \"Home\" },
      { \"starts_at_time\": \"09:00:00\", \"climate_preset_key\": \"Away\" },
      { \"starts_at_time\": \"18:00:00\", \"climate_preset_key\": \"Home\" },
      { \"starts_at_time\": \"22:00:00\", \"climate_preset_key\": \"Sleep\" }
    ]
  }")
  weekday_program_id=$(jq -r '.thermostat_daily_program_id' <<< ${weekday_program})

  weekend_program=$(curl -X 'POST' \
    'https://connect.getseam.com/thermostats/daily_programs/create' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d "{
      \"device_id\": \"$(jq -r '.device.device_id' <<< ${updated_living_room_thermostat})\",
      \"name\":  \"Weekend Program\",
      \"periods\": [
      { \"starts_at_time\": \"08:00:00\", \"climate_preset_key\": \"Home\" },
      { \"starts_at_time\": \"23:00:00\", \"climate_preset_key\": \"Sleep\" }
    ]
  }")
  weekend_program_id=$(jq -r '.thermostat_daily_program_id' <<< ${weekend_program})

  # Use the daily programs to set the weekly program.
  curl -X 'POST' \
    'https://connect.getseam.com/thermostats/update_weekly_program' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d "{
      \"device_id\": \"$(jq -r '.device.device_id' <<< ${updated_living_room_thermostat})\",
      \"monday_program_id\": \"${weekday_program_id}\",
      \"tuesday_program_id\": \"${weekday_program_id}\",
      \"wednesday_program_id\": \"${weekday_program_id}\",
      \"thursday_program_id\": \"${weekday_program_id}\",
      \"friday_program_id\": \"${weekday_program_id}\",
      \"saturday_program_id\": \"${weekend_program_id}\",
      \"sunday_program_id\": \"${weekend_program_id}\"
  }"
  ```

  ```python Python theme={null}
  # Create the daily programs.
  weekday_program = seam.thermostats.daily_programs.create(
    device_id = updated_living_room_thermostat.device_id,
    name = "Weekday Program",
    periods = [
      { "starts_at_time": "07:00:00", "climate_preset_key": "Home" },
      { "starts_at_time": "09:00:00", "climate_preset_key": "Away" },
      { "starts_at_time": "18:00:00", "climate_preset_key": "Home" },
      { "starts_at_time": "22:00:00", "climate_preset_key": "Sleep" }
    ]
  )

  weekend_program = seam.thermostats.daily_programs.create(
    device_id = updated_living_room_thermostat.device_id,
    name = "Weekend Program",
    periods = [
      { "starts_at_time": "08:00:00", "climate_preset_key": "Home" },
      { "starts_at_time": "23:00:00", "climate_preset_key": "Sleep" }
    ]
  )

  # Use the daily programs to set the weekly program.
  seam.thermostats.update_weekly_program(
    device_id = updated_living_room_thermostat.device_id,
    monday_program_id = weekday_program.thermostat_daily_program_id,
    tuesday_program_id = weekday_program.thermostat_daily_program_id,
    wednesday_program_id = weekday_program.thermostat_daily_program_id,
    thursday_program_id = weekday_program.thermostat_daily_program_id,
    friday_program_id = weekday_program.thermostat_daily_program_id,
    saturday_program_id = weekend_program.thermostat_daily_program_id,
    sunday_program_id = weekend_program.thermostat_daily_program_id
  )
  ```

  ```ruby Ruby theme={null}
  # Create the daily programs.
  weekday_program = seam.thermostats.daily_programs.create(
    device_id: updated_living_room_thermostat.device_id,
    name: "Weekday Program",
    periods: [
      { "starts_at_time": "07:00:00", "climate_preset_key": "Home" },
      { "starts_at_time": "09:00:00", "climate_preset_key": "Away" },
      { "starts_at_time": "18:00:00", "climate_preset_key": "Home" },
      { "starts_at_time": "22:00:00", "climate_preset_key": "Sleep" }
    ]
  )

  weekend_program = seam.thermostats.daily_programs.create(
    device_id: updated_living_room_thermostat.device_id,
    name: "Weekend Program",
    periods: [
      { "starts_at_time": "08:00:00", "climate_preset_key": "Home" },
      { "starts_at_time": "23:00:00", "climate_preset_key": "Sleep" }
    ]
  )

  # Use the daily programs to set the weekly program.
  seam.thermostats.update_weekly_program(
    device_id: updated_living_room_thermostat.device_id,
    monday_program_id: weekday_program.thermostat_daily_program_id,
    tuesday_program_id: weekday_program.thermostat_daily_program_id,
    wednesday_program_id: weekday_program.thermostat_daily_program_id,
    thursday_program_id: weekday_program.thermostat_daily_program_id,
    friday_program_id: weekday_program.thermostat_daily_program_id,
    saturday_program_id: weekend_program.thermostat_daily_program_id,
    sunday_program_id: weekend_program.thermostat_daily_program_id
  )
  ```

  ```php PHP theme={null}
  // Create the daily programs.
  $weekday_program = $seam->thermostats->daily_programs->create(
    device_id: $updated_living_room_thermostat->device_id,
    name: "Weekday Program",
    periods: [
      { "starts_at_time": "07:00:00", "climate_preset_key": "Home" },
      { "starts_at_time": "09:00:00", "climate_preset_key": "Away" },
      { "starts_at_time": "18:00:00", "climate_preset_key": "Home" },
      { "starts_at_time": "22:00:00", "climate_preset_key": "Sleep" }
    ]
  );

  $weekend_program = $seam->thermostats->daily_programs->create(
    device_id: $updated_living_room_thermostat->device_id,
    name: "Weekend Program",
    periods: [
      { "starts_at_time": "08:00:00", "climate_preset_key": "Home" },
      { "starts_at_time": "23:00:00", "climate_preset_key": "Sleep" }
    ]
  );

  // Use the daily programs to set the weekly program.
  $seam->thermostats->update_weekly_program(
    device_id: $updated_living_room_thermostat->device_id,
    monday_program_id: $weekday_program->thermostat_daily_program_id,
    tuesday_program_id: $weekday_program->thermostat_daily_program_id,
    wednesday_program_id: $weekday_program->thermostat_daily_program_id,
    thursday_program_id: $weekday_program->thermostat_daily_program_id,
    friday_program_id: $weekday_program->thermostat_daily_program_id,
    saturday_program_id: $weekend_program->thermostat_daily_program_id,
    sunday_program_id: $weekend_program->thermostat_daily_program_id
  );
  ```

  ```csharp C# theme={null}
  // Coming soon!
  ```
</CodeGroup>

**Output:**

<CodeGroup>
  ```json JavaScript theme={null}
  {
    "status": "success",
    "action_attempt_id": "11111111-2222-3333-4444-666666666666",
    "action_type": "PUSH_THERMOSTAT_PROGRAMS",
    "result": {},
    "error": null
  }
  ```

  ```json cURL theme={null}
  {
    "action_attempt": {
      "status": "pending",
      "action_type": "PUSH_THERMOSTAT_PROGRAMS",
      "action_attempt_id": "11111111-2222-3333-4444-666666666666",
      "result": null,
      "error": null
    },
    "ok": true
  }
  ```

  ```json Python theme={null}
  ActionAttempt(
    action_attempt_id='11111111-2222-3333-4444-666666666666',
    action_type='PUSH_THERMOSTAT_PROGRAMS',
    status='success',
    result={},
    error=None
  )
  ```

  ```json Ruby theme={null}
  <Seam::Resources::ActionAttempt:0x005f0
    status="success"
    action_type="PUSH_THERMOSTAT_PROGRAMS"
    action_attempt_id="11111111-2222-3333-4444-666666666666"
    result={}
    error=nil>
  ```

  ```json PHP theme={null}
  {
    "status": "success",
    "action_attempt_id": "11111111-2222-3333-4444-666666666666",
    "action_type": "PUSH_THERMOSTAT_PROGRAMS",
    "result": {},
    "error": null
  }
  ```

  ```json C# theme={null}
  // Coming soon!
  ```
</CodeGroup>

***

## Step 5: Connect a real Google Nest thermostat

Now that you have learned the basics of using the Seam API, you can connect and control a real Google Nest device. To do so, make sure to switch to a [non-sandbox workspace](/core-concepts/workspaces#production-workspaces) and [API key](/core-concepts/authentication/api-keys).

For more details about setting up your real Google Nest thermostat, see the [Google Nest thermostats integration guide](/index).

***

## Step 6: Build your application!

Seam makes it easy to develop your application. The robust Seam API and Seam SDKs in a wide variety of programming languages provide robust, up-to-date information about your thermostats. We also provide helpful thermostat-related events that enable you to monitor the status of your thermostats and the connected HVAC systems. Further, our simulation endpoints make it easy for you to test your thermostat app against events that can be difficult to orchestrate in your quality assurance (QA) environment using real devices.

***

## Next steps

Now that you've completed this getting started guide for Google Nest thermostats, you can learn more about what you can do with the Seam API.

* [ ] **Explore**\
  See the [other devices and system integrations](/device-and-system-integration-guides) that Seam supports.
* [ ] **Learn**\
  Read about Seam [concepts](/core-concepts/overview) and the [device and system capabilities ](/capability-guides/device-and-system-capabilities)that Seam supports.
* [ ] **Expand your abilities**\
  Find out what other [thermostat actions](/capability-guides/thermostats) you can perform using the Seam API.
* [ ] **Use webhooks**\
  Learn how to use [webhooks](/developer-tools/webhooks) as an efficient way to receive device events.
* [ ] **Find out more**\
  Explore the other types of devices and systems that you can control with Seam, including [smart locks](/low-level-apis/smart-locks), [access control systems](/low-level-apis/access-systems), and [noise sensors](/capability-guides/noise-sensors).
* [ ] **Develop for mobile access**\
  Learn about Seam's [mobile access solution](/capability-guides/mobile-access).

<Info>
  If you have any questions or want to report an issue, email us at
  [support@seam.co](mailto:support@seam.co).
</Info>

***

## Quick links

<CardGroup>
  <Card title="Get an API Key (free)" href="https://console.seam.co/">
    Sign up for the Seam Console and get your API keys. →
  </Card>

  <Card title="Contact Sales" href="https://www.seam.co/contact-us">
    Got a project or a specific question? Contact our team to get answers. →
  </Card>
</CardGroup>


# Google Nest Setup Guide
Source: https://docs.seam.co/device-and-system-integration-guides/google-nest-thermostats/google-nest-setup-guide

Connect your Google Nest thermostats to Seam.

This guide walks you through connecting your Google Nest thermostats to Seam. Your thermostats must already be set up and working in the Google Home app before proceeding.

## 1. Set up Google Device Access

Before connecting Nest devices to Seam, you must create a [Google Device Access](https://developers.google.com/nest/device-access) project -- including an associated OAuth client -- and provide information about this project to Seam through the [Seam Console](/core-concepts/seam-console).

We recommend that you apply for [Google Commercial Development](https://developers.google.com/nest/device-access/project/apply) for your Nest devices. For detailed instructions, see [Obtain Google Nest Device Access and Commercial Development](/device-and-system-integration-guides/google-nest-thermostats/obtain-google-nest-device-access-and-commercial-development).

<Info>
  Note the restrictive [rate
  limits](https://developers.google.com/nest/device-access/project/limits) in
  the Google Device Access Sandbox environment while testing the integration
  with customers.
</Info>

The period of time that Google takes to approve Commercial Development may range from a week to more than a month. For more information, see [Apply for Commercial Development](https://developers.google.com/nest/device-access/project/apply) on the Google Device Access site.

Once Google approves your Commercial Development application, you can gradually scale the number of managed devices as you proceed through the Google stages to reach [Google certification for Commercial Production](https://developers.google.com/nest/device-access/project/apply#certification_for_commercial_production).

## 2. Create a Google Home account

If you don't already have one, download the [Google Home app](https://home.google.com/get-app/) and create an account. Add your Nest thermostats in the app and confirm they are online.

## 3. Connect Google Nest to Seam

Use the login credentials for your Google Home account to log in through the [Seam Connect Webview](/core-concepts/connect-webviews) and authorize Seam to access your devices.

## 4. Verify the connection

After completing the Connect Webview, confirm that your Nest thermostats appear in your Seam workspace and show an **online** status.

***

## Troubleshooting

If you see a "No access to partner" error in the Connect Webview:

* Verify that you have [obtained Google Commercial Development](/device-and-system-integration-guides/google-nest-thermostats/obtain-google-nest-device-access-and-commercial-development). Until you obtain Commercial Development, you can only connect devices associated directly with your own Google test users' accounts.
* Confirm that you added the developer email address as a home member in the Google Home app settings.

If your devices don't appear after connecting:

* Confirm that your Nest thermostats are online in the Google Home app.
* Verify that you logged in with the same Google account that owns the thermostats.
* Wait a few minutes for the initial sync to complete, then refresh your device list.


# Sandbox Google Nest Thermostats
Source: https://docs.seam.co/device-and-system-integration-guides/google-nest-thermostats/google-nest-thermostats-sample-data

Add a virtual Google Nest thermostat to your Seam sandbox workspace using these sample credentials to test your integration without real hardware.

Use the following set of credentials to add a virtual [Google Nest thermostat](/device-and-system-integration-guides/google-nest-thermostats) to your Seam [sandbox workspace](/core-concepts/workspaces#sandbox-workspaces):

| Email Address                                                                              | Password |
| ------------------------------------------------------------------------------------------ | -------- |
| [jane@example.com](mailto:jane@example.com) or any email address in the example.com domain | 1234     |


# Google Nest Thermostats
Source: https://docs.seam.co/device-and-system-integration-guides/google-nest-thermostats/index

Guide for using Nest thermostats with Seam

<img alt="Nest logo" />

## Overview

Google produces Nest smart thermostats as part of the Google smart home product group. Nest thermostats are designed to lower energy costs through energy efficiency features, such as remote climate monitoring and control, as well as climate setting scheduling. Google also produces an optional Nest Temperature Sensor accessory to prioritize certain rooms.

***

## Supported Devices

<DeviceList />

This integration supports all [Nest thermostats](https://store.google.com/us/category/nest_thermostats).

For detailed information about the Google Nest devices that Seam supports, see our [Nest Supported Devices page](https://www.seam.co/manufacturers/nest).

***

## Supported Features

We support the following features:

* [Configuring current thermostat settings](/capability-guides/thermostats/configure-current-climate-settings)
* [Creating and managing climate presets](/capability-guides/thermostats/creating-and-managing-climate-presets)
* [Creating and managing thermostat schedules](/capability-guides/thermostats/creating-and-managing-thermostat-schedules)
* [Creating and managing thermostat weekly programs](/capability-guides/thermostats/creating-and-managing-thermostat-programs)
* [Setting and monitoring temperature thresholds](/capability-guides/thermostats/setting-and-monitoring-temperature-thresholds)

***

### Device Provider Key

Seam identifies these devices with the `google_nest` device provider key. By default, a [Connect Webview](/core-concepts/connect-webviews) displays all of the stable providers that Seam supports, so your users can connect their Nest devices without you specifying a provider list. To narrow what a Connect Webview displays, see [Customize the Brands to Display in Your Connect Webviews](/core-concepts/connect-webviews/customizing-connect-webviews#customize-the-brands-to-display-in-your-connect-webviews).

***

## Setup Instructions

For instructions on connecting Google Nest thermostats to Seam, see the [Google Nest Setup Guide](./google-nest-setup-guide).

***

## Brand-Specific Features

Google Nest thermostats support an eco HVAC mode. To set a Google Nest thermostat to eco mode, use the [`/thermostats/set_hvac_mode`](/api/thermostats/set_hvac_mode) endpoint. For details, see [HVAC Mode](/capability-guides/thermostats/understanding-thermostat-concepts/hvac-mode) and [Setting the Current HVAC and Fan Mode Settings](/capability-guides/thermostats/configure-current-climate-settings).

***

## Troubleshooting

If you have not yet [obtained Google Commercial Development](/device-and-system-integration-guides/google-nest-thermostats/obtain-google-nest-device-access-and-commercial-development), and your end user attempts to connect a Google Nest thermostat to Seam using a Connect Webview, the Connect Webview displays the following error:

> No access to partner
>
> Information could not be retrieved. Please contact \<Your Company Name> to verify that your account has been properly set up. You may need to add the developer email address as a home member in the Google Home app settings.

Note that, until you obtain Google Commercial Development, you can only connect devices associated directly with your own Google test users' accounts to Seam.

***

## Where to Order

Order Nest thermostats from the Google online store or from Amazon.

<CardGroup>
  <Card title="Google Online Store" href="https://store.google.com/us/category/nest_thermostats" />

  <Card title="Nest Products on Amazon" href="https://amzn.to/4aaJfus" />
</CardGroup>

***


# Obtain Google Nest Device Access and Commercial Development
Source: https://docs.seam.co/device-and-system-integration-guides/google-nest-thermostats/obtain-google-nest-device-access-and-commercial-development

Learn how to create a Google Nest Device Access project and apply for Google Commercial Development, which enable you to integrate your Nest thermostats with Seam.

To control Nest devices using Seam, you must first create a [Google Device Access](https://developers.google.com/nest/device-access) project—including an associated OAuth client—and provide information about this project to Seam through the [Seam Console](/core-concepts/seam-console). We recommend that you apply for [Google Commercial Development](https://developers.google.com/nest/device-access/project/apply) for your Nest devices.

<Info>
  The period of time that Google takes to approve Commercial Development may range from a week to more than a month. For more information, see [Apply for Commercial Development](https://developers.google.com/nest/device-access/project/apply) on the Google Device Access site.

  Further, once Google approves your Commercial Development application, you can gradually scale the number of managed devices as you proceed through the Google stages to reach [Google certification for Commercial Production](https://developers.google.com/nest/device-access/project/apply#certification_for_commercial_production).
</Info>

***

## Google Developer Account and Rate Limits

Note the restrictive [account and rate limits](https://developers.google.com/nest/device-access/project/limits) in the Google Device Access Sandbox environment while testing the integration with customers.

***

## 1. Start Google Device Access Project Creation

Sign in to your Google account and start the process of creating a Google Device Access Project.

1. Open a web browser and go to the following URL:\
   [https://developers.google.com/nest/device-access](https://developers.google.com/nest/device-access)

2. Click **Go to Console**.

3. Sign in to your Google account.

4. If you have not yet paid the Google Developer Registration Fee (currently, US\$5) to access the Google Device Access Console, perform the following steps:

   1. Select the checkbox to agree to the Google terms of service and then click **Continue to payment**.
   2. Add a credit or debit card if you have not done so already.
   3. Click **Buy**.

   When the purchase is complete, Google displays the Device Access Console welcome page.

5. Click **Create project**.

6. Type a name for your Nest development project and then click **Next**.

## 2. Create an OAuth Client

Use the Google Cloud console to create an OAuth 2.0 client and then download the associated client ID and secret.

1. On the **Add your OAuth client ID** page, click **Learn more**.

<Warning>
  Google displays the **Authorize an Account** page in a separate browser tab or
  window. Do not close the original browser window or tab containing the **Add
  your OAuth client ID** page.
</Warning>

2. On the **Authorize an Account** page, click **Google Cloud Credentials**.

3. In the Google Cloud welcome dialog, select your country, select the checkbox to agree to the Google terms of service, and then click **Agree and Continue**.

4. On the Google Cloud **Credentials** page, click **Create Project**.

5. In the Google Cloud **Select a resource** window, click **New Project**.

6. In the Google Cloud **New Project** page, type a name for the new project, specify the organization and location, and then click **Create**.

7. On the Google Cloud **Create OAuth client ID** page, click **Configure Consent Screen**.

8. On the Google Cloud **OAuth consent screen** page, select the **External** user type and then click **Create**.

9. On the Google Cloud **Edit app registration** page, type the **App name**, **User support email**, and **Developer Contact information** **Email addresses** and then click **Save and Continue**.

10. Move to the bottom of the Google Cloud **Scopes** page and click **Save and Continue**.

11. On the Google Cloud **Test Users** page, click **Add Users**, add the Google account associated with a Nest thermostat as a test user, and then click **Save and Continue**.\
    It is important to remember that the initial Google Device Access Sandbox environment includes [account and rate limits](https://developers.google.com/nest/device-access/project/limits). Consequently, we recommend that you [apply for Google Commercial Development](#5-apply-for-google-commercial-development) as part of this procedure. In addition, before you obtain Google Commercial Development, you an only use the Seam API to control devices associated directly with the test user accounts that you specify on the **Test Users** page. For more information, see [Troubleshooting](/device-and-system-integration-guides/google-nest-thermostats#troubleshooting).

12. In the left navigation pane of the Google Cloud **Summary** page, click **Credentials**.

13. On the Google Cloud **Credentials** page, click **Create Credentials** > **OAuth client ID**.

14. On the Google Cloud **Create OAuth client ID** page, specify the following information:
    1. In the **Application type** field, select **Web application**.\\
    2. Type a name for the OAuth 2.0 client.
    3. In the **Authorized redirect URIs** area, click **Add URI** and then choose one of the following two options:
       * **Option 1 (easy):** Add the following URI to redirect to Seam:\
         [`https://connect.getseam.com/internal/nest/complete_oauth`](https://connect.getseam.com/internal/nest/complete_oauth)
       * **Option 2 (recommended):** Create a CNAME record in your DNS settings (for example, `nestoauth.mydomain.com`) and redirect it to the following URI:

         [`https://connect.getseam.com/internal/nest/complete_oauth`](https://connect.getseam.com/internal/nest/complete_oauth)\
         Setting up a CNAME ensures that the Google OAuth screen displays "continue to \[mydomain.com]" instead of "continue to getseam.com."

15. At the bottom of the Google Cloud **Create OAuth client ID** page, click **Create**.\
    The OAuth client created dialog displays the client ID and secret for the newly-created OAuth client.

16. In the **OAuth client created** dialog, click **Download JSON** and then click **OK**.

17. In the **OAuth 2.0 Client IDs** area on the Google Cloud **Credentials** page, click the copy button in the row that represents the client ID that you created.

<Info>
  Make sure to keep this copied OAuth client ID in the clipboard. You must paste
  this ID into a field later in this procedure.
</Info>

## 3. Enable the Google Smart Device Management API

To control Nest devices with the Seam API, you must enable the Google Smart Device Management API.

1. In the left navigation pane of the **Google Credentials** page, click **Enabled APIs & services** and then click **Enable APIs and Services**.
2. In the search box on the Google Cloud **API Library** welcome page, type `Smart Device Management API` and then press **Enter**.
3. In the search results, click **Smart Device Management API**.
4. On the **Product details** page for the Smart Device Management API, click **Enable**.

## 4. Complete Google Device Access Project Creation

Add the ID of the OAuth client that you created to the Google Device Access project that you are creating and then complete the project creation.

1. Return to the browser tab or window that contains the **Add your OAuth client ID** page from the beginning of this procedure.
2. In the **Enter your OAuth client ID** field, paste the copied OAuth client ID and then click **Next**.
3. On the **Events** page, click **Enable** and then click **Create project**.

## 5. Apply for Google Commercial Development

We recommend that you apply for [Google Commercial Development](https://developers.google.com/nest/device-access/project/apply), which enables you to control more devices. Before Google approves your Commercial Development application, you are subject to [account and rate limits](https://developers.google.com/nest/device-access/project/limits). Then, once Google approves your Commercial Development application, you can gradually scale the number of managed devices as you proceed through the Google stages to reach [Google certification for Commercial Production](https://developers.google.com/nest/device-access/project/apply#certification_for_commercial_production).

<Info>
  Once you have applied for Google Commercial Development, Google reviews your application. The period of time that Google takes to approve Commercial Development may range from a week to more than a month.

  It is imperative to be aware of this delay before testing your commercial application.

  However, we can help you test the settings and configuration of the original test device that you added to your account at the beginning of this procedure.
</Info>

1. On the Google project information page for your new project, click **Apply for commercial development**.
2. On the **Applying for Commercial Development** page, click **Next**.
3. On the **Google Non-Disclosure Agreement** page, type the following information:
   * **Company Name**
   * **Developer Name**
   * **Developer Corporate Email Address**
   * **Name of Company Authorized Representative**
4. Select the checkbox to agree to the Google Non-Disclosure Agreement and then click **Next**.
5. In the Google Commercial Development application, specify the requested information and then click **Apply**.\\

## 6. Provide Your Project Information to Seam through the Seam Console

In the [Seam Console](/core-concepts/seam-console), add your Google Device Access project information. It is not necessary to wait for Google Commercial Development approval before adding this information in the Seam Console.

<Info>
  You must be the owner of your Seam
  [workspace](/core-concepts/workspaces) to perform
  this procedure.
</Info>

1. Locate and note the following information:
   * Google Device Access project ID\
     Find this information on the project information page for your Google Device Access project.\\
   * OAuth client ID and secret\
     Find this information in the JSON file that you downloaded when creating the OAuth client earlier in this procedure.
2. In a web browser, go to [https://console.seam.co](https://console.seam.co).
3. [Log in to the Seam Console](/core-concepts/seam-console).
4. In upper-right corner of the Seam Console, click your username and then select **Workspace Settings**.
5. On the **Workspace Settings** page, next to **Nest Developer Settings**, click **Edit**.
6. In the **Nest Developer Settings** dialog, type or paste your project ID, Client ID, and Client secret.
7. Click **Save**.


# Get Started with Honeywell Resideo Thermostats
Source: https://docs.seam.co/device-and-system-integration-guides/honeywell-thermostats/get-started-with-honeywell-thermostats

Learn how to connect and control Honeywell Resideo thermostats with the Seam API.

## Overview

Seam provides a universal API to connect and control many brands of IoT devices and systems, including thermostats, smart locks, access control systems (ACSs), and noise sensors.

This guide gives you a rapid introduction to connecting and controlling your [Honeywell Resideo](https://www.seam.co/manufacturers/honeywell) thermostats using the Seam API. For application developers, you can use the Seam API in your app, and your users can authorize your app to control their devices using Seam.

For detailed information about the Honeywell Resideo devices that Seam supports, see our [Honeywell Resideo Supported Devices page](https://www.seam.co/manufacturers/honeywell).

To learn more about other IoT device and system brands that Seam supports—such as ecobee, Google Nest, Yale, Schlage, and many more—visit our [integration page](https://www.seam.co/supported-devices-and-systems).

<Check>
  This guide shows you how to install a Seam SDK and then control your Honeywell Resideo thermostat using the Seam API.

  Another easy way to learn about what you can do with the Seam API is to explore the [interactive Seam CLI](/core-concepts/seam-console/seam-online-cli), which you can access from directly within the [Seam Console](/core-concepts/seam-console).

  :arrow\_forward: [Go to the Seam Console!](https://console.seam.co/)
</Check>

***

## Step 1: Install a Seam SDK

Seam provides client libraries for many languages, including JavaScript, Python, Ruby, PHP, and others, as well as a Postman collection and an [OpenAPI](https://connect.getseam.com/openapi.json) spec.

* JavaScript / TypeScript ([npm](https://www.npmjs.com/package/seam), [GitHub](https://github.com/seamapi/javascript))
* Python ([pip](https://pypi.org/project/seam/), [GitHub](https://github.com/seamapi/python))
* Ruby Gem ([rubygem](https://rubygems.org/gems/seam), [GitHub](https://github.com/seamapi/ruby))
* PHP ([packagist](https://packagist.org/packages/seamapi/seam), [GitHub](https://github.com/seamapi/php))
* C# ([nuget](https://www.nuget.org/packages/Seam), [GitHub](https://github.com/seamapi/csharp))

First, install a Seam SDK, as follows:

<Tabs>
  <Tab title="JavaScript">
    ```bash theme={null}
    npm i seam
    ```
  </Tab>

  <Tab title="Python">
    ```bash theme={null}
    pip install seam
    # For some development environments, use pip3 in this command instead of pip.
    ```
  </Tab>

  <Tab title="Ruby">
    ```bash theme={null}
    bundle add seam
    ```
  </Tab>

  <Tab title="PHP">
    ```bash theme={null}
    composer require seamapi/seam
    ```
  </Tab>

  <Tab title="C#">
    Install using [nuget](https://www.nuget.org/packages/Seam).
  </Tab>
</Tabs>

Next, go to [https://console.seam.co/](https://console.seam.co/) and [sign up for Seam](/core-concepts/seam-console#create-a-seam-account) to get your [API key](/core-concepts/authentication/api-keys).

Then, export your API key as an environment variable.

```bash theme={null}
$ export SEAM_API_KEY=seam_test2bMS_94SrGUXuNR2JmJkjtvBQDg5c
```

<Info>
  This guide uses a [sandbox
  workspace](/core-concepts/workspaces#sandbox-workspaces).
  You can only connect virtual devices and systems in this type of workspace. If
  you want to connect a real Honeywell Resideo thermostat, use a [non-sandbox
  workspace](/core-concepts/workspaces#production-workspaces)
  and API key.
</Info>

***

## Step 2: Link your Honeywell Resideo account with Seam

To control your Honeywell Resideo thermostat using the Seam API, you must first authorize your Seam workspace to connect to your Honeywell Resideo account. If your application needs to connect to your users' Honeywell Resideo accounts, Seam provides fully-embedded, [customizable](/core-concepts/connect-webviews/customizing-connect-webviews) client-side [Connect Webviews](/core-concepts/connect-webviews) to collect their authorization securely. These user-friendly pre-built authorization flows walk your users through the process of granting your Seam workspace permission to control their Honeywell Resideo thermostats. The Connect Webview presents a flow that prompts your users to enter their credentials for their Honeywell Resideo account.

In this guide, you create a Connect Webview object. Then, you display the graphical component of the created Connect Webview and enter a set of sample credentials to connect a sandbox Honeywell Resideo account.

<Check>
  This guide shows you how to create a Connect Webview programmatically using the Seam API.

  The [Seam Console](/core-concepts/seam-console) provides another easy way to connect devices to your Seam workspace.

  Go to [https://console.seam.co/](https://console.seam.co/). On the **Devices** page, click **+ Add Devices**. Then, see [Authorize your workspace](#authorize-your-workspace) in this guide to complete the Connect Webview authorization flow.
</Check>

### Create a Connect Webview

Create a `connect_webview` object and then note the returned URL.

**Code:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  import { Seam } from 'seam'

  const seam = new Seam() // Seam automatically uses your exported SEAM_API_KEY.

  const connectWebview = await seam.connectWebviews.create()

  console.log(connectWebview.login_successful) // false

  // Use the returned Connect Webview URL to display
  // the Connect Webview authorization flow to your user.
  console.log(connectWebview.url)
  ```

  ```bash cURL theme={null}
  curl -X 'POST' \
    'https://connect.getseam.com/connect_webviews/create' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d '{}' | jq -r '"Login Successful (false): " + (.connect_webview.login_successful | tostring),
    "URL: " + .connect_webview.url'
    # Use the returned Connect Webview URL to display
    # the Connect Webview authorization flow to your user.
  ```

  ```python Python theme={null}
  from seam import Seam

  seam = Seam()  # Seam automatically uses your exported SEAM_API_KEY.

  connect_webview = seam.connect_webviews.create()

  assert connect_webview.login_successful is False

  # Use the returned Connect Webview URL to display
  # the Connect Webview authorization flow to your user.
  print(connect_webview.url)
  ```

  ```ruby Ruby theme={null}
  require "seam"

  seam = Seam.new() # Seam automatically uses your exported SEAM_API_KEY.

  connect_webview = seam.connect_webviews.create()

  puts connect_webview.login_successful # false

  # Use the returned Connect Webview URL to display
  # the Connect Webview authorization flow to your user.
  puts connect_webview.url
  ```

  ```php PHP theme={null}
  <?php
  require 'vendor/autoload.php';

  $seam = new Seam\SeamClient(); // Seam automatically uses your exported SEAM_API_KEY.

  $connect_webview = $seam->connect_webviews->create();

  echo $connect_webview->login_successful ? 'true' : 'false', "\n"; // false

  // Use the returned Connect Webview URL to display
  // the Connect Webview authorization flow to your user.
  echo $connect_webview->url;
  ```

  ```csharp C# theme={null}
  using Seam.Client;

  var seam = new SeamClient(apiToken: SEAM_API_KEY);

  var connectWebview = seam.ConnectWebviews.Create();

  Console.WriteLine(connectWebview.LoginSuccessful); // False

  // Use the returned Connect Webview URL to display
  // the Connect Webview authorization flow to your user.
  Console.WriteLine(connectWebview.Url);
  ```
</CodeGroup>

**Output:**

<CodeGroup>
  ```json JavaScript theme={null}
  false
  https://connect.getseam.com/connect_webviews/view?connect_webview_id=12345678-1234-1234-1234-123456789012&auth_token=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
  ```

  ```json cURL theme={null}
  Login Successful (false): false
  https://connect.getseam.com/connect_webviews/view?connect_webview_id=12345678-1234-1234-1234-123456789012&auth_token=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
  ```

  ```json Python theme={null}
  https://connect.getseam.com/connect_webviews/view?connect_webview_id=12345678-1234-1234-1234-123456789012&auth_token=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
  ```

  ```json Ruby theme={null}
  false
  https://connect.getseam.com/connect_webviews/view?connect_webview_id=12345678-1234-1234-1234-123456789012&auth_token=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
  ```

  ```json PHP theme={null}
  false
  https://connect.getseam.com/connect_webviews/view?connect_webview_id=12345678-1234-1234-1234-123456789012&auth_token=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
  ```

  ```json C# theme={null}
  False
  https://connect.getseam.com/connect_webviews/view?connect_webview_id=12345678-1234-1234-1234-123456789012&auth_token=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
  ```
</CodeGroup>

***

### Authorize Your Workspace

In a web browser, go to the URL that the Connect Webview object returned.

For application developers, you can redirect your user to this Connect Webview URL so that they can authorize your app to control their devices using Seam. We even provide a prebuilt [Connect Account Button](/ui-components/overview/react-components/connect-account-button) within our suite of [Seam Components](/ui-components/overview) that help you build your device management flow.

<Check>
  Because you're using a sandbox workspace, you can connect Seam's test
  Honeywell Resideo account. We provide [virtual
  devices](./sandbox-honeywell-thermostats) for each of the brands that we
  support. These sandbox devices and systems enable you to test your app with
  devices from multiple brands without the need to own all the corresponding
  physical devices.
</Check>

Complete the Connect Webview authorization flow by entering the following [Honeywell Resideo sandbox account](./sandbox-honeywell-thermostats) credentials:

* **Email:** [jane@example.com](mailto:jane@example.com)
* **Password:** 1234

Confirm that authorization through the Connect Webview was successful by querying its status.

**Code:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  const updatedConnectWebview = await seam.connectWebviews.get({
    connect_webview_id: connectWebview.connect_webview_id,
  })

  console.log(updatedConnectWebview.login_successful) // true
  ```

  ```bash cURL theme={null}
  curl -X 'GET' \
    'https://connect.getseam.com/connect_webviews/get' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d "{
    \"connect_webview_id\": \"${connect_webview_id}\"
  }" | jq -r '"Login Successful (true): " + (.connect_webview.login_successful | tostring)'
  ```

  ```python Python theme={null}
  updated_connect_webview = seam.connect_webviews.get(connect_webview.connect_webview_id)

  assert updated_connect_webview.login_successful is True # True
  ```

  ```ruby Ruby theme={null}
  updated_connect_webview = seam.connect_webviews.get(
    connect_webview_id: connect_webview.connect_webview_id
  )

  puts updated_connect_webview.login_successful # true
  ```

  ```php PHP theme={null}
  $updated_connect_webview = $seam->connect_webviews->get(
    connect_webview_id: $connect_webview->connect_webview_id
  );

  echo $updated_connect_webview->login_successful ? 'true' : 'false', "\n"; // true
  ```

  ```csharp C# theme={null}
  var updatedConnectWebview = seam.ConnectWebviews.Get(
    connectWebviewId: connectWebview.connectWebviewId
  );

  Console.WriteLine(updatedConnectWebview.LoginSuccessful); // True
  ```
</CodeGroup>

**Output:**

<CodeGroup>
  ```json JavaScript theme={null}
  true
  ```

  ```json cURL theme={null}
  Login Successful (true): true
  ```

  ```json Python theme={null}
  True
  ```

  ```json Ruby theme={null}
  true
  ```

  ```json PHP theme={null}
  true
  ```

  ```json C# theme={null}
  True
  ```
</CodeGroup>

***

## Step 3: Retrieve Honeywell Resideo thermostat devices

When you link a Honeywell Resideo account with Seam, we create a `device` object to represent each Honeywell Resideo thermostat in your account. You can then retrieve these Honeywell Resideo devices using the [List Devices](/api/devices/list) and [Get Device](/api/devices/get) endpoints.

The Seam API exposes each device's properties, such as the current temperature reading in Fahrenheit and Celsius, current HVAC and fan modes, available climate presets, thermostat-specific constraints, and much more.

**Code:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  // Retrieve all devices, filtered by manufacturer,
  // which is one of several filters that list() supports.
  const allHoneywellResideoThermostats = await seam.devices.list({
    manufacturer: 'honeywell_resideo',
  })

  // Select the first device as an example.
  const livingRoomThermostat = allHoneywellResideoThermostats[0]

  // Inspect specific properties.
  console.log(
    'Current temperature: ' +
      livingRoomThermostat.properties.temperature_fahrenheit,
  )
  console.log('Fan running: ' + livingRoomThermostat.properties.is_fan_running)

  // View the entire returned device object.
  console.log(livingRoomThermostat)
  ```

  ```bash cURL theme={null}
  # Retrieve all devices, filtered by manufacturer, which is
  # one of several filters that the list endpoint supports.
  all_honeywell_resideo_thermostats=$(
    # Use GET or POST.
    curl -X 'GET' \
      'https://connect.getseam.com/devices/list' \
      -H 'accept: application/json' \
      -H "Authorization: Bearer ${SEAM_API_KEY}" \
      -H 'Content-Type: application/json' \
      -d '{
      "manufacturer": "honeywell_resideo"
    }')

  # Select the first device as an example.
  living_room_thermostat=$(jq -r '.devices[0]' <<< ${all_honeywell_resideo_thermostats})

  # Inspect specific properties.
  echo $(jq -r '"Current temperature: " + (.properties.temperature_fahrenheit | tostring)' <<< ${living_room_thermostat})
  echo $(jq -r '"Fan running: " + (.properties.is_fan_running | tostring)' <<< ${living_room_thermostat})

  # View the entire returned device object.
  echo ${living_room_thermostat}
  ```

  ```python Python theme={null}
  # Retrieve all devices, filtered by manufacturer,
  # which is one of several filters that list() supports.
  all_honeywell_resideo_thermostats = seam.devices.list(manufacturer="honeywell_resideo")

  # Select the first device as an example.
  living_room_thermostat = all_honeywell_resideo_thermostats[0]

  # Inspect specific properties.
  pprint("Current temperature: " + str(living_room_thermostat.properties["temperature_fahrenheit"]))
  pprint("Fan running: " + str(living_room_thermostat.properties["is_fan_running"]))

  # View the entire returned device object.
  pprint(living_room_thermostat)
  ```

  ```ruby Ruby theme={null}
  # Retrieve all devices, filtered by manufacturer,
  # which is one of several filters that list() supports.
  all_honeywell_resideo_thermostats = seam.devices.list(manufacturer: "honeywell_resideo")

  # Select the first device as an example.
  living_room_thermostat = all_honeywell_resideo_thermostats[0]

  # Inspect specific properties.
  puts "Current temperature: " + living_room_thermostat.properties.temperature_fahrenheit.to_s
  puts "Fan running: " + living_room_thermostat.properties.is_fan_running.to_s

  # View the entire returned device object.
  puts living_room_thermostat.inspect
  ```

  ```php PHP theme={null}
  // Retrieve all devices, filtered by manufacturer,
  // which is one of several filters that list() supports.
  $all_honeywell_resideo_thermostats = $seam->devices->list(manufacturer: "honeywell_resideo");

  // Select the first device as an example.
  $living_room_thermostat = $all_honeywell_resideo_thermostats[0];

  // Inspect specific properties.
  echo "Current temperature: ", $living_room_thermostat->properties->temperature_fahrenheit, "\n";
  echo "Fan running: ", $living_room_thermostat->properties->is_fan_running ? 'true' : 'false', "\n";

  // View the entire returned device object.
  echo json_encode($living_room_thermostat, JSON_PRETTY_PRINT);
  ```

  ```csharp C# theme={null}
  // Coming soon!
  ```
</CodeGroup>

**Output:**

<CodeGroup>
  ```json JavaScript theme={null}
  Current temperature: 70
  Fan running: false
  {
    device_id: '11111111-1111-1111-2222-444444444444',
    workspace_id: '00000000-0000-0000-0000-000000000000',
    connected_account_id: '11111111-1111-1111-1111-222222222222',
    created_at: '2024-10-03T22:12:15.666Z',
    properties: {
      manufacturer: 'honeywell_resideo',
      online: true,
      temperature_celsius: 21.11111111111111,
      temperature_fahrenheit: 70,
      relative_humidity: 0.36,
      is_cooling: false,
      is_heating: false,
      is_fan_running: false,
      current_climate_setting: {
        display_name: 'Manual Setting',
        fan_mode_setting: 'auto',
        hvac_mode_setting: 'heat',
        manual_override_allowed: true,
        heating_set_point_celsius: 21.11111111111111,
        heating_set_point_fahrenheit: 70
      },
      ...
    },
    can_hvac_cool: true,
    can_hvac_heat: true,
    can_hvac_heat_cool: true,
    can_turn_off_hvac: true,
    ...
  }
  ```

  ```json cURL theme={null}
  Current temperature: 70
  Fan running: false
  {
    "device_id": "11111111-1111-1111-2222-444444444444",
    "workspace_id": "00000000-0000-0000-0000-000000000000",
    "connected_account_id": "11111111-1111-1111-1111-222222222222",
    "created_at": "2024-10-03T22:12:15.666Z",
    "properties": {
      "manufacturer": "honeywell_resideo",
      "online": true,
      "temperature_celsius": 21.11111111111111,
      "temperature_fahrenheit": 70,
      "relative_humidity": 0.36,
      "is_cooling": false,
      "is_heating": false,
      "is_fan_running": false,
      "current_climate_setting": {
        "display_name": "Manual Setting",
        "fan_mode_setting": "auto",
        "hvac_mode_setting": "heat",
        "manual_override_allowed": true,
        "heating_set_point_celsius": 21.11111111111111,
        "heating_set_point_fahrenheit": 70
      },
      ...
    },
    "can_hvac_cool": true,
    "can_hvac_heat": true,
    "can_hvac_heat_cool": true,
    "can_turn_off_hvac": true,
    ...
  }
  ```

  ```json Python theme={null}
  'Current temperature: 70'
  'Fan running: False'
  Device(
    device_id='11111111-1111-1111-2222-444444444444',
    workspace_id='00000000-0000-0000-0000-000000000000',
    connected_account_id='11111111-1111-1111-1111-222222222222',
    created_at='2024-10-03T22:12:15.666Z',
    properties={
      'manufacturer': 'honeywell_resideo',
      'online': True,
      'temperature_celsius': 21.11111111111111,
      'temperature_fahrenheit': 70,
      'relative_humidity': 0.36,
      'is_cooling': False,
      'is_heating': False,
      'is_fan_running': False,
      'current_climate_setting': {
        'display_name': 'Manual Setting',
        'fan_mode_setting': 'auto',
        'heating_set_point_celsius': 21.11111111111111,
        'heating_set_point_fahrenheit': 70,
        'hvac_mode_setting': 'heat',
        'manual_override_allowed': True
      },
      ...
    },
    can_hvac_cool=True,
    can_hvac_heat=True,
    can_hvac_heat_cool=True,
    can_turn_off_hvac=True,
    ...
  )
  ```

  ```json Ruby theme={null}
  Current temperature: 70
  Fan running: false
  <Seam::Resources::Device:0x005f0
    device_id="11111111-1111-1111-2222-444444444444"
    workspace_id="00000000-0000-0000-0000-000000000000"
    connected_account_id="11111111-1111-1111-1111-222222222222"
    created_at=2024-10-03 22:12:15.666 UTC
    properties=#<Seam::DeepHashAccessor:0x0000016b1791f068 @data={
      "manufacturer"=>"honeywell_resideo",
      "online"=>true,
      "temperature_celsius"=>21.11111111111111,
      "temperature_fahrenheit"=>70,
      "relative_humidity"=>0.36,
      "is_cooling"=>false,
      "is_heating"=>false,
      "is_fan_running"=>false,
      "current_climate_setting"=>{
        "display_name"=>"Manual Setting",
        "fan_mode_setting"=>"auto",
        "hvac_mode_setting"=>"heat",
        "manual_override_allowed"=>true,
        "heating_set_point_celsius"=>21.11111111111111,
        "heating_set_point_fahrenheit"=>70
      },
      ...
    }>
    can_hvac_cool=true
    can_hvac_heat=true
    can_hvac_heat_cool=true
    can_turn_off_hvac=true
    ...
  >
  ```

  ```json PHP theme={null}
  Current temperature: 70
  Fan running: false
  {
    "device_id": "11111111-1111-1111-2222-444444444444",
    "workspace_id": "00000000-0000-0000-0000-000000000000",
    "connected_account_id": "11111111-1111-1111-1111-222222222222",
    "created_at": "2024-10-03T22:12:15.666Z",
    "properties": {
      "manufacturer": "honeywell_resideo",
      "online": true,
      "temperature_celsius": 21.11111111111111,
      "temperature_fahrenheit": 70,
      "relative_humidity": 0.36,
      "is_cooling": false,
      "is_heating": false,
      "is_fan_running": false,
      "current_climate_setting": {
        "display_name": "Manual Setting",
        "fan_mode_setting": "auto",
        "heating_set_point_celsius": 21.11111111111111,
        "heating_set_point_fahrenheit": 70,
        "hvac_mode_setting": "heat",
        "manual_override_allowed": true,
        ...
      },
      ...
    },
    "can_hvac_cool": true,
    "can_hvac_heat": true,
    "can_hvac_heat_cool": true,
    "can_turn_off_hvac": true,
    ...
  }
  ```

  ```json C# theme={null}
  // Coming soon!
  ```
</CodeGroup>

***

## Step 4: Control your Honeywell Resideo thermostat

Next, you can use the Seam API to control your Honeywell Resideo thermostat.

Each device that you connect to Seam has a specific set of capabilities. These capabilities define the Seam API actions that you can use. For thermostats, device-specific capabilities include whether you can [set the HVAC mode](/capability-guides/thermostats/configure-current-climate-settings) to `heat`, `cool`, or `heat_cool`. Seam's intuitive and granular [capability flags](/capability-guides/device-and-system-capabilities#capability-flags) inform your application about what features and behaviors each device supports. Notice the capability flags within the code samples in this guide.

Seam provides additional actions for thermostats, such as setting the fan mode, creating and scheduling climate presets, setting temperature thresholds, and configuring weekly thermostat programs. You can also monitor for Seam thermostat-related events, such as reported temperatures outside your set thresholds.

Try out the following actions on your Honeywell Resideo thermostat:

* [ ] [Set the HVAC mode](#set-the-hvac-mode)
* [ ] [Create and schedule climate presets](#create-and-schedule-climate-presets)
* [ ] [Configure a weekly thermostat program](#configure-a-weekly-thermostat-program)

### Set the HVAC mode

To set the HVAC mode, use any of the following endpoints or their equivalents in the Seam SDKs:

* `/thermostats/heat`
* `/thermostats/cool`
* `/thermostats/heat_cool`
* `/thermostats/off`
* `/thermostats/set_hvac_mode`

  This endpoint is a consolidated version of the other four endpoints.

Specify the thermostat that you want to control by including the `device_id` in the request body. Also, include the desired temperature [set point](/capability-guides/thermostats/understanding-thermostat-concepts/set-points).

In this example, set the HVAC mode to `heat` and the desired heating set point to 68 °F.

Each of these HVAC mode endpoints returns an [action attempt](/core-concepts/action-attempts) to track the progress of the operation.

**Code:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  // Confirm that the device supports heat mode.
  // You're using a capability flag here!
  if (livingRoomThermostat.can_hvac_heat) {
    // Set the HVAC mode
    // and return an action attempt.
    const actionAttempt = await seam.thermostats.heat({
      device_id: livingRoomThermostat.device_id,
      heating_set_point_fahrenheit: 68,
    })
  }
  ```

  ```bash cURL theme={null}
  # Confirm that the device supports heat mode.
  # You're using a capability flag here!
  if  $(jq -r '.can_hvac_heat' <<< ${living_room_thermostat}); then \
    # Set the HVAC mode
    # and return an action attempt.
    curl -X 'POST' \
      'https://connect.getseam.com/thermostats/heat' \
      -H 'accept: application/json' \
      -H "Authorization: Bearer ${SEAM_API_KEY}" \
      -H 'Content-Type: application/json' \
      -d "{
        \"device_id\": \"$(jq -r '.device_id' <<< ${living_room_thermostat})\",
        \"heating_set_point_fahrenheit\": 68
    }";
  fi
  ```

  ```python Python theme={null}
  # Confirm that the device supports heat mode.
  # You're using a capability flag here!
  if living_room_thermostat.can_hvac_heat:
    # Set the HVAC mode
    # and return an action attempt.
    action_attempt = seam.thermostats.heat(
      device_id = living_room_thermostat.device_id,
      heating_set_point_fahrenheit = 68
    )
  ```

  ```ruby Ruby theme={null}
  # Confirm that the device supports heat mode.
  # You're using a capability flag here!
  if (living_room_thermostat.can_hvac_heat)
    # Set the HVAC mode
    # and return an action attempt.
    action_attempt = seam.thermostats.heat(
      device_id: living_room_thermostat.device_id,
      heating_set_point_fahrenheit: 68
    )
  end
  ```

  ```php PHP theme={null}
  // Confirm that the device supports heat mode.
  // You're using a capability flag here!
  if ($living_room_thermostat->can_hvac_heat) {
    // Set the HVAC mode
    // and return an action attempt.
    $action_attempt = $seam->thermostats->heat(
      device_id: $living_room_thermostat->device_id,
      heating_set_point_fahrenheit: 68
    );
  }
  ```

  ```csharp C# theme={null}
  // Coming soon!
  ```
</CodeGroup>

**Output:**

<CodeGroup>
  ```json JavaScript theme={null}
  {
    "actionAttempt": {
      "status": "success",
      "action_attempt_id": "11111111-2222-3333-4444-555555555555",
      "action_type": "SET_HVAC_MODE",
      "result": {},
      "error": null
    }
  }
  ```

  ```json cURL theme={null}
  {
    "action_attempt": {
      "status": "pending",
      "action_type": "SET_HVAC_MODE",
      "action_attempt_id": "11111111-2222-3333-4444-555555555555",
      "result": null,
      "error": null
    },
    "ok": true
  }
  ```

  ```json Python theme={null}
  ActionAttempt(
    action_attempt_id='11111111-2222-3333-4444-555555555555',
    action_type='SET_HVAC_MODE',
    status='success',
    result={},
    error=None
  )
  ```

  ```json Ruby theme={null}
  <Seam::Resources::ActionAttempt:0x005f0
    status="success"
    action_type="SET_HVAC_MODE"
    action_attempt_id="11111111-2222-3333-4444-555555555555"
    result={}
    error=nil>
  ```

  ```json PHP theme={null}
  {
    "action_attempt_id": "11111111-2222-3333-4444-555555555555",
    "action_type": "SET_HVAC_MODE",
    "error": null,
    "result": {},
    "status": "success"
  }
  ```

  ```json C# theme={null}
  // Coming soon!
  ```
</CodeGroup>

You can track the status of the operation to confirm that the device was set to heat mode successfully. Query `properties.current_climate_setting.hvac_mode_setting` for the device, [retrieve the action attempt](/api/action_attempts/get) by ID, or look for a [`thermostat.manually_adjusted` event](/api/thermostats/events#thermostat-manually_adjusted). Further, if you wanted to find out whether the HVAC system was currently heating, you could inspect `properties.is_heating` for the device.

To query `properties.current_climate_setting.hvac_mode_setting` for the device:

**Code:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  // Get the device by ID.
  const updatedLivingRoomThermostat = await seam.devices.get({
    device_id: livingRoomThermostat.device_id,
  })

  // Inspect properties.current_climate_setting.hvac_mode_setting
  // to confirm that setting the HVAC mode to heat was successful.
  console.log(
    updatedLivingRoomThermostat.properties.current_climate_setting
      .hvac_mode_setting,
  )
  ```

  ```bash cURL theme={null}
  # Get the device by ID.
  updated_living_room_thermostat=$(
    # Use GET or POST.
    curl -X 'GET' \
      'https://connect.getseam.com/devices/get' \
      -H 'accept: application/json' \
      -H "Authorization: Bearer ${SEAM_API_KEY}" \
      -H 'Content-Type: application/json' \
      -d "{
        \"device_id\": \"$(jq -r '.device_id' <<< ${living_room_thermostat})\"
    }")

  # Inspect properties.current_climate_setting.hvac_mode_setting
  # to confirm that setting the HVAC mode to heat was successful.
  echo $(jq -r '(.device.properties.current_climate_setting.hvac_mode_setting)' <<< ${updated_living_room_thermostat})
  ```

  ```python Python theme={null}
  # Get the device by ID.
  updated_living_room_thermostat = seam.devices.get(
    device_id = living_room_thermostat.device_id
  )

  # Inspect properties.current_climate_setting.hvac_mode_setting
  # to confirm that setting the HVAC mode to heat was successful.
  pprint(
    updated_living_room_thermostat.
    properties["current_climate_setting"]["hvac_mode_setting"]
  )
  ```

  ```ruby Ruby theme={null}
  # Get the device by ID.
  updated_living_room_thermostat = seam.devices.get(
    device_id: living_room_thermostat.device_id
  )

  # Inspect properties.current_climate_setting.hvac_mode_setting
  # to confirm that setting the HVAC mode to heat was successful.
  puts updated_living_room_thermostat.
    properties.current_climate_setting.hvac_mode_setting
  ```

  ```php PHP theme={null}
  // Get the device by ID.
  $updated_living_room_thermostat = $seam->devices->get(
    device_id: $living_room_thermostat->device_id
  );

  // Inspect properties.current_climate_setting.hvac_mode_setting
  // to confirm that setting the HVAC mode to heat was successful.
  echo $updated_living_room_thermostat->properties->
    current_climate_setting->hvac_mode_setting;
  ```

  ```csharp C# theme={null}
  // Coming soon!
  ```
</CodeGroup>

**Output:**

<CodeGroup>
  ```json JavaScript theme={null}
  heat
  ```

  ```json cURL theme={null}
  heat
  ```

  ```json Python theme={null}
  'heat'
  ```

  ```json Ruby theme={null}
  heat
  ```

  ```json PHP theme={null}
  heat
  ```

  ```json C# theme={null}
  // Coming soon!
  ```
</CodeGroup>

***

### Create and schedule climate presets

You can use the Seam API to create climate presets for Honeywell Resideo thermostats. Each climate preset is a saved group of settings, such as HVAC mode, fan mode, and temperature set points. Climate presets make it quick and easy to apply consistent climate settings for different scenarios. For example, you could create two climate presets: a comfort preset for when a vacation rental is occupied and an eco preset for when the vacation rental is empty.

You can schedule climate presets to start and stop whenever you'd like. You can even set a fallback climate preset, such as eco.

In this example, create comfort and eco climate presets, set eco as the fallback, and schedule the comfort climate preset to coincide with two vacation rental reservations.

**Code:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  // Confirm that the thermostat supports heat_cool mode
  // so that the climate presets can use this mode.
  if (updatedLivingRoomThermostat.can_hvac_heat_cool) {
    // Create the climate presets.
    await seam.thermostats.createClimatePreset({
      device_id: updatedLivingRoomThermostat.device_id,
      climate_preset_key: 'comfort',
      name: 'Comfort',
      fan_mode_setting: 'auto',
      hvac_mode_setting: 'heat_cool',
      cooling_set_point_celsius: 25,
      heating_set_point_celsius: 20,
    })

    await seam.thermostats.createClimatePreset({
      device_id: updatedLivingRoomThermostat.device_id,
      climate_preset_key: 'eco',
      name: 'Eco',
      fan_mode_setting: 'auto',
      hvac_mode_setting: 'heat_cool',
      cooling_set_point_celsius: 30,
      heating_set_point_celsius: 15,
    })

    // Then, set eco as the fallback climate setting.
    await seam.thermostats.setFallbackClimatePreset({
      device_id: updatedLivingRoomThermostat.device_id,
      climate_preset_key: 'eco',
    })

    // Now, schedule the comfort preset to coincide with two reservations.
    await seam.thermostats.schedules.create({
      device_id: updatedLivingRoomThermostat.device_id,
      name: "Jim's stay",
      climate_preset_key: 'comfort',
      starts_at: '2025-03-10T15:00:00Z',
      ends_at: '2025-03-15T12:00:00Z',
      is_override_allowed: true,
      max_override_period_minutes: 90,
    })

    await seam.thermostats.schedules.create({
      device_id: updatedLivingRoomThermostat.device_id,
      name: "Jane's stay",
      climate_preset_key: 'comfort',
      starts_at: '2025-03-17T15:00:00Z',
      ends_at: '2025-03-20T12:00:00Z',
      is_override_allowed: true,
      max_override_period_minutes: 90,
    })
  }
  ```

  ```bash cURL theme={null}
  # Confirm that the thermostat supports heat_cool mode
  # so that the climate presets can use this mode.
  if  $(jq -r '.device.can_hvac_heat_cool' <<< ${updated_living_room_thermostat}); then \
    # Create the climate presets.
    curl -X 'POST' \
      'https://connect.getseam.com/thermostats/create_climate_preset' \
      -H 'accept: application/json' \
      -H "Authorization: Bearer ${SEAM_API_KEY}" \
      -H 'Content-Type: application/json' \
      -d "{
        \"device_id\": \"$(jq -r '.device.device_id' <<< ${updated_living_room_thermostat})\",
        \"climate_preset_key\": \"comfort\",
        \"name\": \"Comfort\",
        \"fan_mode_setting\": \"auto\",
        \"hvac_mode_setting\": \"heat_cool\",
        \"cooling_set_point_celsius\": 25,
        \"heating_set_point_celsius\": 20
    }";

    curl -X 'POST' \
      'https://connect.getseam.com/thermostats/create_climate_preset' \
      -H 'accept: application/json' \
      -H "Authorization: Bearer ${SEAM_API_KEY}" \
      -H 'Content-Type: application/json' \
      -d "{
        \"device_id\": \"$(jq -r '.device.device_id' <<< ${updated_living_room_thermostat})\",
        \"climate_preset_key\": \"eco\",
        \"name\": \"Eco\",
        \"fan_mode_setting\": \"auto\",
        \"hvac_mode_setting\": \"heat_cool\",
        \"cooling_set_point_celsius\": 30,
        \"heating_set_point_celsius\": 15
    }";

    # Then, set eco as the fallback climate setting.
    curl -X 'POST' \
      'https://connect.getseam.com/thermostats/set_fallback_climate_preset' \
      -H 'accept: application/json' \
      -H "Authorization: Bearer ${SEAM_API_KEY}" \
      -H 'Content-Type: application/json' \
      -d "{
        \"device_id\": \"$(jq -r '.device.device_id' <<< ${updated_living_room_thermostat})\",
        \"climate_preset_key\": \"eco\"
    }";

    # Now, schedule the comfort preset to coincide with two reservations.
    curl -X 'POST' \
    'https://connect.getseam.com/thermostats/schedules/create' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d "{
      \"device_id\": \"$(jq -r '.device.device_id' <<< ${updated_living_room_thermostat})\",
      \"name\":  \"Jim's stay\",
      \"climate_preset_key\": \"comfort\",
      \"starts_at\": \"2025-03-10T15:00:00Z\",
      \"ends_at\": \"2025-03-15T12:00:00Z\",
      \"is_override_allowed\": true,
      \"max_override_period_minutes\": 90
    }";

    curl -X 'POST' \
    'https://connect.getseam.com/thermostats/schedules/create' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d "{
      \"device_id\": \"$(jq -r '.device.device_id' <<< ${updated_living_room_thermostat})\",
      \"name\":  \"Jane's stay\",
      \"climate_preset_key\": \"comfort\",
      \"starts_at\": \"2025-03-17T15:00:00Z\",
      \"ends_at\": \"2025-03-20T12:00:00Z\",
      \"is_override_allowed\": true,
      \"max_override_period_minutes\": 90
    }";
  fi
  ```

  ```python Python theme={null}
  # Confirm that the thermostat supports heat_cool mode
  # so that the climate presets can use this mode.
  if updated_living_room_thermostat.can_hvac_heat_cool:
    # Create the climate presets.
    seam.thermostats.create_climate_preset(
      device_id = updated_living_room_thermostat.device_id,
      climate_preset_key = "comfort",
      name = "Comfort",
      fan_mode_setting = "auto",
      hvac_mode_setting = "heat_cool",
      cooling_set_point_celsius = 25,
      heating_set_point_celsius = 20
    )

    seam.thermostats.create_climate_preset(
      device_id: updated_living_room_thermostat.device_id,
      climate_preset_key = "eco",
      name = "Eco",
      fan_mode_setting = "auto",
      hvac_mode_setting = "heat_cool",
      cooling_set_point_celsius = 30,
      heating_set_point_celsius = 15
    )

    # Then, set eco as the fallback climate setting.
    seam.thermostats.set_fallback_climate_preset(
      device_id = updated_living_room_thermostat.device_id,
      climate_preset_key = "eco"
    )

    # Now, schedule the comfort preset to coincide with two reservations.
    seam.thermostats.schedules.create(
      device_id = updated_living_room_thermostat.device_id,
      name = "Jim's stay",
      climate_preset_key = "comfort",
      starts_at = "2025-03-10T15:00:00Z",
      ends_at = "2025-03-15T12:00:00Z",
      is_override_allowed = True,
      max_override_period_minutes = 90
    )

    seam.thermostats.schedules.create(
      device_id = updated_living_room_thermostat.device_id,
      name = "Jane's stay",
      climate_preset_key = "comfort",
      starts_at = "2025-03-17T15:00:00Z",
      ends_at = "2025-03-20T12:00:00Z",
      is_override_allowed = True,
      max_override_period_minutes = 90
    )
  ```

  ```ruby Ruby theme={null}
  # Confirm that the thermostat supports heat_cool mode
  # so that the climate presets can use this mode.
  if (updated_living_room_thermostat.can_hvac_heat_cool)
    # Create the climate presets.
    seam.thermostats.create_climate_preset(
      device_id: updated_living_room_thermostat.device_id,
      climate_preset_key: "comfort",
      name: "Comfort",
      fan_mode_setting: "auto",
      hvac_mode_setting: "heat_cool",
      cooling_set_point_celsius: 25,
      heating_set_point_celsius: 20
    )

    seam.thermostats.create_climate_preset(
      device_id: updated_living_room_thermostat.device_id,
      climate_preset_key: "eco",
      name: "Eco",
      fan_mode_setting: "auto",
      hvac_mode_setting: "heat_cool",
      cooling_set_point_celsius: 30,
      heating_set_point_celsius: 15
    )

    # Then, set eco as the fallback climate setting.
    seam.thermostats.set_fallback_climate_preset(
      device_id: updated_living_room_thermostat.device_id,
      climate_preset_key: "eco"
    )

    # Now, schedule the comfort preset to coincide with two reservations.
    seam.thermostats.schedules.create(
      device_id: updated_living_room_thermostat.device_id,
      name: "Jim's stay",
      climate_preset_key: "comfort",
      starts_at: "2025-03-10T15:00:00Z",
      ends_at: "2025-03-15T12:00:00Z",
      is_override_allowed: true,
      max_override_period_minutes: 90
    )

    await seam.thermostats.schedules.create(
      device_id: updated_living_room_thermostat.device_id,
      name: "Jane's stay",
      climate_preset_key: "comfort",
      starts_at: "2025-03-17T15:00:00Z",
      ends_at: "2025-03-20T12:00:00Z",
      is_override_allowed: true,
      max_override_period_minutes: 90
    )
  end
  ```

  ```php PHP theme={null}
  // Confirm that the thermostat supports heat_cool mode
  // so that the climate presets can use this mode.
  if ($updated_living_room_thermostat->can_hvac_heat_cool) {
    // Create the climate presets.
    $seam->thermostats->create_climate_preset(
      device_id: $updated_living_room_thermostat->device_id,
      climate_preset_key: "comfort",
      name: "Comfort",
      fan_mode_setting: "auto",
      hvac_mode_setting: "heat_cool",
      cooling_set_point_celsius: 25,
      heating_set_point_celsius: 20
    );

    $seam->thermostats->create_climate_preset(
      device_id: $updated_living_room_thermostat->device_id,
      climate_preset_key: "eco",
      name: "Eco",
      fan_mode_setting: "auto",
      hvac_mode_setting: "heat_cool",
      cooling_set_point_celsius: 30,
      heating_set_point_celsius: 15
    );

    // Then, set eco as the fallback climate setting.
    $seam->thermostats->set_fallback_climate_preset(
      device_id: $updated_living_room_thermostat->device_id,
      climate_preset_key: "eco"
    );

    // Now, schedule the comfort preset to coincide with two reservations.
    $seam->thermostats->schedules->create(
      device_id: $updated_living_room_thermostat->device_id,
      name: "Jim's stay",
      climate_preset_key: "comfort",
      starts_at: "2025-03-10T15:00:00Z",
      ends_at: "2025-03-15T12:00:00Z",
      is_override_allowed: true,
      max_override_period_minutes: 90
    );

    $seam->thermostats->schedules->create(
      device_id: updated_living_room_thermostat.device_id,
      name: "Jane's stay",
      climate_preset_key: "comfort",
      starts_at: "2025-03-17T15:00:00Z",
      ends_at: "2025-03-20T12:00:00Z",
      is_override_allowed: true,
      max_override_period_minutes: 90
    );
  }
  ```

  ```csharp C# theme={null}
  // Coming soon!
  ```
</CodeGroup>

**Output:**

<CodeGroup>
  ```json JavaScript theme={null}
  {
    thermostat_schedule_id: '88888888-1111-1111-1111-111111111111',
    name: "Jim's stay",
    device_id: '11111111-1111-1111-2222-444444444444',
    climate_preset_key: 'comfort',
    starts_at: '2025-03-10T15:00:00.000Z',
    ends_at: '2025-03-15T12:00:00.000Z',
    is_override_allowed: true,
    max_override_period_minutes: 90,
    ...
  }
  {
    thermostat_schedule_id: '88888888-1111-1111-1111-222222222222',
    name: "Jane's stay",
    device_id: '11111111-1111-1111-2222-444444444444',
    climate_preset_key: 'comfort',
    starts_at: '2025-03-17T15:00:00.000Z',
    ends_at: '2025-03-20T12:00:00.000Z',
    is_override_allowed: true,
    max_override_period_minutes: 90,
    ...
  }
  ```

  ```json cURL theme={null}
  {
    "thermostat_schedule":{
      "thermostat_schedule_id":"88888888-1111-1111-1111-111111111111",
      "name":"Jim's stay",
      "device_id":"11111111-1111-1111-2222-444444444444",
      "climate_preset_key":"comfort",
      "starts_at":"2025-03-10T15:00:00.000Z",
      "ends_at":"2025-03-15T12:00:00.000Z",
      "is_override_allowed":true,
      "max_override_period_minutes":90,
      ...
    },
    "ok":true
  }
  {
    "thermostat_schedule":{
      "thermostat_schedule_id":"88888888-1111-1111-1111-222222222222",
      "name":"Jane's stay",
      "device_id":"11111111-1111-1111-2222-444444444444",
      "climate_preset_key":"comfort",
      "starts_at":"2025-03-17T15:00:00.000Z",
      "ends_at":"2025-03-20T12:00:00.000Z",
      "is_override_allowed":true,
      "max_override_period_minutes":90,
      ...
    },
    "ok":true
  }
  ```

  ```json Python theme={null}
  ThermostatSchedule(
    thermostat_schedule_id='88888888-1111-1111-1111-111111111111',
    name="Jim's stay",
    device_id='11111111-1111-1111-2222-444444444444',
    climate_preset_key='comfort',
    starts_at='2025-03-10T15:00:00.000Z',
    ends_at='2025-03-15T12:00:00.000Z',
    is_override_allowed=True,
    max_override_period_minutes=90,
    ...
  )
  ThermostatSchedule(
    thermostat_schedule_id='88888888-1111-1111-1111-222222222222',
    name="Jane's stay",
    device_id='11111111-1111-1111-2222-444444444444',
    climate_preset_key='comfort',
    starts_at='2025-03-17T15:00:00.000Z',
    ends_at='2025-03-20T12:00:00.000Z',
    is_override_allowed=True,
    max_override_period_minutes=90,
    ...
  )
  ```

  ```json Ruby theme={null}
  <Seam::Resources::ThermostatSchedule:0x005f0
    thermostat_schedule_id="88888888-1111-1111-1111-111111111111"
    name="Jim's stay"
    device_id="11111111-1111-1111-2222-444444444444"
    climate_preset_key="comfort"
    starts_at=2025-03-10 15:00:00 UTC
    ends_at=2025-03-15 12:00:00 UTC
    is_override_allowed=true
    max_override_period_minutes=90
    ...
  >
  <Seam::Resources::ThermostatSchedule:0x005f0
    thermostat_schedule_id="88888888-1111-1111-1111-222222222222"
    name="Jane's stay"
    device_id="11111111-1111-1111-2222-444444444444"
    climate_preset_key="comfort"
    starts_at=2025-03-17 15:00:00 UTC
    ends_at=2025-03-20 12:00:00 UTC
    is_override_allowed=true
    max_override_period_minutes=90
    ...
  >
  ```

  ```json PHP theme={null}
  {
    "thermostat_schedule_id":"88888888-1111-1111-1111-111111111111",
    "name":"Jim's stay",
    "device_id":"11111111-1111-1111-2222-444444444444",
    "climate_preset_key":"comfort",
    "starts_at":"2025-03-10T15:00:00.000Z",
    "ends_at":"2025-03-15T12:00:00.000Z",
    "is_override_allowed":true,
    "max_override_period_minutes":90,
    ...
  }
  {
    "thermostat_schedule_id":"88888888-1111-1111-1111-222222222222",
    "name":"Jane's stay",
    "device_id":"11111111-1111-1111-2222-444444444444",
    "climate_preset_key":"comfort",
    "starts_at":"2025-03-17T15:00:00.000Z",
    "ends_at":"2025-03-20T12:00:00.000Z",
    "is_override_allowed":true,
    "max_override_period_minutes":90,
    ...
  }
  ```

  ```json C# theme={null}
  // Coming soon!
  ```
</CodeGroup>

***

### Configure a weekly thermostat program

You can use the Seam API to create a thermostat weekly program for your Honeywell Resideo thermostat. This standard feature of smart thermostats enables you to define full-week programs that are made up of reusable daily programs. Each daily program consists of a set of thermostat daily program periods, that is, time blocks with associated climate presets.

In this example, create a weekday daily program and a weekend daily program. Then, combine these daily programs into a weekly program by assigning a daily program to each day of the week.

**Code:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  // Create the daily programs.
  const weekdayProgram = await seam.thermostats.dailyPrograms.create({
    device_id: updatedLivingRoomThermostat.device_id,
    name: 'Weekday Program',
    periods: [
      { starts_at_time: '07:00:00', climate_preset_key: 'Home' },
      { starts_at_time: '09:00:00', climate_preset_key: 'Away' },
      { starts_at_time: '18:00:00', climate_preset_key: 'Home' },
      { starts_at_time: '22:00:00', climate_preset_key: 'Sleep' },
    ],
  })

  const weekendProgram = await seam.thermostats.dailyPrograms.create({
    device_id: updatedLivingRoomThermostat.device_id,
    name: 'Weekend Program',
    periods: [
      { starts_at_time: '08:00:00', climate_preset_key: 'Home' },
      { starts_at_time: '23:00:00', climate_preset_key: 'Sleep' },
    ],
  })

  // Use the daily programs to set the weekly program.
  await seam.thermostats.updateWeeklyProgram({
    device_id: updatedLivingRoomThermostat.device_id,
    monday_program_id: weekdayProgram.thermostat_daily_program_id,
    tuesday_program_id: weekdayProgram.thermostat_daily_program_id,
    wednesday_program_id: weekdayProgram.thermostat_daily_program_id,
    thursday_program_id: weekdayProgram.thermostat_daily_program_id,
    friday_program_id: weekdayProgram.thermostat_daily_program_id,
    saturday_program_id: weekendProgram.thermostat_daily_program_id,
    sunday_program_id: weekendProgram.thermostat_daily_program_id,
  })
  ```

  ```bash cURL theme={null}
  # Create the daily programs.
  weekday_program=$(curl -X 'POST' \
    'https://connect.getseam.com/thermostats/daily_programs/create' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d "{
      \"device_id\": \"$(jq -r '.device.device_id' <<< ${updated_living_room_thermostat})\",
      \"name\":  \"Weekday Program\",
      \"periods\": [
      { \"starts_at_time\": \"07:00:00\", \"climate_preset_key\": \"Home\" },
      { \"starts_at_time\": \"09:00:00\", \"climate_preset_key\": \"Away\" },
      { \"starts_at_time\": \"18:00:00\", \"climate_preset_key\": \"Home\" },
      { \"starts_at_time\": \"22:00:00\", \"climate_preset_key\": \"Sleep\" }
    ]
  }")
  weekday_program_id=$(jq -r '.thermostat_daily_program_id' <<< ${weekday_program})

  weekend_program=$(curl -X 'POST' \
    'https://connect.getseam.com/thermostats/daily_programs/create' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d "{
      \"device_id\": \"$(jq -r '.device.device_id' <<< ${updated_living_room_thermostat})\",
      \"name\":  \"Weekend Program\",
      \"periods\": [
      { \"starts_at_time\": \"08:00:00\", \"climate_preset_key\": \"Home\" },
      { \"starts_at_time\": \"23:00:00\", \"climate_preset_key\": \"Sleep\" }
    ]
  }")
  weekend_program_id=$(jq -r '.thermostat_daily_program_id' <<< ${weekend_program})

  # Use the daily programs to set the weekly program.
  curl -X 'POST' \
    'https://connect.getseam.com/thermostats/update_weekly_program' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d "{
      \"device_id\": \"$(jq -r '.device.device_id' <<< ${updated_living_room_thermostat})\",
      \"monday_program_id\": \"${weekday_program_id}\",
      \"tuesday_program_id\": \"${weekday_program_id}\",
      \"wednesday_program_id\": \"${weekday_program_id}\",
      \"thursday_program_id\": \"${weekday_program_id}\",
      \"friday_program_id\": \"${weekday_program_id}\",
      \"saturday_program_id\": \"${weekend_program_id}\",
      \"sunday_program_id\": \"${weekend_program_id}\"
  }"
  ```

  ```python Python theme={null}
  # Create the daily programs.
  weekday_program = seam.thermostats.daily_programs.create(
    device_id = updated_living_room_thermostat.device_id,
    name = "Weekday Program",
    periods = [
      { "starts_at_time": "07:00:00", "climate_preset_key": "Home" },
      { "starts_at_time": "09:00:00", "climate_preset_key": "Away" },
      { "starts_at_time": "18:00:00", "climate_preset_key": "Home" },
      { "starts_at_time": "22:00:00", "climate_preset_key": "Sleep" }
    ]
  )

  weekend_program = seam.thermostats.daily_programs.create(
    device_id = updated_living_room_thermostat.device_id,
    name = "Weekend Program",
    periods = [
      { "starts_at_time": "08:00:00", "climate_preset_key": "Home" },
      { "starts_at_time": "23:00:00", "climate_preset_key": "Sleep" }
    ]
  )

  # Use the daily programs to set the weekly program.
  seam.thermostats.update_weekly_program(
    device_id = updated_living_room_thermostat.device_id,
    monday_program_id = weekday_program.thermostat_daily_program_id,
    tuesday_program_id = weekday_program.thermostat_daily_program_id,
    wednesday_program_id = weekday_program.thermostat_daily_program_id,
    thursday_program_id = weekday_program.thermostat_daily_program_id,
    friday_program_id = weekday_program.thermostat_daily_program_id,
    saturday_program_id = weekend_program.thermostat_daily_program_id,
    sunday_program_id = weekend_program.thermostat_daily_program_id
  )
  ```

  ```ruby Ruby theme={null}
  # Create the daily programs.
  weekday_program = seam.thermostats.daily_programs.create(
    device_id: updated_living_room_thermostat.device_id,
    name: "Weekday Program",
    periods: [
      { "starts_at_time": "07:00:00", "climate_preset_key": "Home" },
      { "starts_at_time": "09:00:00", "climate_preset_key": "Away" },
      { "starts_at_time": "18:00:00", "climate_preset_key": "Home" },
      { "starts_at_time": "22:00:00", "climate_preset_key": "Sleep" }
    ]
  )

  weekend_program = seam.thermostats.daily_programs.create(
    device_id: updated_living_room_thermostat.device_id,
    name: "Weekend Program",
    periods: [
      { "starts_at_time": "08:00:00", "climate_preset_key": "Home" },
      { "starts_at_time": "23:00:00", "climate_preset_key": "Sleep" }
    ]
  )

  # Use the daily programs to set the weekly program.
  seam.thermostats.update_weekly_program(
    device_id: updated_living_room_thermostat.device_id,
    monday_program_id: weekday_program.thermostat_daily_program_id,
    tuesday_program_id: weekday_program.thermostat_daily_program_id,
    wednesday_program_id: weekday_program.thermostat_daily_program_id,
    thursday_program_id: weekday_program.thermostat_daily_program_id,
    friday_program_id: weekday_program.thermostat_daily_program_id,
    saturday_program_id: weekend_program.thermostat_daily_program_id,
    sunday_program_id: weekend_program.thermostat_daily_program_id
  )
  ```

  ```php PHP theme={null}
  // Create the daily programs.
  $weekday_program = $seam->thermostats->daily_programs->create(
    device_id: $updated_living_room_thermostat->device_id,
    name: "Weekday Program",
    periods: [
      { "starts_at_time": "07:00:00", "climate_preset_key": "Home" },
      { "starts_at_time": "09:00:00", "climate_preset_key": "Away" },
      { "starts_at_time": "18:00:00", "climate_preset_key": "Home" },
      { "starts_at_time": "22:00:00", "climate_preset_key": "Sleep" }
    ]
  );

  $weekend_program = $seam->thermostats->daily_programs->create(
    device_id: $updated_living_room_thermostat->device_id,
    name: "Weekend Program",
    periods: [
      { "starts_at_time": "08:00:00", "climate_preset_key": "Home" },
      { "starts_at_time": "23:00:00", "climate_preset_key": "Sleep" }
    ]
  );

  // Use the daily programs to set the weekly program.
  $seam->thermostats->update_weekly_program(
    device_id: $updated_living_room_thermostat->device_id,
    monday_program_id: $weekday_program->thermostat_daily_program_id,
    tuesday_program_id: $weekday_program->thermostat_daily_program_id,
    wednesday_program_id: $weekday_program->thermostat_daily_program_id,
    thursday_program_id: $weekday_program->thermostat_daily_program_id,
    friday_program_id: $weekday_program->thermostat_daily_program_id,
    saturday_program_id: $weekend_program->thermostat_daily_program_id,
    sunday_program_id: $weekend_program->thermostat_daily_program_id
  );
  ```

  ```csharp C# theme={null}
  // Coming soon!
  ```
</CodeGroup>

**Output:**

<CodeGroup>
  ```json JavaScript theme={null}
  {
    "status": "success",
    "action_attempt_id": "11111111-2222-3333-4444-666666666666",
    "action_type": "PUSH_THERMOSTAT_PROGRAMS",
    "result": {},
    "error": null
  }
  ```

  ```json cURL theme={null}
  {
    "action_attempt": {
      "status": "pending",
      "action_type": "PUSH_THERMOSTAT_PROGRAMS",
      "action_attempt_id": "11111111-2222-3333-4444-666666666666",
      "result": null,
      "error": null
    },
    "ok": true
  }
  ```

  ```json Python theme={null}
  ActionAttempt(
    action_attempt_id='11111111-2222-3333-4444-666666666666',
    action_type='PUSH_THERMOSTAT_PROGRAMS',
    status='success',
    result={},
    error=None
  )
  ```

  ```json Ruby theme={null}
  <Seam::Resources::ActionAttempt:0x005f0
    status="success"
    action_type="PUSH_THERMOSTAT_PROGRAMS"
    action_attempt_id="11111111-2222-3333-4444-666666666666"
    result={}
    error=nil>
  ```

  ```json PHP theme={null}
  {
    "status": "success",
    "action_attempt_id": "11111111-2222-3333-4444-666666666666",
    "action_type": "PUSH_THERMOSTAT_PROGRAMS",
    "result": {},
    "error": null
  }
  ```

  ```json C# theme={null}
  // Coming soon!
  ```
</CodeGroup>

***

## Step 5: Connect a real Honeywell Resideo thermostat

Now that you have learned the basics of using the Seam API, you can connect and control a real Honeywell Resideo device. To do so, make sure to switch to a [non-sandbox workspace](/core-concepts/workspaces#production-workspaces) and [API key](/core-concepts/authentication/api-keys).

For more details about setting up your real Honeywell Resideo thermostat, see the [Honeywell Resideo thermostats integration guide](./).

***

## Step 6: Build your application!

Seam makes it easy to develop your application. The robust Seam API and Seam SDKs in a wide variety of programming languages provide robust, up-to-date information about your thermostats. We also provide helpful thermostat-related events that enable you to monitor the status of your thermostats and the connected HVAC systems. Further, our simulation endpoints make it easy for you to test your thermostat app against events that can be difficult to orchestrate in your quality assurance (QA) environment using real devices.

***

## Next steps

Now that you've completed this getting started guide for Honeywell Resideo devices, you can learn more about what you can do with the Seam API.

* [ ] **Explore**\
  See the [other devices and system integrations](/device-and-system-integration-guides) that Seam supports.
* [ ] **Learn**\
  Read about Seam [concepts](/core-concepts/overview) and the [device and system capabilities ](/capability-guides/device-and-system-capabilities)that Seam supports.
* [ ] **Expand your abilities**\
  Find out what other [thermostat actions](/capability-guides/thermostats) you can perform using the Seam API.
* [ ] **Use webhooks**\
  Learn how to use [webhooks](/developer-tools/webhooks) as an efficient way to receive device events.
* [ ] **Find out more**\
  Explore the other types of devices and systems that you can control with Seam, including [smart locks](/low-level-apis/smart-locks), [access control systems](/low-level-apis/access-systems), and [noise sensors](/capability-guides/noise-sensors).
* [ ] **Develop for mobile access**\
  Learn about Seam's [mobile access solution](/capability-guides/mobile-access).

<Info>
  If you have any questions or want to report an issue, email us at
  [support@seam.co](mailto:support@seam.co).
</Info>

***

## Quick links

<CardGroup>
  <Card title="Get an API Key (free)" href="https://console.seam.co/">
    Sign up for the Seam Console and get your API keys. →
  </Card>

  <Card title="Contact Sales" href="https://www.seam.co/contact-us">
    Got a project or a specific question? Contact our team to get answers. →
  </Card>
</CardGroup>


# Honeywell Resideo Setup Guide
Source: https://docs.seam.co/device-and-system-integration-guides/honeywell-thermostats/honeywell-resideo-setup-guide

Connect your Honeywell Resideo thermostats to Seam.

This guide walks you through connecting your Honeywell Resideo thermostats to Seam. Your thermostats must already be set up and working in the Resideo app before proceeding.

## 1. Create a Resideo account

If you don't already have one, download the [Resideo app](https://www.resideo.com/us/en/resideo-smart-home-app/) and create an account. Add your Honeywell Resideo thermostats in the app and confirm they are online.

## 2. Connect Honeywell Resideo to Seam

Use the login credentials for your Resideo account to log in through the [Seam Connect Webview](/core-concepts/connect-webviews) and authorize Seam to access your devices.

## 3. Verify the connection

After completing the Connect Webview, confirm that your Honeywell Resideo thermostats appear in your Seam workspace and show an **online** status.

***

## Troubleshooting

If your devices don't appear after connecting:

* Confirm that your Honeywell Resideo thermostats are online in the Resideo app.
* Verify that you logged in with the same Resideo account that owns the thermostats.
* Wait a few minutes for the initial sync to complete, then refresh your device list.


# Honeywell Resideo Thermostats
Source: https://docs.seam.co/device-and-system-integration-guides/honeywell-thermostats/index

Guide for using Honeywell Resideo thermostats with Seam

<img alt="Honeywell logo" />

## Overview

Honeywell Resideo produces Wi-Fi smart thermostats to manage energy costs while maintaining comfortable temperatures. Honeywell Resideo thermostat models include a variety of features, such as color touchscreens.

***

## Supported Devices

<DeviceList />

This integration supports [Honeywell Resideo Wi-Fi-enabled thermostats](https://www.resideo.com/us/en/products/air/thermostats/).

For detailed information about the Honeywell devices that Seam supports, see our [Honeywell Supported Devices page](https://www.seam.co/manufacturers/honeywell).

***

## Supported Features

We support the following features:

* [Configuring current thermostat settings](/capability-guides/thermostats/configure-current-climate-settings)
* [Creating and managing climate presets](/capability-guides/thermostats/creating-and-managing-climate-presets)
* [Creating and managing thermostat schedules](/capability-guides/thermostats/creating-and-managing-thermostat-schedules)
* [Creating and managing thermostat weekly programs](/capability-guides/thermostats/creating-and-managing-thermostat-programs)
* [Setting and monitoring temperature thresholds](/capability-guides/thermostats/setting-and-monitoring-temperature-thresholds)

***

### Device Provider Key

Seam identifies these devices with the `honeywell_resideo` device provider key. By default, a [Connect Webview](/core-concepts/connect-webviews) displays all of the stable providers that Seam supports, so your users can connect their Honeywell Resideo devices without you specifying a provider list. To narrow what a Connect Webview displays, see [Customize the Brands to Display in Your Connect Webviews](/core-concepts/connect-webviews/customizing-connect-webviews#customize-the-brands-to-display-in-your-connect-webviews).

***

## Setup Instructions

For instructions on connecting Honeywell Resideo thermostats to Seam, see the [Honeywell Resideo Setup Guide](./honeywell-resideo-setup-guide).

***

## Where to Order

To purchase Honeywell Resideo thermostats, visit the Honeywell Resideo online store.

<table>
  <thead>
    <tr>
      <th />

      <th />

      <th />

      <th />

      <th />
    </tr>
  </thead>

  <tbody>
    <tr>
      <td />

      <td>
        <strong>Honeywell Resideo Online Store</strong>
      </td>

      <td />

      <td>
        <a href="https://www.resideo.com/us/en/products/air/thermostats/">
          [https://www.resideo.com/us/en/products/air/thermostats/](https://www.resideo.com/us/en/products/air/thermostats/)
        </a>
      </td>

      <td>
        <a href="/images/honeywell-logo.png">honeywell-logo.png</a>
      </td>
    </tr>
  </tbody>
</table>

***


# Sandbox Honeywell Resideo Thermostats
Source: https://docs.seam.co/device-and-system-integration-guides/honeywell-thermostats/sandbox-honeywell-thermostats

Add virtual Honeywell Resideo thermostats to your Seam sandbox workspace using these sample credentials to test your integration without real hardware.

Use the following set of credentials to add virtual [Honeywell Resideo thermostats](/device-and-system-integration-guides/honeywell-thermostats) to your Seam [sandbox workspace](/core-concepts/workspaces#sandbox-workspaces):

| Email Address                                                                              | Password |
| ------------------------------------------------------------------------------------------ | -------- |
| [jane@example.com](mailto:jane@example.com) or any email address in the example.com domain | 1234     |


# Finding Your Room Numbers, Common Doors, and Encoders
Source: https://docs.seam.co/device-and-system-integration-guides/hotek-access-control-system/finding-your-room-numbers-common-doors-and-encoders

How to find the room numbers, common doors, and encoder details that Seam needs to finish configuring your Hotek system.

After connecting your Hotek system through Seam, Seam needs three pieces of information to finish configuring your account. You can find all of this in the Hotek SMART software.

<Info>
  If you provided a setup instructions email when connecting, Seam sends you an email with your Connected Account ID and instructions. Otherwise, send the information below to [support@getseam.com](mailto:support@getseam.com) along with your Connected Account ID.
</Info>

***

## Guest Rooms

1. Open Hotek SMART.
2. Click the **Room** icon in the top-left corner of the screen.
3. Adjust the **Lock Name** column to make sure the full name is visible.
4. Send screenshots of the full room list, showing the **Lock No.** and **Lock Name** columns. Scroll and send multiple screenshots if needed.

***

## Common Doors

1. In Hotek SMART, click the **Room** icon in the top-left corner of the screen.
2. Click the **Common Door** tab at the bottom of the screen.
3. Adjust the **Name** column to make sure the full name is visible.
4. Send screenshots of the full common door list, showing the **Code** and **Name** columns. Scroll and send multiple screenshots if needed.

***

## Encoders

1. In Hotek SMART, click **Card** in the menu bar.
2. Click **TCP Encoder**.
3. Send a screenshot showing the **Encoder No.** column.

<Tip>
  If you're using a USB encoder instead of a TCP encoder, let Seam support know in your email.
</Tip>


# Get Started with the Hotek Access Control System
Source: https://docs.seam.co/device-and-system-integration-guides/hotek-access-control-system/get-started-with-hotek-access-control-system

Learn how to connect and control your Hotek access control system with the Seam API.

## Overview

Seam provides a universal API to connect and control many brands of access control systems. This guide provides a rapid introduction to connecting and controlling your [Hotek](https://www.seam.co/manufacturers/hotek) access control system using the Seam API.

Hotek systems communicate over TCP via a [Seam Bridge](/capability-guides/seam-bridge) installed on the property network.

To learn more about other access control systems supported by Seam, head over to our [integration page](https://www.seam.co/supported-devices-and-systems).

***

## 1 — Install Seam SDK

Seam provides client libraries for many languages, such as JavaScript, Python, Ruby, PHP, and others, as well as a Postman collection and [OpenAPI](https://connect.getseam.com/openapi.json) spec.

* JavaScript / TypeScript ([npm](https://www.npmjs.com/package/seam), [GitHub](https://github.com/seamapi/javascript))
* Python ([pip](https://pypi.org/project/seam/), [GitHub](https://github.com/seamapi/python))
* Ruby Gem ([rubygem](https://rubygems.org/gems/seam), [GitHub](https://github.com/seamapi/ruby))
* PHP ([packagist](https://packagist.org/packages/seamapi/seam), [GitHub](https://github.com/seamapi/php))
* C# ([nuget](https://www.nuget.org/packages/Seam), [GitHub](https://github.com/seamapi/csharp))
* Java ([Maven](https://central.sonatype.com/artifact/co.seam/java), [GitHub](https://github.com/seamapi/java))

<CodeGroup>
  ```bash JavaScript theme={null}
  npm i seam
  ```

  ```bash Python theme={null}
  pip install seam
  # For some development environments, use pip3 in this command instead of pip.
  ```

  ```bash Ruby theme={null}
  bundle add seam
  ```

  ```bash PHP theme={null}
  composer require seamapi/seam
  ```

  ```bash C# theme={null}
  Install using nuget: https://www.nuget.org/packages/Seam
  ```

  ```bash Java theme={null}
  // Add to your pom.xml or build.gradle — see Maven Central for details.
  ```

  ```bash cURL (bash) theme={null}
  # cURL is already installed on most systems. No additional installation needed.
  # Export your API key as an environment variable:
  export SEAM_API_KEY=seam_test2ZTo_0mEYQW2TvNDCxG5Atpj85Ffw
  ```
</CodeGroup>

Once installed, [sign up for Seam](https://console.seam.co/) to get your API key, and export it as an environment variable:

```bash theme={null}
export SEAM_API_KEY=seam_test2ZTo_0mEYQW2TvNDCxG5Atpj85Ffw
```

<Info>
  This guide uses a Sandbox Workspace. Only virtual devices can be connected. If
  you need to connect a real Hotek system, use a non-sandbox workspace and API key.
</Info>

***

## 2 — Link Hotek System with Seam

To control your Hotek system via the Seam API, you must first authorize your Seam workspace against your Hotek installation. To do so, Seam provides [Connect Webviews](/core-concepts/connect-webviews): pre-built UX flows that walk you through authorizing your application to control your Hotek system.

#### Request a Connect Webview

<CodeGroup>
  ```javascript JavaScript theme={null}
  import { Seam } from "seam";

  const seam = new Seam();

  const connectWebview = await seam.connectWebviews.create();

  console.log(connectWebview.login_successful); // false

  // Send the webview URL to your user
  console.log(connectWebview.url);
  ```

  ```python Python theme={null}
  from seam import Seam

  seam = Seam()

  webview = seam.connect_webviews.create()

  assert webview.login_successful is False

  # Send the webview URL to your user
  print(webview.url)
  ```

  ```ruby Ruby theme={null}
  require "seam"

  seam = Seam.new(api_key: "MY_API_KEY")

  webview = seam.connect_webviews.create()

  puts webview.login_successful # false

  # Send the webview URL to your user
  puts webview.url
  ```

  ```php PHP theme={null}
  <?php
  use Seam\SeamClient;

  $seam = new SeamClient("YOUR_API_KEY");

  $webview = $seam->connect_webviews->create();

  echo $webview->login_successful; // false

  // Send the webview URL to your user
  echo $webview->url;
  ```

  ```csharp C# theme={null}
  using Seam.Client;

  var seam = new SeamClient(apiToken: "YOUR_API_KEY");

  var webview = seam.ConnectWebviews.Create();

  Console.WriteLine(webview.LoginSuccessful); // false

  // Send the webview URL to your user
  Console.WriteLine(webview.Url);
  ```

  ```java Java theme={null}
  import co.seam.Seam;
  import co.seam.api.types.ConnectWebview;

  Seam seam = Seam.builder().apiKey("YOUR_API_KEY").build();

  ConnectWebview webview = seam.connectWebviews().create(
    ConnectWebviewsCreateRequest.builder()
      .build()
  );

  System.out.println(webview.getLoginSuccessful()); // false

  // Send the webview URL to your user
  System.out.println(webview.getUrl());
  ```

  ```bash cURL (bash) theme={null}
  curl -X 'POST' \
    'https://connect.getseam.com/connect_webviews/create' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d '{}'
  ```
</CodeGroup>

#### Authorize Your Workspace

Navigate to the URL returned by the Webview object. Since you are using a sandbox workspace, complete the login flow by entering the Hotek [sandbox test credentials](/device-and-system-integration-guides/hotek-access-control-system/sandbox-hotek-access-control-system):

1. **Bridge connection** — the pairing token is prefilled in sandbox mode
2. **Hotek Dashboard Credentials:**
   * **Site Name:** Any string (e.g., "My Hotek Site")
   * **TCP Port:** Any port number
   * **Hotek SMART Server IP Address:** prefilled

Confirm the Connect Webview was successful by querying its status:

<CodeGroup>
  ```javascript JavaScript theme={null}
  const updatedWebview = await seam.connectWebviews.get(
    connectWebview.connect_webview_id
  );

  console.log(updatedWebview.login_successful); // true
  ```

  ```python Python theme={null}
  updated_webview = seam.connect_webviews.get(
      connect_webview_id=webview.connect_webview_id
  )

  assert updated_webview.login_successful  # true
  ```

  ```ruby Ruby theme={null}
  updated_webview = seam.connect_webviews.get(
    connect_webview_id: webview.connect_webview_id
  )

  puts updated_webview.login_successful # true
  ```

  ```php PHP theme={null}
  <?php
  $updated_webview = $seam->connect_webviews->get(
    connect_webview_id: $webview->connect_webview_id
  );

  echo $updated_webview->login_successful; // true
  ```

  ```csharp C# theme={null}
  var updatedWebview = seam.ConnectWebviews.Get(
    connectWebviewId: webview.ConnectWebviewId
  );

  Console.WriteLine(updatedWebview.LoginSuccessful); // true
  ```

  ```java Java theme={null}
  ConnectWebview updatedWebview = seam.connectWebviews().get(
    ConnectWebviewsGetRequest.builder()
      .connectWebviewId(webview.getConnectWebviewId())
      .build()
  );

  System.out.println(updatedWebview.getLoginSuccessful()); // true
  ```

  ```bash cURL (bash) theme={null}
  curl -X 'POST' \
    'https://connect.getseam.com/connect_webviews/get' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d "{
      \"connect_webview_id\": \"${CONNECT_WEBVIEW_ID}\"
    }"
  ```
</CodeGroup>

***

## 3 — Retrieve the ACS System

After the Hotek system is linked with Seam, you can retrieve the ACS system. This represents the connected Hotek SMART Server installation.

<CodeGroup>
  ```javascript JavaScript theme={null}
  const systems = await seam.acs.systems.list();

  const hotekSystem = systems[0];

  console.log(hotekSystem);
  /*
  {
    acs_system_id: '...',
    name: 'My Hotek Site',
    external_type: 'hotek_site',
    connected_account_ids: ['...'],
    ...
  }
  */
  ```

  ```python Python theme={null}
  systems = seam.acs.systems.list()

  hotek_system = systems[0]

  print(hotek_system)
  # AcsSystem(
  #   acs_system_id='...',
  #   name='My Hotek Site',
  #   external_type='hotek_site',
  #   ...
  # )
  ```

  ```ruby Ruby theme={null}
  systems = seam.acs.systems.list

  hotek_system = systems.first

  puts hotek_system
  ```

  ```php PHP theme={null}
  <?php
  $systems = $seam->acs->systems->list();

  $hotek_system = $systems[0];

  echo $hotek_system->name; // My Hotek Site
  ```

  ```csharp C# theme={null}
  var systems = seam.Acs.Systems.List();

  var hotekSystem = systems[0];

  Console.WriteLine(hotekSystem.Name); // My Hotek Site
  ```

  ```java Java theme={null}
  var systems = seam.acs().systems().list();

  var hotekSystem = systems.get(0);

  System.out.println(hotekSystem.getName()); // My Hotek Site
  ```

  ```bash cURL (bash) theme={null}
  curl -X 'POST' \
    'https://connect.getseam.com/acs/systems/list' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d '{}'
  ```
</CodeGroup>

***

## 4 — List Entrances

Entrances represent the doors managed by the Hotek system. In the sandbox, this includes guest rooms (101-104, 201-204).

<CodeGroup>
  ```javascript JavaScript theme={null}
  const entrances = await seam.acs.entrances.list({
    acs_system_id: hotekSystem.acs_system_id,
  });

  console.log(entrances);
  /*
  [
    {
      acs_entrance_id: '...',
      display_name: 'Room 101',
      hotek_metadata: {
        room_number: '101',
        door_type: 'guest'
      },
      ...
    },
    ...
  ]
  */
  ```

  ```python Python theme={null}
  entrances = seam.acs.entrances.list(
      acs_system_id=hotek_system.acs_system_id
  )

  print(entrances)
  ```

  ```ruby Ruby theme={null}
  entrances = seam.acs.entrances.list(
    acs_system_id: hotek_system.acs_system_id
  )

  puts entrances
  ```

  ```php PHP theme={null}
  <?php
  $entrances = $seam->acs->entrances->list(
    acs_system_id: $hotek_system->acs_system_id
  );

  print_r($entrances);
  ```

  ```csharp C# theme={null}
  var entrances = seam.Acs.Entrances.List(
    acsSystemId: hotekSystem.AcsSystemId
  );

  foreach (var entrance in entrances)
  {
    Console.WriteLine(entrance.DisplayName);
  }
  ```

  ```java Java theme={null}
  var entrances = seam.acs().entrances().list(
    AcsEntrancesListRequest.builder()
      .acsSystemId(hotekSystem.getAcsSystemId())
      .build()
  );

  System.out.println(entrances);
  ```

  ```bash cURL (bash) theme={null}
  curl -X 'POST' \
    'https://connect.getseam.com/acs/entrances/list' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d "{\"acs_system_id\": \"${ACS_SYSTEM_ID}\"}"
  ```
</CodeGroup>

***

## 5 — Create a User and Issue a Credential

To grant access to a guest, create an ACS user and then issue a credential (key card) for the entrances they should access.

#### Create an ACS User

<CodeGroup>
  ```javascript JavaScript theme={null}
  const user = await seam.acs.users.create({
    acs_system_id: hotekSystem.acs_system_id,
    full_name: "Jane Guest",
  });

  console.log(user.acs_user_id);
  ```

  ```python Python theme={null}
  user = seam.acs.users.create(
      acs_system_id=hotek_system.acs_system_id,
      full_name="Jane Guest"
  )

  print(user.acs_user_id)
  ```

  ```ruby Ruby theme={null}
  user = seam.acs.users.create(
    acs_system_id: hotek_system.acs_system_id,
    full_name: "Jane Guest"
  )

  puts user.acs_user_id
  ```

  ```php PHP theme={null}
  <?php
  $user = $seam->acs->users->create(
    acs_system_id: $hotek_system->acs_system_id,
    full_name: "Jane Guest"
  );

  echo $user->acs_user_id;
  ```

  ```csharp C# theme={null}
  var user = seam.Acs.Users.Create(
    acsSystemId: hotekSystem.AcsSystemId,
    fullName: "Jane Guest"
  );

  Console.WriteLine(user.AcsUserId);
  ```

  ```java Java theme={null}
  var user = seam.acs().users().create(
    AcsUsersCreateRequest.builder()
      .acsSystemId(hotekSystem.getAcsSystemId())
      .fullName("Jane Guest")
      .build()
  );

  System.out.println(user.getAcsUserId());
  ```

  ```bash cURL (bash) theme={null}
  curl -X 'POST' \
    'https://connect.getseam.com/acs/users/create' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d "{
      \"acs_system_id\": \"${ACS_SYSTEM_ID}\",
      \"full_name\": \"Jane Guest\"
    }"
  ```
</CodeGroup>

#### Create a Credential for the User

<CodeGroup>
  ```javascript JavaScript theme={null}
  const credential = await seam.acs.credentials.create({
    acs_user_id: user.acs_user_id,
    access_method: "card",
    allowed_acs_entrance_ids: [
      entrances.find((e) => e.display_name === "Room 101").acs_entrance_id,
    ],
  });

  console.log(credential);
  /*
  {
    acs_credential_id: '...',
    access_method: 'card',
    ...
  }
  */
  ```

  ```python Python theme={null}
  room_101 = next(e for e in entrances if e.display_name == "Room 101")

  credential = seam.acs.credentials.create(
      acs_user_id=user.acs_user_id,
      access_method="card",
      allowed_acs_entrance_ids=[room_101.acs_entrance_id]
  )

  print(credential)
  ```

  ```ruby Ruby theme={null}
  room_101 = entrances.find { |e| e.display_name == "Room 101" }

  credential = seam.acs.credentials.create(
    acs_user_id: user.acs_user_id,
    access_method: "card",
    allowed_acs_entrance_ids: [room_101.acs_entrance_id]
  )

  puts credential
  ```

  ```php PHP theme={null}
  <?php
  $room_101 = array_values(array_filter(
    $entrances,
    fn($e) => $e->display_name === "Room 101"
  ))[0];

  $credential = $seam->acs->credentials->create(
    acs_user_id: $user->acs_user_id,
    access_method: "card",
    allowed_acs_entrance_ids: [$room_101->acs_entrance_id]
  );

  print_r($credential);
  ```

  ```csharp C# theme={null}
  var room101 = entrances.First(e => e.DisplayName == "Room 101");

  var credential = seam.Acs.Credentials.Create(
    acsUserId: user.AcsUserId,
    accessMethod: "card",
    allowedAcsEntranceIds: new List<string> { room101.AcsEntranceId }
  );

  Console.WriteLine(credential.AcsCredentialId);
  ```

  ```java Java theme={null}
  var room101 = entrances.stream()
      .filter(e -> "Room 101".equals(e.getDisplayName()))
      .findFirst()
      .orElseThrow();

  var credential = seam.acs().credentials().create(
    AcsCredentialsCreateRequest.builder()
      .acsUserId(user.getAcsUserId())
      .accessMethod("card")
      .allowedAcsEntranceIds(List.of(room101.getAcsEntranceId()))
      .build()
  );

  System.out.println(credential.getAcsCredentialId());
  ```

  ```bash cURL (bash) theme={null}
  curl -X 'POST' \
    'https://connect.getseam.com/acs/credentials/create' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d "{
      \"acs_user_id\": \"${ACS_USER_ID}\",
      \"access_method\": \"card\",
      \"allowed_acs_entrance_ids\": [\"${ACS_ENTRANCE_ID}\"]
    }"
  ```
</CodeGroup>

***

## Next Steps

Now that you've completed this guide, you can try connecting a real Hotek system. To do so, make sure to switch to a non-sandbox workspace and API key, and ensure you have a [Seam Bridge](/capability-guides/seam-bridge) installed on the property network.

In addition, if you'd like to explore other aspects of Seam, here is a list of helpful resources:

* [Access Grants](/use-cases/granting-access) — the recommended way to manage access across providers
* [Plastic Card Encoding](/api/acs/encoders/encode_credential) — encode physical key cards
* [Receiving webhooks](/developer-tools/webhooks) for [device events](/api/events/list)
* [Core Concepts](/core-concepts/overview)

If you have any questions or want to report an issue, email us at [support@seam.co](mailto:support@seam.co).


# Hotek Setup Guide
Source: https://docs.seam.co/device-and-system-integration-guides/hotek-access-control-system/hotek-setup-guide

Configure your Hotek SMART system and connect it to Seam through a Seam Bridge.

## Overview

This guide walks you through connecting a Hotek SMART access control system to Seam. The integration requires a [Seam Bridge](/capability-guides/seam-bridge) installed on the same network as the Hotek SMART Server, which relays commands between Seam's cloud API and the on-premise Hotek system over TCP.

<Info>
  This guide assumes the Hotek SMART system and LockOH PMS Server are already installed and running at the property.
</Info>

***

## Prerequisites

Before you begin, ensure you have:

* Hotek SMART software installed and running at the property
* A [Seam Bridge](/capability-guides/seam-bridge) installed on the same machine as Hotek SMART (or on the same local network)
* The TCP port number for the Hotek SMART PMS Server (default: `10003`)

***

## Step 1: Find Your TCP Port

Hotek SMART listens for PMS commands on a TCP port. The default is `10003`. To confirm, open **Command Prompt** on the machine running Hotek SMART and run:

```bash theme={null}
for /f "tokens=2" %i in ('tasklist /FI "IMAGENAME eq PMSServer.exe" /NH') do netstat -ano | findstr "LISTENING" | findstr "%i"
```

You should see output like:

```
TCP    0.0.0.0:10003    0.0.0.0:0    LISTENING    5712
```

<Tip>
  If you see multiple ports, use `10003` — that's the standard PMS interface port.
</Tip>

***

## Step 2: Connect to Seam

1. Open the [Connect Webview](/core-concepts/connect-webviews) provided by your application.
2. Select **Hotek** as the provider.
3. Complete the **Seam Bridge** section by entering your Bridge connection details as shown in your Bridge UI.
4. Complete the **Hotek** section with your connection details:

| Field                        | Description                                                                                                                                                                       |
| ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Site Name**                | A name for your Hotek site (e.g., "Hotel Marlin")                                                                                                                                 |
| **TCP Port**                 | The port from Step 1 (default: `10003`)                                                                                                                                           |
| **Remote IP**                | If the Seam Bridge and Hotek SMART are on different computers, check the box and enter the IP address of the Hotek SMART server. Leave unchecked if they run on the same machine. |
| **Setup Instructions Email** | (Optional) Enter an email and Seam sends instructions for completing setup                                                                                                        |

Once connected, a new Hotek ACS system appears in Seam and shows as **connected** once the Bridge can reach the Hotek SMART Server.

***

## Step 3: Provide Room Numbers, Common Doors, and Encoders

After connecting, Seam needs three pieces of information to finish configuring your account. You can find all of this in the Hotek SMART software. For detailed instructions with screenshots, see [Finding Your Room Numbers, Common Doors, and Encoders](./finding-your-room-numbers-common-doors-and-encoders).

<Info>
  Entrance and encoder setup is currently managed by Seam support. If you provided a setup instructions email in the previous step, Seam sends you an email with your Connected Account ID and instructions. Otherwise, send the information below to [support@getseam.com](mailto:support@getseam.com) along with your Connected Account ID.
</Info>

### Guest Rooms

1. Open Hotek SMART.
2. Click the **Room** icon in the top-left corner of the screen.
3. Adjust the **Lock Name** column to make sure the full name is visible.
4. Send screenshots of the full room list, showing the **Lock No.** and **Lock Name** columns. Scroll and send multiple screenshots if needed.

### Common Doors

1. In Hotek SMART, click the **Room** icon in the top-left corner of the screen.
2. Click the **Common Door** tab at the bottom of the screen.
3. Adjust the **Name** column to make sure the full name is visible.
4. Send screenshots of the full common door list, showing the **Code** and **Name** columns. Scroll and send multiple screenshots if needed.

### Encoders

1. In Hotek SMART, click **Card** in the menu bar.
2. Click **TCP Encoder**.
3. Send a screenshot showing the **Encoder No.** column.

<Tip>
  If you're using a USB encoder instead of a TCP encoder, let Seam support know in your email.
</Tip>

Seam support will configure the rooms, common doors, and encoders so they appear as entrances and encoders in your Seam workspace.

***

## Step 4: Verify the Connection

Once setup is complete, verify that your Hotek ACS system shows as connected, your configured rooms and common areas appear as entrances, and your encoders are listed.

***

## Troubleshooting

### Can't find PMSServer.exe

Hotek SMART may not be running. Launch it from the Start menu or check Task Manager.

### Connection times out

Verify that the Seam Bridge is running, confirm the TCP port, and check that the firewall allows inbound connections on that port.

From the Bridge host machine, you can test connectivity:

```bash theme={null}
nc -zv <tcp_host> <tcp_port>
# Example: nc -zv 127.0.0.1 10003
```

If the Hotek SMART Server runs on a different machine than the Bridge, make sure you checked the remote IP box and entered the server's LAN IP address.

### Encoder not found

Confirm that you sent encoder details to Seam support. The encoder must be registered with the ACS system before it can be used for card encoding.

### Rooms not appearing as entrances

The room numbers in Seam must match the room list in Hotek SMART. Check the **Room** list in the Hotek SMART application and verify the room numbers match what was provided to Seam support.

### Duplicate site name

Use a unique Site Name for each Hotek installation to avoid confusion when managing multiple properties.

### Feature flag not enabled

Contact [Seam support](mailto:support@getseam.com) if the Hotek provider does not appear as an option when connecting.


# Hotek Access Control System
Source: https://docs.seam.co/device-and-system-integration-guides/hotek-access-control-system/index

Guide for using the Hotek access control system with Seam

<img alt="Hotek logo" />

## Overview

Hotek manufactures access control systems designed for the hospitality industry. Their SMART Server platform manages electronic door locks, encoders, and room access across hotel properties, communicating with locks over TCP via a local network.

Seam integrates with Hotek through a [Seam Bridge](/capability-guides/seam-bridge) connection to the Hotek SMART Server. This enables you to manage entrances (rooms and common areas), provision credentials (key cards), and encode plastic cards using Seam's unified API — all without direct interaction with the Hotek system.

<Info>
  Hotek requires a [Seam Bridge](/capability-guides/seam-bridge) installed on the property network. The bridge relays commands between Seam's cloud API and the on-premise Hotek server over TCP.
</Info>

***

## Supported Devices

<DeviceList />

This integration supports all electronic door locks and encoders connected to a Hotek SMART Server. The Hotek system manages two types of entrances:

* **Guest rooms** — individual hotel room doors (e.g., Room 101, Room 202)
* **Common areas** — shared spaces such as lobbies, gyms, and pools

For detailed information about the Hotek devices that Seam supports, see our [Hotek Supported Devices page](https://www.seam.co/manufacturers/hotek).

***

## Supported Features

We support the following features:

* Managing ACS users (guests and staff)
* Listing and managing entrances (guest rooms and common areas)
* Creating and revoking credentials (key cards)
* Encoding plastic cards via connected encoders

***

## Related Features

* [**Access Grants**](/use-cases/granting-access) — The recommended way to manage access in Seam. Integrate once, and your access model works consistently across all providers, including Hotek.
* [**Plastic Card Encoding**](/api/acs/encoders/encode_credential) — Encode and issue physical key cards using Seam's card management API.

***

## Brand-Specific Restrictions

Hotek locks do not support remote web unlock. Access is granted by encoding physical key cards or issuing credentials that work with the lock hardware.

***

## Device Provider Key

Seam identifies these devices with the `hotek` device provider key. By default, a [Connect Webview](/core-concepts/connect-webviews) displays all of the stable providers that Seam supports, so your users can connect their Hotek system without you specifying a provider list. To narrow what a Connect Webview displays, see [Customize the Brands to Display in Your Connect Webviews](/core-concepts/connect-webviews/customizing-connect-webviews#customize-the-brands-to-display-in-your-connect-webviews).

***

## Setup Instructions

For step-by-step instructions on connecting a Hotek system to Seam — including Bridge configuration, entrance and encoder setup, and troubleshooting — see the [Hotek Setup Guide](./hotek-setup-guide).

***

## Where to Order

<CardGroup>
  <Card title="Hotek - Electronic Hotel Lock Solutions" href="https://www.hotek.com" />
</CardGroup>


# Sandbox Hotek Access Control System
Source: https://docs.seam.co/device-and-system-integration-guides/hotek-access-control-system/sandbox-hotek-access-control-system

Add a virtual Hotek access control system to your Seam sandbox workspace using these Connect Webview credentials to test your integration.

Use the following set of credentials to add virtual Hotek Access Control System-connected devices to your Seam [sandbox workspace](/core-concepts/workspaces#sandbox-workspaces):

## Hotek Connect Webview Credentials

#### 1. Bridge connection pane

| Pairing Token            |
| ------------------------ |
| *<mark>prefilled</mark>* |

#### 2. Hotek Dashboard Credentials

<table>
  <thead>
    <tr>
      <th>Field</th>
      <th>Value</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Site Name</td>

      <td>
        Any string to identify this Hotek ACS site, for example, My Hotek Site
      </td>
    </tr>

    <tr>
      <td>TCP Port</td>

      <td>
        <em>
          <mark>any port number</mark>
        </em>
      </td>
    </tr>

    <tr>
      <td>Hotek SMART Server IP Address</td>

      <td>
        <em>
          <mark>prefilled</mark>
        </em>
      </td>
    </tr>
  </tbody>
</table>

***


# Creating igloohome Offline Access Codes
Source: https://docs.seam.co/device-and-system-integration-guides/igloohome-locks/creating-igloohome-offline-access-codes

Learn how to create igloohome offline access codes, including understanding manufacturer-specific requirements.

In addition to supporting [online access codes](/low-level-apis/smart-locks/access-codes), the Seam integration for igloohome supports the generation of offline access codes (that is, igloohome [algoPIN™](https://www.igloohome.co/en-US/how-it-works) codes) for all igloohome lock models, without the need for a bridge. You generate offline access (PIN) codes remotely, and the manufacturer maintains a server-based registry of synchronized encryption keys (tokens) to enable these offline codes. Then, owners or managers can share these codes with users through messaging or other similar applications, and the users do not need to install a special application to unlock the device.

To learn about the special requirements regarding offline access codes for igloohome locks, see [Offline Access Code Requirements](#offline-access-code-requirements). For more information about using offline access codes, see [Offline Access Codes](/low-level-apis/smart-locks/access-codes#offline-access-codes) and [Managing Offline Access Codes](/low-level-apis/smart-locks/access-codes/offline-access-codes).

***

## Offline Access Code Requirements

Seam supports the following types of [offline access codes](/low-level-apis/smart-locks/access-codes/offline-access-codes) for igloohome locks:

* [Hourly-bound](#hourly-bound-offline-access-codes)
* [Daily-bound](#daily-bound-offline-access-codes)
* [One-time-use](#one-time-use-offline-access-codes)

Note the following igloohome-specific offline access code constraints:

### **General igloohome Offline Access Code Constraints**

| Constraint                            | Description                                                                                                                                              |
| ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Total maximum number of offline codes | 199 PINs, including online and offline PINs.                                                                                                             |
| Creation                              | You cannot set a custom code for an offline access code that represents an algoPIN.                                                                      |
| Update                                | You cannot modify an offline access code that represents an algoPIN.                                                                                     |
| Activation                            | For codes that last longer than 24 hours, algoPINs have a 24-hour activation window. Use the code within the first 24 hours of the start time.           |
| Revocation                            | To delete algoPINs, you must be within Bluetooth® range of the lock. You cannot use the Seam API to delete offline access codes that represent algoPINs. |

### **Hourly-Bound Offline Access Code Constraints**

| Constraint                                    | Description               |
| --------------------------------------------- | ------------------------- |
| Range of hourly-bound codes                   | 1 to 672 hours (28 days). |
| Maximum number of hourly-bound codes per hour | 3                         |

### **Daily-Bound Offline Access Code Constraints**

| Constraint                                  | Description                         |
| ------------------------------------------- | ----------------------------------- |
| Range of daily-bound codes                  | 29 to 367 days.                     |
| Daily-bound code schedule restrictions      | Start time and end time must match. |
| Maximum number of daily-bound codes per day | 3                                   |

### **One-Time-User Offline Access Code Constraints**

| Constraint                                               | Description                                                                    |
| -------------------------------------------------------- | ------------------------------------------------------------------------------ |
| Timeframe for one-time-use codes                         | <ul><li>Must have a start date and time.</li><li>Lasts for 24 hours.</li></ul> |
| Maximum number of one-time-use codes per start date slot | 5                                                                              |
| One-time-use code expiration                             | Expire after a single use.                                                     |

***

## Programming igloohome Offline Access Codes

You can create hourly-bound, daily-bound, and one-time-use offline access codes for igloohome devices.

### Hourly-Bound Offline Access Codes

To [create an hourly-bound offline access code](/low-level-apis/smart-locks/access-codes/offline-access-codes#creating-time-bound-offline-access-codes), issue an access code creation request. Then, poll or use a webhook to confirm that the code was registered successfully in the igloohome offline access code server.

#### 1. Create an Hourly-Bound Offline Access Code

To create an hourly-bound offline access code, provide the `device_id` of the lock for which you want to create the code and set `is_offline_access_code` to `true`. Specify the `starts_at` and `ends_at` [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) timestamps to define the active time window for the offline code. You can also assign an optional `name` to the offline access code. For more details, see the [Create Access Code endpoint](/api/access_codes/create).

**Request:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  // Get the device.
  const device = await seam.locks.get({
    device_id: '11111111-1111-1111-1111-444444444444',
  })

  // Confirm that the device supports offline access codes.
  if (device.can_program_offline_access_codes) {
    // Create the hourly-bound offline access code.
    await seam.accessCodes.create({
      device_id: device.device_id,
      name: 'my hourly-bound offline code',
      starts_at: '2023-11-10T00:00:00-00:00',
      ends_at: '2023-11-15T18:00:00-00:00',
      is_offline_access_code: true,
    })
  }
  ```

  ```sh cURL theme={null}
  # 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 offline access codes.
  if  $(jq -r '.device.can_program_offline_access_codes' <<< ${device}); then \
    # Create the hourly-bound offline 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 hourly-bound offline code\",
        \"starts_at\": \"2023-11-10T00:00:00-00:00\",
        \"ends_at\": \"2023-11-15T18:00:00-00:00\",
        \"is_offline_access_code\": true
    }";
  fi
  ```

  ```python Python theme={null}
  # Get the device.
  device = seam.locks.get(
    device_id="11111111-1111-1111-1111-444444444444"
  )

  # Confirm that the device supports offline access codes.
  if device.can_program_offline_access_codes:
    # Create the hourly-bound offline access code.
    seam.access_codes.create(
      device_id = device.device_id,
      name = "my hourly-bound offline code",
      starts_at = "2023-11-10T00:00:00-00:00",
      ends_at = "2023-11-15T18:00:00-00:00",
      is_offline_access_code = True
    )
  ```

  ```ruby Ruby theme={null}
  # Get the device.
  device = client.locks.get(device_id: "11111111-1111-1111-1111-444444444444")

  # Confirm that the device supports offline access codes.
  if (device.can_program_offline_access_codes)
    # Create the hourly-bound offline access code.
    client.access_codes.create(
      device_id: device.device_id,
      name: "my hourly-bound offline code",
      starts_at: "2023-11-10T00:00:00-00:00",
      ends_at: "2023-11-15T18:00:00-00:00",
      is_offline_access_code: true
    )
  end
  ```

  ```php PHP theme={null}
  // Get the device.
  $device = $seam->locks->get(device_id: "11111111-1111-1111-1111-444444444444");

  // Confirm that the device supports offline access codes.
  if ($device->can_program_offline_access_codes) {
    // Create the hourly-bound offline access code.
    $seam->access_codes->create(
      device_id: $device->device_id,
      name: "my hourly-bound offline code",
      starts_at: "2023-11-10T00:00:00Z",
      ends_at: "2023-11-15T18:00:00Z",
      is_offline_access_code: true
    );
  }
  ```

  ```csharp C# theme={null}
  // Get the device.
  Device device = seam.Locks.Get(deviceId: "11111111-1111-1111-1111-444444444444");

  // Confirm that the device supports offline access codes.
  if (device.CanProgramOfflineAccessCodes == true) {
    // Create the hourly-bound offline access code.
    seam.AccessCodes.Create(
      deviceId: device.DeviceId,
      name: "my hourly-bound offline code",
      startsAt: "2023-11-10T00:00:00Z",
      endsAt: "2023-11-15T18:00:00Z",
      isOfflineAccessCode: true
    );
  }
  ```
</CodeGroup>

**Response:**

<CodeGroup>
  ```json JavaScript theme={null}
  {
    access_code_id: '11111111-1111-1111-1111-777777777777',
    device_id: '11111111-1111-1111-1111-444444444444',
    name: 'my hourly-bound offline code',
    type: 'time_bound',
    starts_at: '2023-11-10T00:00:00.000Z',
    ends_at: '2023-11-15T18:00:00.000Z',
    is_offline_access_code: true,
    ...
  }
  ```

  ```json cURL theme={null}
  {
    "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-777777777777",
      "device_id": "11111111-1111-1111-1111-444444444444",
      "name": "my hourly-bound offline code",
      "type": "time_bound",
      "starts_at": "2023-11-10T00:00:00.000Z",
      "ends_at": "2023-11-15T18:00:00.000Z",
      "is_offline_access_code": true,
      ...
    },
    "ok": true
  }
  ```

  ```json Python theme={null}
  AccessCode(
    access_code_id='11111111-1111-1111-1111-777777777777',
    device_id='11111111-1111-1111-1111-444444444444',
    type='time_bound',
    starts_at='2023-11-10T00:00:00.000Z',
    ends_at='2023-11-15T18:00:00.000Z',
    name='my hourly-bound offline code',
    is_offline_access_code=True,
    ...
  )
  ```

  ```json Ruby theme={null}
  <Seam::AccessCode:0x00438
    access_code_id="11111111-1111-1111-1111-777777777777"
    device_id="11111111-1111-1111-1111-444444444444"
    name="my hourly-bound offline code"
    type="time_bound"
    starts_at=2023-11-10 00:00:00 UTC
    ends_at=2023-11-15 18:00:00 UTC
    is_offline_access_code: true
    ...
  >
  ```

  ```json PHP theme={null}
  {
    "access_code_id": "11111111-1111-1111-1111-777777777777",
    "device_id": "11111111-1111-1111-1111-444444444444",
    "name": "my hourly-bound offline code",
    "type": "time_bound",
    "starts_at": "2023-11-10T00:00:00.000Z",
    "ends_at": "2023-11-15T18:00:00.000Z",
    "is_offline_access_code": true,
    ...
  }
  ```

  ```json C# theme={null}
  {
    "type": "time_bound",
    "access_code_id": "11111111-1111-1111-1111-777777777777",
    "device_id": "11111111-1111-1111-1111-444444444444",
    "name": "my hourly-bound offline code",
    "starts_at": "2023-11-10T00:00:00Z",
    "ends_at": "2023-11-15T18:00:00Z",
    "is_offline_access_code": true,
    ...
  }
  ```
</CodeGroup>

#### 2. Verify Successful Time-Bound Code Registration

The [lifecycle of a time-bound access code](/low-level-apis/smart-locks/access-codes/lifecycle-of-access-codes) is marked by distinct phases:

1. `Unset`: When initially created on Seam, the offline access code remains in an `unset` state, indicating that it is not yet available for use on the lock due to a configured future activation time.
2. `Setting`: As the scheduled `starts_at` time approaches, Seam initiates the process of readying the code for use on the lock, transitioning the `status` of the offline code to `setting`.
3. `Set`: Upon successful programming, the status updates to `set`, signaling that the code is ready to grant the designated user the ability to unlock the door.

There are two methods to verify that an time-bound offline access code has been registered in the offline access code server that the device manufacturer maintains:

* **Polling**: Continuously query the access code until the `status` is updated. For instructions, see [Polling Method](/low-level-apis/smart-locks/access-codes/creating-access-codes#polling-method).
* **Webhook**: Wait for updates to arrive using webhook requests from the Seam API. For instructions, see [Webhook Events Method](/low-level-apis/smart-locks/access-codes/creating-access-codes#webhook-events-method).

***

### Daily-Bound Offline Access Codes

To [create a daily-bound offline access code](/low-level-apis/smart-locks/access-codes/offline-access-codes#creating-time-bound-offline-access-codes), first issue a creation request. Then, poll or use a webhook to confirm that the code was registered successfully in the igloohome offline access code server.

#### 1. Create a Daily-Bound Access Code

To create a daily-bound offline access code, provide the `device_id` of the lock for which you want to create the code and set `is_offline_access_code` to `true`. Specify the `starts_at` and `ends_at` [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) timestamps to define the active time window for the offline code. For a daily-bound offline access code, you must specify the same time (but not the same date) in the `starts_at` and `ends_at` properties.

Because daily-bound offline access codes require day-level duration granularity, you can also set `max_time_rounding` to `1day` (or `1d`), instead of the default `1hour` (or `1h`). Note that the Seam API returns an error if `max_time_rounding` is `1hour` and the necessary rounding amount exceeds one hour.

You can also assign an optional `name` to the offline access code. For more details, see the [Create Access Code endpoint](/api/access_codes/create).

**Request:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  // Get the device.
  const device = await seam.locks.get({
    device_id: '11111111-1111-1111-1111-444444444444',
  })

  // Confirm that the device supports offline access codes.
  if (device.can_program_offline_access_codes) {
    // Create the daily-bound offline access code.
    await seam.accessCodes.create({
      device_id: device.device_id,
      name: 'my daily-bound offline code',
      starts_at: '2023-11-17T00:00:00-00:00',
      ends_at: '2023-12-18T00:00:00-00:00',
      max_time_rounding: '1d',
      is_offline_access_code: true,
    })
  }
  ```

  ```sh cURL theme={null}
  # 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 offline access codes.
  if  $(jq -r '.device.can_program_offline_access_codes' <<< ${device}); then \
    # Create the daily-bound offline 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 daily-bound offline code\",
        \"starts_at\": \"2023-11-17T00:00:00-00:00\",
        \"ends_at\": \"2023-12-18T00:00:00-00:00\",
        \"max_time_rounding\": \"1d\",
        \"is_offline_access_code\": true
    }";
  fi
  ```

  ```python Python theme={null}
  # Get the device.
  device = seam.locks.get(
    device_id="11111111-1111-1111-1111-444444444444"
  )

  # Confirm that the device supports offline access codes.
  if device.can_program_offline_access_codes:
    # Create the daily-bound offline access code.
    seam.access_codes.create(
      device_id = device.device_id,
      name = "my daily-bound offline code",
      starts_at = "2023-11-17T00:00:00-00:00",
      ends_at = "2023-12-18T00:00:00-00:00",
      max_time_rounding = "1d",
      is_offline_access_code = True
    )
  ```

  ```ruby Ruby theme={null}
  # Get the device.
  device = client.locks.get(device_id: "11111111-1111-1111-1111-444444444444")

  # Confirm that the device supports offline access codes.
  if (device.can_program_offline_access_codes)
    # Create the daily-bound offline access code.
    client.access_codes.create(
      device_id: device.device_id,
      name: "my daily-bound offline code",
      starts_at: "2023-11-17T00:00:00-00:00",
      ends_at: "2023-12-18T00:00:00-00:00",
      max_time_rounding: "1d",
      is_offline_access_code: true
    )
  end
  ```

  ```php PHP theme={null}
  // Get the device.
  $device = $seam->locks->get(device_id: "11111111-1111-1111-1111-444444444444");

  // Confirm that the device supports offline access codes.
  if ($device->can_program_offline_access_codes) {
    // Create the daily-bound offline access code.
    $seam->access_codes->create(
      device_id: $device->device_id,
      name: "my daily-bound offline code",
      starts_at: "2023-11-17T00:00:00Z",
      ends_at: "2023-12-18T00:00:00Z",
      max_time_rounding: "1d",
      is_offline_access_code: true
    );
  }
  ```

  ```csharp C# theme={null}
  // Get the device.
  Device device = seam.Locks.Get(deviceId: "11111111-1111-1111-1111-444444444444");

  // Confirm that the device supports offline access codes.
  if (device.CanProgramOfflineAccessCodes == true) {
    // Create the daily-bound offline access code.
    seam.AccessCodes.Create(
      deviceId: device.DeviceId,
      name: "my daily-bound offline code",
      startsAt: "2023-11-17T00:00:00Z",
      endsAt: "2023-12-18T00:00:00Z",
      maxTimeRounding: "1d",
      isOfflineAccessCode: true
    );
  }
  ```
</CodeGroup>

**Response:**

<CodeGroup>
  ```json JavaScript theme={null}
  {
    access_code_id: '11111111-1111-1111-1111-888888888888',
    device_id: '11111111-1111-1111-1111-444444444444',
    name: 'my daily-bound offline code',
    type: 'time_bound',
    starts_at: '2023-11-17T00:00:00.000Z',
    ends_at: '2023-12-18T00:00:00.000Z',
    is_offline_access_code: true,
    ...
  }
  ```

  ```json cURL theme={null}
  {
    "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-888888888888",
      "device_id": "11111111-1111-1111-1111-444444444444",
      "name": "my daily-bound offline code",
      "type": "time_bound",
      "starts_at": "2023-11-17T00:00:00.000Z",
      "ends_at": "2023-12-18T00:00:00.000Z",
      "is_offline_access_code": true,
      ...
    },
    "ok": true
  }
  ```

  ```json Python theme={null}
  AccessCode(
    access_code_id='11111111-1111-1111-1111-888888888888',
    device_id='11111111-1111-1111-1111-444444444444',
    type='time_bound',
    starts_at='2023-11-17T00:00:00.000Z',
    ends_at='2023-12-18T00:00:00.000Z',
    name='my daily-bound offline code',
    is_offline_access_code=True,
    ...
  )
  ```

  ```json Ruby theme={null}
  <Seam::AccessCode:0x00438
    access_code_id="11111111-1111-1111-1111-888888888888"
    device_id="11111111-1111-1111-1111-444444444444"
    name="my daily-bound offline code"
    type="time_bound"
    starts_at=2023-11-17 00:00:00 UTC
    ends_at=2023-12-18 00:00:00 UTC
    is_offline_access_code: true
    ...
  >
  ```

  ```json PHP theme={null}
  {
    "access_code_id": "11111111-1111-1111-1111-888888888888",
    "device_id": "11111111-1111-1111-1111-444444444444",
    "name": "my daily-bound offline code",
    "type": "time_bound",
    "starts_at": "2023-11-17T00:00:00.000Z",
    "ends_at": "2023-12-18T00:00:00.000Z",
    "is_offline_access_code": true,
    ...
  }
  ```

  ```json C# theme={null}
  {
    "type": "time_bound",
    "access_code_id": "11111111-1111-1111-1111-888888888888",
    "device_id": "11111111-1111-1111-1111-444444444444",
    "name": "my daily-bound offline code",
    "starts_at": "2023-11-17T00:00:00Z",
    "ends_at": "2023-12-18T00:00:00Z",
    "is_offline_access_code": true,
    ...
  }
  ```
</CodeGroup>

#### 2. Verify Successful Time-Bound Code Registration

The [lifecycle of a time-bound access code](/low-level-apis/smart-locks/access-codes/lifecycle-of-access-codes) is marked by distinct phases:

1. `Unset`: When initially created on Seam, the offline access code remains in an `unset` state, indicating that it is not yet available for use on the lock due to a configured future activation time.
2. `Setting`: As the scheduled `starts_at` time approaches, Seam initiates the process of readying the code for use on the lock, transitioning the `status` of the offline code to `setting`.
3. `Set`: Upon successful programming, the status updates to `set`, signaling that the code is ready to grant the designated user the ability to unlock the door.

There are two methods to verify that an time-bound offline access code has been registered in the offline access code server that the device manufacturer maintains:

* **Polling**: Continuously query the access code until the `status` is updated. For instructions, see [Polling Method](/low-level-apis/smart-locks/access-codes/creating-access-codes#polling-method).
* **Webhook**: Wait for updates to arrive using webhook requests from the Seam API. For instructions, see [Webhook Events Method](/low-level-apis/smart-locks/access-codes/creating-access-codes#webhook-events-method).

***

### One-Time-Use Offline Access Codes

igloohome one-time-use offline access codes are valid for 24 hours from the `starts_at` timestamp that you configure. These codes expire after a single use. For detailed instructions, see [Creating One-Time-Use Offline Access Codes](/low-level-apis/smart-locks/access-codes/offline-access-codes#creating-one-time-use-offline-access-codes).


# Get started with igloohome Locks
Source: https://docs.seam.co/device-and-system-integration-guides/igloohome-locks/get-started-with-igloo-locks

Learn how to connect and control your Igloohome locks with the Seam API.

## Overview

Seam provides a universal API to connect and control many brands of locks, including Igloohome. This guide provides a rapid introduction to connecting and controlling your [Igloohome](https://www.seam.co/manufacturers/igloohome) locks using the Seam API. To learn more about other device brands supported by the Seam API, such as Yale, Schlage, and August, head over to our [integration page](https://www.seam.co/supported-devices-and-systems).

## 1 — Install Seam SDK

Seam provides client libraries for many languages, such as JavaScript, Python, Ruby, PHP, and others, as well as a Postman collection and [OpenAPI](https://connect.getseam.com/openapi.json) spec.

* JavaScript / TypeScript ([npm](https://www.npmjs.com/package/seam), [GitHub](https://github.com/seamapi/javascript))
* Python ([pip](https://pypi.org/project/seam/), [GitHub](https://github.com/seamapi/python))
* Ruby Gem ([rubygem](https://rubygems.org/gems/seam), [GitHub](https://github.com/seamapi/ruby))
* PHP ([packagist](https://packagist.org/packages/seamapi/seam), [GitHub](https://github.com/seamapi/php))
* C# ([nuget](https://www.nuget.org/packages/Seam), [GitHub](https://github.com/seamapi/csharp))

<Tabs>
  <Tab title="JavaScript">
    ```bash theme={null}
    npm i seam
    ```
  </Tab>

  <Tab title="Python">
    ```bash theme={null}
    pip install seam
    # For some development environments, use pip3 in this command instead of pip.
    ```
  </Tab>

  <Tab title="Ruby">
    ```bash theme={null}
    bundle add seam
    ```
  </Tab>

  <Tab title="PHP">
    ```bash theme={null}
    composer require seamapi/seam
    ```
  </Tab>

  <Tab title="C#">
    Install using [nuget](https://www.nuget.org/packages/Seam).
  </Tab>
</Tabs>

Once installed, [sign-up for Seam](https://console.seam.co/) to get your API key, and export it as an environment variable:

```
$ export SEAM_API_KEY=seam_test2ZTo_0mEYQW2TvNDCxG5Atpj85Ffw
```

<Info>
  This guide uses a Sandbox Workspace. Only virtual devices can be connected. If
  you need to connect a real Igloohome device, use a non-sandbox workspace and
  API key.
</Info>

## 2 — Link Your Igloohome Account with Seam

To control your Igloohome locks via the Seam API, you must first authorize your Seam workspace against your Igloohome account. To do so, Seam provides[ Connect Webviews](/core-concepts/connect-webviews): pre-built UX flows that walk you through authorizing your application to control your Igloohome devices.

#### Request a Connect Webview

<CodeGroup>
  ```javascript JavaScript theme={null}
  import { Seam } from 'seam'

  const seam = new Seam()

  const { connect_webview: connectWebview } = await seam.connectWebviews.create()

  console.log(connectWebview.login_successful) // false

  // Send the webview URL to your user
  console.log(connectWebview.url)

  ```

  ```python Python theme={null}
  from seam import Seam

  seam = Seam()

  webview = seam.connect_webviews.create()

  assert webview.login_successful is False

  # Send the webview URL to your user
  print(webview.url)
  ```

  ```ruby Ruby theme={null}
  require "seam"

  seam = Seam.new(api_key: 'MY_API_KEY')

  webview = seam.connect_webviews.create()

  puts webview.login_successful # false

  # Send the webview URL to your user

  puts webview.url

  ```

  ```php PHP theme={null}
  use Seam\SeamClient;

  $seam = new SeamClient("YOUR_API_KEY");

  $webview = $seam->connect_webviews->create();

  echo json_encode($webview)
  /*
  {"connect_webview_id":"70c4df9e-1070-441f-92f8-fd6524062cec","workspace_id":"d7418ff3-a476-4f48-9a4b-211d1d21a03d","url":"https:\/\/connect.getseam.com\/connect_webviews\/view?connect_webview_id=70c4df9e-1070-441f-92f8-fd6524062cec&auth_token=9HJbwWKbD5aJLifZcozU9WWZXxropn9Bg","connected_account_id":null,"status":"pending","custom_redirect_url":null,"custom_redirect_failure_url":null,"created_at":"2023-02-09T02:14:06.147745+00:00","error":null}
  */
  ```
</CodeGroup>

#### Authorize Your Workspace

Navigate to the URL returned by the Webview object. Since you are using a sandbox workspace, complete the login flow by entering the Igloohome [sandbox test accounts ](./igloohome-sample-data)credentials below:

* **email:** [jane@example.com](mailto:jane@example.com)
* **password:** 1234

Confirm the Connect Webview was successful by querying its status:

<CodeGroup>
  ```javascript JavaScript theme={null}
  const updatedWebview = await seam.connectWebviews.get(
    connectWebview.connect_webview_id,
  )

  console.log(updatedWebview.login_successful) // true

  ```

  ```python Python theme={null}
  updated_webview = seam.connect_webviews.get(connect_webview_id: webview.connect_webview_id)

  assert updated_webview.login_successful # true
  ```

  ```ruby Ruby theme={null}
  updated_webview = seam.connect_webviews.get(connect_webview_id: webview.connect_webview_id)

  puts updated_webview.login_successful # true

  ```

  ```php PHP theme={null}
  $webview = $seam->connect_webviews->get($webview->id);
  echo json_encode($webview);
  ```
</CodeGroup>

## 3 — Retrieve Igloohome Devices

After an Igloohome account is linked with Seam, you can retrieve devices for this Igloohome account. The Seam API exposes most of the device's properties such as battery level.

<CodeGroup>
  ```javascript JavaScript theme={null}
  const allLocks = await seam.locks.list()

  const someLock = allLocks[0]

  console.log(someLock.properties.online) // true
  console.log(someLock.properties.locked) // true

  console.log(someLock)
  /_
  {
  device_id: '60d0f1b6-26ae-4366-8d1b-d20ad0d6a62e',
  device_type: 'igloohome_lock',
  capabilities_supported: [ 'access_code', 'lock' ],
  properties: {
  locked: false,
  online: true,
  manufacturer: 'igloohome',
  battery_level: 0.86,
  igloohome_metadata: { device_id: '545636388', device_name: 'Office Lock' },
  max_active_codes_supported: 100,
  supported_code_lengths: [ 6 ],
  name: 'Office Lock'
  },
  location: null,
  connected_account_id: '32e92b46-7978-4d48-a3e7-9b04662151b3',
  workspace_id: 'd7418ff3-a476-4f48-9a4b-211d1d21a03d',
  created_at: '2023-02-11T00:46:12.940Z',
  errors: [],
  warnings: []
  }
  _/

  ```

  ```python Python theme={null}
  all_locks = seam.locks.list()

  some_lock = all_locks[0]

  assert some_lock.properties["online"] is True
  assert some_lock.properties["battery_level"] is True

  print(some_lock)
  # Device(device_id='60d0f1b6-26ae-4366-8d1b-d20ad0d6a62e', device_type='igloohome_lock', location=None, properties={'locked': False, 'online': True, 'manufacturer': 'igloohome', 'battery_level': 0.86, 'igloohome_metadata': {'device_id': '545636388', 'device_name': 'Office Lock'}, 'max_active_codes_supported': 100, 'supported_code_lengths': [6], 'name': 'Office Lock'}, capabilities_supported=['access_code', 'lock'], errors=[])
  ```

  ```ruby Ruby theme={null}
  some_lock = seam.locks.list.first

  puts some_lock.properties.online # true
  puts some_lock.properties.locked # true

  puts some_lock

  # <Seam::Device:0x00730

  # device_id="60d0f1b6-26ae-4366-8d1b-d20ad0d6a62e"

  # device_type="igloohome_lock"

  # properties={"locked"=>false, "online"=>true, "manufacturer"=>"igloohome", "battery_level"=>0.86, "igloohome_metadata"=>{"device_id"=>"545636388", "device_name"=>"Office Lock"}, "max_active_codes_supported": 100, "supported_code_lengths"=>[6], "name"=>"Office Lock"}

  # created_at=2023-02-11 00:46:12.94 UTC

  # errors=[]

  # warnings=[]>

  ```

  ```php PHP theme={null}
  use Seam\SeamClient;

  $seam = new SeamClient('YOUR_API_KEY');

  $locks = $seam->locks->list();

  echo json_encode($locks);
  /*
  [{"device_id":"60d0f1b6-26ae-4366-8d1b-d20ad0d6a62e","workspace_id":"d7418ff3-a476-4f48-9a4b-211d1d21a03d","connected_account_id":"32e92b46-7978-4d48-a3e7-9b04662151b3","device_type":"igloohome_lock","properties":{"online":true,"locked":false,"door_open":null,"battery_level":0.86,"name":"Office Lock","manufacturer":"igloohome","august_metadata":null,"schlage_metadata":null,"smartthings_metadata":null},"location":null,"created_at":"2023-02-11T00:46:12.940Z","capabilities_supported":["access_code","lock"],"errors":[]}]
  */
  ```
</CodeGroup>

### 4 — Locking & Unlocking a Door

Next, you can perform the basic action of locking and unlocking a door.

> **`POST`** `/locks/lock_door`
>
> See the [API Reference](/api/locks/lock_door) for details.

## Unlock a door

<mark>`POST`</mark>
`https://connect.getseam.com/locks/unlock_door`

#### Request Body

| Name       | Type   | Description |
| ---------- | ------ | ----------- |
| device\_id | String |             |

<CodeGroup>
  ```javascript JavaScript theme={null}
  // lock the door
  await seam.locks.lockDoor(someLock.device_id)
  const updatedLock = await seam.locks.get(someLock.device_id)
  console.log(updatedLock.properties.locked) // true

  // unlock the door
  await seam.locks.unlockDoor(someLock.device_id)
  updatedLock = await seam.locks.get(someLock.device_id)
  console.log(updatedLock.properties.locked) // false

  ```

  ```python Python theme={null}
  # lock the door
  seam.locks.lock_door(device_id: some_lock.device_id)
  updated_lock = seam.locks.get(device_id: some_lock.device_id)
  assert updated_lock.properties["locked"] is True

  # Now unlock the door
  seam.locks.unlock_door(device_id: some_lock.device_id)
  updated_lock = seam.locks.get(device_id: some_lock.device_id)
  assert updated_lock.properties["locked"] is False
  ```

  ```ruby Ruby theme={null}
  # lock the door
  seam.locks.lock_door(device_id: some_lock.device_id)
  updated_lock = seam.locks.get(device_id: some_lock.device_id)
  puts updated_lock.properties.locked # true

  # unlock the door

  seam.locks.unlock_door(device_id: some_lock.device_id)
  updated_lock = seam.locks.get(device_id: some_lock.device_id)
  puts updated_lock.properties.locked # false

  ```

  ```php PHP theme={null}
  use Seam\SeamClient;

  $seam = new SeamClient('YOUR_API_KEY');

  $some_lock = $seam->locks->list()[0];

  # unlock the door
  $seam->locks->unlock_door($lock->device_id);
  # lock the door
  $seam->locks->lock_door($lock->device_id);
  ```
</CodeGroup>

### 5 — Setting Access Code on Igloohome Lock

Most Igloohome locks come with a keypad built-in to program access codes. These codes can then be entered to unlock a Igloohome lock.

The Seam API makes it easy to program both `ongoing` codes and `timebound` codes on an Igloohome lock. You can find out more about Igloohome lock access code in our [core concept section on access codes.](/low-level-apis/smart-locks/access-codes)

<Info>
  Igloohome pins have to be 4-6 digits long, and for time bound access codes,
  start date can't be on the past.
</Info>

<CodeGroup>
  ```javascript JavaScript theme={null}
  // create an ongoing code
  await seam.accessCodes.create({
    device_id: someLock.device_id,
    code: '123456',
    name: 'Personal Access Code',
  })

  // create a timebound code
  await seam.accessCodes.create({
  device_id: someLock.device_id,
  code: '888888',
  name: 'My Temp Access Code',
  starts_at: '2028-11-12T19:23:42+0000',
  ends_at: '2028-11-13T19:23:42+0000',
  })

  // use a device_id as the "device_id" parameter
  await seam.accessCodes.list({
  device_id: someLock.device_id,
  })

  ```

  ```python Python theme={null}
  # create an ongoing code
  seam.access_codes.create(
    device=some_lock,
    code="492332",
    name="Personal Access Code")

  # create a timebound code
  seam.access_codes.create(
    device=some_lock,
    code="498882",
    name="My Temp Access Code",
    starts_at="2028-08-12T19:23:42+0000",
    ends_at="2028-08-13T19:23:42+0000")

  # you can use a device or a device_id as the "device" parameter
  seam.access_codes.list(device=some_lock)


  ```

  ```ruby Ruby theme={null}
  # create an ongoing code
  seam.access_codes.create(
    device_id: some_lock.device_id, code: '123456', name: 'Personal Access Code'
  )

  # create a timebound code

  seam.access_codes.create(
  device_id: some_lock.device_id,
  code: '888888',
  name: 'My Temp Access Code',
  starts_at: '2028-08-12T19:23:42+0000',
  ends_at: '2028-08-13T19:23:42+0000'
  )

  seam.access_codes.list(device_id: some_lock.device_id)

  ```

  ```php PHP theme={null}
  use Seam\SeamClient;

  $seam = new SeamClient("YOUR_API_KEY");

  $some_lock = $seam->locks->list()[0];
  $seam->access_codes->create(
    device_id: $some_lock->device_id, code: '123456', name: 'Personal Access Code'
  );

  $seam->access_codes->create(
    device_id: $some_lock->device_id,
    name: 'My Temp Access Code',
    code: '888888',
    starts_at: '2028-08-12T19:23:42+0000',
    ends_at: '2028-08-13T19:23:42+0000'
  );

  ```
</CodeGroup>

###

## Next Steps

Now that you've completed this guide, you can try to connect a real Igloohome device. To do so, make sure to switch to a non-sandbox workspace and API key as real devices cannot be connected to sandbox workspaces.

In addition, if you'd like to explore other aspects of Seam, here is a list of helpful resources:

* [Schlage Getting Started Guide](../schlage-locks/get-started-with-schlage-locks)
* [Yale Getting Started Guide](../yale-locks/get-started-with-yale-locks)
* [SmartThings Getting Started Guide](../smartthings-hubs-+-devices/get-started-with-smartthings-hubs-+-smart-locks)
* [Receiving webhook](/developer-tools/webhooks) for [device events](/api/events/list)
* [Core Concepts](/core-concepts/overview)

If you have any questions or want to report an issue, email us at [support@seam.co](mailto:support@seam.co).


# IglooHome Error and Warning Codes
Source: https://docs.seam.co/device-and-system-integration-guides/igloohome-locks/igloohome-error-and-warning-codes

This guide covers error and warning codes specific to IglooHome devices integrated through Seam.

### Overview

IglooHome devices can generate errors and warnings related to device connectivity, bridge status, and access code management. Understanding these codes helps you quickly diagnose and resolve issues.

<Info>
  **Note:** Error and warning codes may change over time as we improve our error
  handling. Use these codes as a reference for troubleshooting, but avoid
  building logic that depends on specific code keys remaining static.
</Info>

### Device Errors

Device errors indicate critical issues that prevent normal operation.

| Error Code            | Description                             | Triggered When                                   | Resolution                                                                                       |
| --------------------- | --------------------------------------- | ------------------------------------------------ | ------------------------------------------------------------------------------------------------ |
| `device_disconnected` | Device is offline and cannot be reached | Device goes offline (not an offline-only device) | Reconnect the device through the Igloohome app. Check device batteries and network connectivity. |
| `hub_disconnected`    | The Igloohome Bridge is offline         | Bridge cannot communicate with the cloud         | Check bridge power and network connection. Restart the bridge if needed.                         |

### Device Warnings

Device warnings indicate potential issues or configuration limitations but don't prevent all functionality.

| Warning Code                              | Description                                            | Triggered When                                            | Impact                                                                                                 |
| ----------------------------------------- | ------------------------------------------------------ | --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
| `accessory_keypad_setup_required`         | Accessory keypad is not linked to the Igloohome Bridge | Device has both keypad and bridge, but they're not linked | Online access code programming will fail. Link the keypad to the bridge in the Igloohome app.          |
| `hub_required_for_addtional_capabilities` | Device is operating without an Igloohome Bridge        | Device has no bridge configured                           | Only offline access codes are available. Add a bridge to enable remote unlock and online access codes. |
| `device_has_flaky_connection`             | Device has an unstable internet connection             | Frequent network disconnections detected                  | May experience intermittent issues with remote operations.                                             |

<Info>
  **Note:** The legacy warning `functional_offline_device` is being migrated to
  `hub_required_for_addtional_capabilities`.
</Info>

### Access Code Errors

Access code errors prevent the creation or management of access codes.

| Error Code                               | Description                 | Triggered When                                                   | Resolution                                                                                                                |
| ---------------------------------------- | --------------------------- | ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| `igloohome_bridge_too_many_pending_jobs` | Bridge queue is at capacity | Bridge has 20 or more pending jobs                               | Seam will continue retrying automatically. If the issue persists, contact support. Jobs will process as the queue clears. |
| `igloohome_bridge_offline`               | Bridge cannot be contacted  | Bridge reports that it's offline or lock is not linked to bridge | Verify the bridge is online and the lock i                                                                                |


# Sandbox igloohome Locks
Source: https://docs.seam.co/device-and-system-integration-guides/igloohome-locks/igloohome-sample-data

Add virtual igloohome locks to your Seam sandbox workspace using these sample credentials to test your integration without real hardware.

Use the following set of credentials to add virtual [igloohome locks](/device-and-system-integration-guides/igloohome-locks) to your Seam [sandbox workspace](/core-concepts/workspaces#sandbox-workspaces):

| Email Address                                                                              | Password |
| ------------------------------------------------------------------------------------------ | -------- |
| [jane@example.com](mailto:jane@example.com) or any email address in the example.com domain | 1234     |


# igloohome Setup Guide
Source: https://docs.seam.co/device-and-system-integration-guides/igloohome-locks/igloohome-setup-guide

Connect your igloohome locks to Seam.

This guide walks you through connecting your igloohome locks to Seam. Your locks must already be set up and working in the igloohome app before proceeding.

## 1. Create an igloohome account

If you don't already have one, download the igloohome mobile app and create an account. For more information, see "Download App & Sign in" in the [igloohome app quick start guide](https://support.igloohome.co/support/solutions/articles/35000183120-igloohome-app-quick-start-guide).

## 2. Add your igloohome devices

In the igloohome mobile app, add your igloohome locks. For more information, see "Pair your lock" in the [igloohome app quick start guide](https://support.igloohome.co/support/solutions/articles/35000183120-igloohome-app-quick-start-guide).

## 3. Set up the igloohome Bridge (optional)

To configure your igloohome smart locks remotely, trigger lock and unlock actions, and use custom access codes, install the [igloohome Wi-Fi Bridge](https://www.igloohome.co/en-US/products/bridge) and pair your locks to the bridge.

<Info>
  The igloohome Bridge is not required for offline access code (algoPIN)
  provisioning. It is only needed for remote lock/unlock and custom access
  codes.
</Info>

## 4. Connect igloohome to Seam

Use the login credentials for your igloohome account to log in through the [Seam Connect Webview](/core-concepts/connect-webviews) and authorize Seam to access your devices.

## 5. Verify the connection

After completing the Connect Webview, confirm that your igloohome locks appear in your Seam workspace and show an **online** status.

***

## Troubleshooting

If your devices don't appear after connecting:

* Confirm that your igloohome locks are paired in the igloohome mobile app.
* Verify that you logged in with the same igloohome account that owns the locks.
* Wait a few minutes for the initial sync to complete, then refresh your device list.

If your devices show as offline:

* Verify that the igloohome Bridge is powered on and connected to Wi-Fi.
* Check that each lock is within range of the bridge and paired to it.
* Note that locks without a bridge will only support offline access codes (algoPIN).


# igloohome Locks
Source: https://docs.seam.co/device-and-system-integration-guides/igloohome-locks/index

Guide for using igloohome locks with Seam

<img alt="igloohome logo" />

## Overview

igloohome produces various types of smart locks for the residential, rental property, and small business markets. These locks include mortise, deadbolt, rim, glass door, keybox, and padlock style locks.

Seam integrates with igloohome locks through the [igloohome Wi-Fi Bridge](https://www.igloohome.co/en-US/products/bridge) to provide lock, unlock, and customizable access code provisioning actions. You can link up to five igloohome locks with a single igloohome Bridge.

In addition, the Seam integration supports the generation of [offline access codes](./creating-igloohome-offline-access-codes) (that is, igloohome [algoPIN™](https://www.igloohome.co/en-US/how-it-works) codes) for igloohome locks without the need for the igloohome Bridge.

***

## Supported Devices

<DeviceList />

This integration supports a series of igloohome devices for lock, unlock, and customizable access code provisioning actions. In addition, this integration supports a wider set of igloohome devices for offline access code (algoPIN) provisioning.

For detailed information about the igloohome devices that Seam supports, see our [igloohome Supported Devices page](https://www.seam.co/manufacturers/igloohome).

### igloohome Bridge Support

This integration supports lock, unlock, and customizable access code provisioning actions for a subset of igloohome smart locks, when combined with the [igloohome Bridge](https://www.igloohome.co/en-US/products/bridge). For a list of compatible igloohome smart locks, see the **Bridge Compatibility** area on the [igloohome Bridge ](https://www.igloohome.co/en-US/products/bridge)page.

Each igloohome Bridge supports up to five compatible igloohome locks.

***

## Supported Features

We support the following features:

* [Triggering web lock and unlock actions](/low-level-apis/smart-locks/lock-and-unlock) for igloohome smart locks connected through the igloohome Bridge
* [Programming online access codes](/low-level-apis/smart-locks/access-codes)
* [Programming offline access codes](/low-level-apis/smart-locks/access-codes/offline-access-codes)

<Info>
  We support customizable access codes for igloohome locks connected through the
  igloohome Bridge. We support offline algoPIN codes for all igloohome locks,
  without the need for a bridge.
</Info>

***

### Device Provider Key

Seam identifies these devices with the `igloohome` device provider key. By default, a [Connect Webview](/core-concepts/connect-webviews) displays all of the stable providers that Seam supports, so your users can connect their igloohome devices without you specifying a provider list. To narrow what a Connect Webview displays, see [Customize the Brands to Display in Your Connect Webviews](/core-concepts/connect-webviews/customizing-connect-webviews#customize-the-brands-to-display-in-your-connect-webviews).

***

## Setup Instructions

For instructions on connecting igloohome locks to Seam, see the [igloohome Setup Guide](./igloohome-setup-guide).

***

## Brand-Specific Events

Seam supports the following events and event property values for igloohome devices:

### igloohome Auto-Relock

igloohome devices have an auto-relock feature that automatically locks the device after a configurable period of time, for example, 30 seconds. The Seam API reports these auto-relock occurrences by emitting a [`lock.locked` event](/api/locks/events#lock-locked) with `automatic` as the value for the `method` property.

### igloohome Access Denied Event

Each time an igloohome device detects an invalid attempt of entry, Seam emits a [`lock.access_denied` event](/api/locks/events#lock-access_denied). Invalid entry attempts include entering the wrong PIN, exceeding the PIN length, and using an invalid key card. The igloohome lock also flashes red to indicate an invalid attempt. If too many invalid attempts occur, igloohome locks produce a Keypad Security Lockout alarm, accompanied by light and sound indicators. For more information, see the igloohome support articles on [keypad security](https://support.igloohome.co/support/solutions/articles/35000169627-keypad-security-lockout-activated-and-deactivated) and [incorrect PINs](https://support.igloohome.co/support/solutions/articles/35000169625-incorrect-pin).

***

## Where to Order

Order igloohome devices directly from the igloohome website.

<table>
  <thead>
    <tr>
      <th />

      <th />

      <th />

      <th />

      <th />
    </tr>
  </thead>

  <tbody>
    <tr>
      <td />

      <td>
        <strong>igloohome</strong>
      </td>

      <td />

      <td>
        <a href="https://store-us.igloohome.co/">
          [https://store-us.igloohome.co/](https://store-us.igloohome.co/)
        </a>
      </td>

      <td>
        <a href="/images/igloohome-logo.png">igloohome-logo.png</a>
      </td>
    </tr>
  </tbody>
</table>

***


# Brand Guides
Source: https://docs.seam.co/device-and-system-integration-guides/index

Learn about all the manufacturers, devices, and systems that you can control with the Seam API, including how to set up your connections and any manufacturer-specific requirements or restrictions.

Seam enables you to control a wide variety of devices and systems, from different manufacturers, using the universal Seam API. This section provides a set of device and system integration guides that show you which devices Seam supports from each manufacturer, explain how to set up these devices and systems, and provide any manufacturer-specific requirements or restrictions.

Each brand guide includes sandbox credentials that you can use to connect virtual devices in a [sandbox workspace](/core-concepts/workspaces#sandbox-workspaces), so you can test your integration without owning physical devices. For the shared login that works across most manufacturers, see [Test Accounts](/developer-tools/test-accounts).

To find the integration guide for each of your devices or systems, see the following categories:

* [Smart locks](#smart-locks)
* [Access control systems](#access-control-systems)
* [Thermostats](#thermostats)
* [Cameras](#cameras)
* [Noise sensors](#noise-sensors)

***

## Smart Locks

<CardGroup>
  <Card title="2N Intercom Systems" href="/device-and-system-integration-guides/2n-intercom-systems" />

  <Card title="33 Lock Devices" href="/device-and-system-integration-guides/33-lock-devices" />

  <Card title="4SUITES Locks" href="/device-and-system-integration-guides/4suites-locks" />

  <Card title="Akiles Locks" href="/device-and-system-integration-guides/akiles-locks" />

  <Card title="August Locks" href="/device-and-system-integration-guides/august-locks" />

  <Card title="dormakaba Oracode Locks" href="/device-and-system-integration-guides/dormakaba-oracode-locks" />

  <Card title="Dusaw Locks" href="/device-and-system-integration-guides/dusaw-locks" />

  <Card title="iglooHome Locks" href="/device-and-system-integration-guides/igloohome-locks" />

  <Card title="KeyInCode Locks" href="/device-and-system-integration-guides/keyincode-locks" />

  <Card title="Kwikset Locks" href="/device-and-system-integration-guides/kwikset-locks" />

  <Card title="Lockly Locks" href="/device-and-system-integration-guides/lockly-locks" />

  <Card title="Nuki Locks" href="/device-and-system-integration-guides/nuki-locks" />

  <Card title="Salto KS Locks" href="/device-and-system-integration-guides/salto-locks" />

  <Card title="Schlage Locks" href="/device-and-system-integration-guides/schlage-locks" />

  <Card title="Sifely Locks" href="/device-and-system-integration-guides/sifely-locks" />

  <Card title="SmartThings Hubs + Smart Locks" href="/device-and-system-integration-guides/smartthings-hubs-+-devices" />

  <Card title="Tedee Locks" href="/device-and-system-integration-guides/tedee-locks" />

  <Card title="TTLock Locks" href="/device-and-system-integration-guides/ttlock-locks" />

  <Card title="Wyze Locks" href="/device-and-system-integration-guides/wyze-locks" />

  <Card title="Yale Locks" href="/device-and-system-integration-guides/yale-locks" />
</CardGroup>

***

## Access Control Systems

<CardGroup>
  <Card title="ASSA ABLOY Visionline Access Control System" href="/device-and-system-integration-guides/assa-abloy-visionline-access-control-system" />

  <Card title="ASSA ABLOY Vostio Access Control System" href="/device-and-system-integration-guides/assa-abloy-vostio-access-control-system" />

  <Card title="Avigilon Alta Access System" href="/device-and-system-integration-guides/avigilon-alta-access-system" />

  <Card title="Brivo Access" href="/device-and-system-integration-guides/brivo-access" />

  <Card title="Latch Access Control System" href="/device-and-system-integration-guides/latch-access-control-system" />

  <Card title="PTI Storlogix Cloud" href="/device-and-system-integration-guides/pti-storlogix-cloud" />

  <Card title="Salto KS Access Control System" href="/device-and-system-integration-guides/salto-ks-access-control-system" />

  <Card title="Salto ProAccess Space Access System" href="/device-and-system-integration-guides/salto-proaccess-space-access-system" />
</CardGroup>

***

## Thermostats

<CardGroup>
  <Card title="ecobee Thermostats" href="/device-and-system-integration-guides/ecobee-thermostats" />

  <Card title="First Alert Thermostats" href="/device-and-system-integration-guides/first-alert-thermostats" />

  <Card title="Google Nest Thermostats" href="/device-and-system-integration-guides/google-nest-thermostats" />

  <Card title="Honeywell Resideo Thermostats" href="/device-and-system-integration-guides/honeywell-thermostats" />

  <Card title="Sensi Thermostats" href="/device-and-system-integration-guides/sensi-thermostats" />

  <Card title="SmartThings Hubs + Thermostats" href="/device-and-system-integration-guides/smartthings-hubs-+-devices" />
</CardGroup>

***

## Cameras

<CardGroup>
  <Card title="Ring Cameras" href="/device-and-system-integration-guides/ring-cameras" />
</CardGroup>

***

## Noise sensors

<CardGroup>
  <Card title="Minut Sensors" href="/device-and-system-integration-guides/minut-sensors" />

  <Card title="NoiseAware Sensors" href="/device-and-system-integration-guides/noiseaware-sensors" />
</CardGroup>

***

## Relays

<CardGroup>
  <Card title="ControlByWeb Relays" href="/device-and-system-integration-guides/controlbyweb-relays" />
</CardGroup>


# Get Started with KeyInCode Locks
Source: https://docs.seam.co/device-and-system-integration-guides/keyincode-locks/get-started-with-keyincode-locks

Learn how to connect and control your KeyInCode lock with the Seam API.

## Overview

Seam provides a universal API to connect and control many brands of smart locks. This guide provides a rapid introduction to connecting and controlling your [KeyInCode](https://www.seam.co/manufacturers/keyincode) lock using the Seam API.

To learn more about other smart lock brands supported by Seam, head over to our [integration page](https://www.seam.co/supported-devices-and-systems).

***

## 1 — Install Seam SDK

Seam provides client libraries for many languages, such as JavaScript, Python, Ruby, PHP, and others, as well as a Postman collection and [OpenAPI](https://connect.getseam.com/openapi.json) spec.

* JavaScript / TypeScript ([npm](https://www.npmjs.com/package/seam), [GitHub](https://github.com/seamapi/javascript))
* Python ([pip](https://pypi.org/project/seam/), [GitHub](https://github.com/seamapi/python))
* Ruby Gem ([rubygem](https://rubygems.org/gems/seam), [GitHub](https://github.com/seamapi/ruby))
* PHP ([packagist](https://packagist.org/packages/seamapi/seam), [GitHub](https://github.com/seamapi/php))
* C# ([nuget](https://www.nuget.org/packages/Seam), [GitHub](https://github.com/seamapi/csharp))
* Java ([Maven](https://central.sonatype.com/artifact/co.seam/java), [GitHub](https://github.com/seamapi/java))

<CodeGroup>
  ```bash JavaScript theme={null}
  npm i seam
  ```

  ```bash Python theme={null}
  pip install seam
  # For some development environments, use pip3 in this command instead of pip.
  ```

  ```bash Ruby theme={null}
  bundle add seam
  ```

  ```bash PHP theme={null}
  composer require seamapi/seam
  ```

  ```bash C# theme={null}
  Install using nuget: https://www.nuget.org/packages/Seam
  ```

  ```bash Java theme={null}
  // Add to your pom.xml or build.gradle — see Maven Central for details.
  ```

  ```bash cURL (bash) theme={null}
  # cURL is already installed on most systems. No additional installation needed.
  # Export your API key as an environment variable:
  export SEAM_API_KEY=seam_test2ZTo_0mEYQW2TvNDCxG5Atpj85Ffw
  ```
</CodeGroup>

Once installed, [sign up for Seam](https://console.seam.co/) to get your API key, and export it as an environment variable:

```bash theme={null}
export SEAM_API_KEY=seam_test2ZTo_0mEYQW2TvNDCxG5Atpj85Ffw
```

<Info>
  This guide uses a Sandbox Workspace. Only virtual devices can be connected. If
  you need to connect a real KeyInCode lock, use a non-sandbox workspace and API
  key.
</Info>

***

## 2 — Link KeyInCode Account with Seam

To control your KeyInCode lock via the Seam API, you must first authorize your Seam workspace against your KeyInCode account. To do so, Seam provides [Connect Webviews](/core-concepts/connect-webviews): pre-built UX flows that walk you through authorizing your application to control your KeyInCode lock.

#### Request a Connect Webview

<CodeGroup>
  ```javascript JavaScript theme={null}
  import { Seam } from "seam";

  const seam = new Seam();

  const connectWebview = await seam.connectWebviews.create();

  console.log(connectWebview.login_successful); // false

  // Send the webview URL to your user
  console.log(connectWebview.url);
  ```

  ```python Python theme={null}
  from seam import Seam

  seam = Seam()

  webview = seam.connect_webviews.create()

  assert webview.login_successful is False

  # Send the webview URL to your user
  print(webview.url)
  ```

  ```ruby Ruby theme={null}
  require "seam"

  seam = Seam.new(api_key: "MY_API_KEY")

  webview = seam.connect_webviews.create()

  puts webview.login_successful # false

  # Send the webview URL to your user
  puts webview.url
  ```

  ```php PHP theme={null}
  <?php
  use Seam\SeamClient;

  $seam = new SeamClient("YOUR_API_KEY");

  $webview = $seam->connect_webviews->create();

  echo $webview->login_successful; // false

  // Send the webview URL to your user
  echo $webview->url;
  ```

  ```csharp C# theme={null}
  using Seam.Client;

  var seam = new SeamClient(apiToken: "YOUR_API_KEY");

  var webview = seam.ConnectWebviews.Create();

  Console.WriteLine(webview.LoginSuccessful); // false

  // Send the webview URL to your user
  Console.WriteLine(webview.Url);
  ```

  ```java Java theme={null}
  import co.seam.Seam;
  import co.seam.api.types.ConnectWebview;

  Seam seam = Seam.builder().apiKey("YOUR_API_KEY").build();

  ConnectWebview webview = seam.connectWebviews().create(
    ConnectWebviewsCreateRequest.builder()
      .build()
  );

  System.out.println(webview.getLoginSuccessful()); // false

  // Send the webview URL to your user
  System.out.println(webview.getUrl());
  ```

  ```bash cURL (bash) theme={null}
  curl -X 'POST' \
    'https://connect.getseam.com/connect_webviews/create' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d '{}'
  ```
</CodeGroup>

#### Authorize Your Workspace

Navigate to the URL returned by the Webview object. Since you are using a sandbox workspace, complete the login flow by entering the KeyInCode [sandbox test account](/device-and-system-integration-guides/keyincode-locks/sandbox-keyincode-locks) credentials below:

* **email:** [jane@example.com](mailto:jane@example.com)
* **password:** 1234

Confirm the Connect Webview was successful by querying its status:

<CodeGroup>
  ```javascript JavaScript theme={null}
  const updatedWebview = await seam.connectWebviews.get(
    connectWebview.connect_webview_id
  );

  console.log(updatedWebview.login_successful); // true
  ```

  ```python Python theme={null}
  updated_webview = seam.connect_webviews.get(
      connect_webview_id=webview.connect_webview_id
  )

  assert updated_webview.login_successful  # true
  ```

  ```ruby Ruby theme={null}
  updated_webview = seam.connect_webviews.get(
    connect_webview_id: webview.connect_webview_id
  )

  puts updated_webview.login_successful # true
  ```

  ```php PHP theme={null}
  <?php
  $updated_webview = $seam->connect_webviews->get(
    connect_webview_id: $webview->connect_webview_id
  );

  echo $updated_webview->login_successful; // true
  ```

  ```csharp C# theme={null}
  var updatedWebview = seam.ConnectWebviews.Get(
    connectWebviewId: webview.ConnectWebviewId
  );

  Console.WriteLine(updatedWebview.LoginSuccessful); // true
  ```

  ```java Java theme={null}
  ConnectWebview updatedWebview = seam.connectWebviews().get(
    ConnectWebviewsGetRequest.builder()
      .connectWebviewId(webview.getConnectWebviewId())
      .build()
  );

  System.out.println(updatedWebview.getLoginSuccessful()); // true
  ```

  ```bash cURL (bash) theme={null}
  curl -X 'POST' \
    'https://connect.getseam.com/connect_webviews/get' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d "{
      \"connect_webview_id\": \"${CONNECT_WEBVIEW_ID}\"
    }"
  ```
</CodeGroup>

***

## 3 — Retrieve KeyInCode Lock Devices

After a KeyInCode account is linked with Seam, you can retrieve devices for this KeyInCode account. The Seam API exposes most of the device's properties such as battery level or door lock status.

<CodeGroup>
  ```javascript JavaScript theme={null}
  const allLocks = await seam.locks.list();

  const someLock = allLocks[0];

  console.log(someLock.properties.online); // true
  console.log(someLock.properties.locked); // true

  console.log(someLock);
  /*
  {
    device_id: '...',
    device_type: 'korelock_lock',
    capabilities_supported: ['access_code', 'lock'],
    properties: {
      locked: true,
      online: true,
      manufacturer: 'korelock',
      name: 'Front Door Lock'
    },
    ...
  }
  */
  ```

  ```python Python theme={null}
  all_locks = seam.locks.list()

  some_lock = all_locks[0]

  assert some_lock.properties["online"] is True
  assert some_lock.properties["locked"] is True

  print(some_lock)
  # Device(
  #   device_id='...',
  #   device_type='korelock_lock',
  #   properties={
  #     'locked': True,
  #     'online': True,
  #     'manufacturer': 'korelock',
  #     'name': 'Front Door Lock'
  #   },
  #   capabilities_supported=['access_code', 'lock']
  # )
  ```

  ```ruby Ruby theme={null}
  some_lock = seam.locks.list.first

  puts some_lock.properties.online # true
  puts some_lock.properties.locked # true

  puts some_lock
  ```

  ```php PHP theme={null}
  <?php
  $locks = $seam->locks->list();

  $some_lock = $locks[0];

  echo $some_lock->properties->online; // true
  echo $some_lock->properties->locked; // true
  ```

  ```csharp C# theme={null}
  var locks = seam.Locks.List();

  var someLock = locks[0];

  Console.WriteLine(someLock.Properties.Online); // true
  Console.WriteLine(someLock.Properties.Locked); // true
  ```

  ```java Java theme={null}
  var locks = seam.locks().list();

  var someLock = locks.get(0);

  System.out.println(someLock.getProperties().getOnline()); // true
  System.out.println(someLock.getProperties().getLocked()); // true
  ```

  ```bash cURL (bash) theme={null}
  curl -X 'POST' \
    'https://connect.getseam.com/locks/list' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d '{}'
  ```
</CodeGroup>

***

## 4 — Locking & Unlocking a Door

You can perform the basic actions of locking and unlocking a KeyInCode lock.

<CodeGroup>
  ```javascript JavaScript theme={null}
  // lock the door
  await seam.locks.lockDoor(someLock.device_id);
  const updatedLock = await seam.locks.get(someLock.device_id);
  console.log(updatedLock.properties.locked); // true

  // unlock the door
  await seam.locks.unlockDoor(someLock.device_id);
  const unlockedLock = await seam.locks.get(someLock.device_id);
  console.log(unlockedLock.properties.locked); // false
  ```

  ```python Python theme={null}
  # lock the door
  seam.locks.lock_door(device_id=some_lock.device_id)
  updated_lock = seam.locks.get(device_id=some_lock.device_id)
  assert updated_lock.properties["locked"] is True

  # unlock the door
  seam.locks.unlock_door(device_id=some_lock.device_id)
  updated_lock = seam.locks.get(device_id=some_lock.device_id)
  assert updated_lock.properties["locked"] is False
  ```

  ```ruby Ruby theme={null}
  # lock the door
  seam.locks.lock_door(device_id: some_lock.device_id)
  updated_lock = seam.locks.get(device_id: some_lock.device_id)
  puts updated_lock.properties.locked # true

  # unlock the door
  seam.locks.unlock_door(device_id: some_lock.device_id)
  updated_lock = seam.locks.get(device_id: some_lock.device_id)
  puts updated_lock.properties.locked # false
  ```

  ```php PHP theme={null}
  <?php
  // lock the door
  $seam->locks->lock_door(device_id: $some_lock->device_id);
  $updated_lock = $seam->locks->get(device_id: $some_lock->device_id);
  echo $updated_lock->properties->locked; // true

  // unlock the door
  $seam->locks->unlock_door(device_id: $some_lock->device_id);
  $updated_lock = $seam->locks->get(device_id: $some_lock->device_id);
  echo $updated_lock->properties->locked; // false
  ```

  ```csharp C# theme={null}
  // lock the door
  seam.Locks.LockDoor(deviceId: someLock.DeviceId);
  var updatedLock = seam.Locks.Get(deviceId: someLock.DeviceId);
  Console.WriteLine(updatedLock.Properties.Locked); // true

  // unlock the door
  seam.Locks.UnlockDoor(deviceId: someLock.DeviceId);
  updatedLock = seam.Locks.Get(deviceId: someLock.DeviceId);
  Console.WriteLine(updatedLock.Properties.Locked); // false
  ```

  ```java Java theme={null}
  // lock the door
  seam.locks().lockDoor(LocksLockDoorRequest.builder()
      .deviceId(someLock.getDeviceId())
      .build());
  var updatedLock = seam.locks().get(LocksGetRequest.builder()
      .deviceId(someLock.getDeviceId())
      .build());
  System.out.println(updatedLock.getProperties().getLocked()); // true

  // unlock the door
  seam.locks().unlockDoor(LocksUnlockDoorRequest.builder()
      .deviceId(someLock.getDeviceId())
      .build());
  updatedLock = seam.locks().get(LocksGetRequest.builder()
      .deviceId(someLock.getDeviceId())
      .build());
  System.out.println(updatedLock.getProperties().getLocked()); // false
  ```

  ```bash cURL (bash) theme={null}
  # lock the door
  curl -X 'POST' \
    'https://connect.getseam.com/locks/lock_door' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d "{\"device_id\": \"${DEVICE_ID}\"}"

  # unlock the door
  curl -X 'POST' \
    'https://connect.getseam.com/locks/unlock_door' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d "{\"device_id\": \"${DEVICE_ID}\"}"
  ```
</CodeGroup>

***

## 5 — Setting Access Codes on a KeyInCode Lock

KeyInCode locks with a keypad support access code programming. The Seam API makes it easy to program both `ongoing` codes and `timebound` codes on a KeyInCode lock.

You can find out more about access codes in our [guide on access codes](/low-level-apis/smart-locks/access-codes).

<CodeGroup>
  ```javascript JavaScript theme={null}
  // create an ongoing code
  await seam.accessCodes.create({
    device_id: someLock.device_id,
    code: "123456",
    name: "Personal Access Code",
  });

  // create a timebound code
  await seam.accessCodes.create({
    device_id: someLock.device_id,
    code: "888888",
    name: "Guest Access Code",
    starts_at: "2028-11-12T19:00:00+0000",
    ends_at: "2028-11-13T12:00:00+0000",
  });

  // list all access codes on the device
  const accessCodes = await seam.accessCodes.list({
    device_id: someLock.device_id,
  });

  console.log(accessCodes);
  /*
  [
    {
      code: '123456',
      type: 'ongoing',
      status: 'setting',
      access_code_id: '...',
      name: 'Personal Access Code'
    },
    {
      code: '888888',
      type: 'timebound',
      status: 'setting',
      access_code_id: '...',
      name: 'Guest Access Code',
      starts_at: '2028-11-12T19:00:00.000Z',
      ends_at: '2028-11-13T12:00:00.000Z'
    }
  ]
  */
  ```

  ```python Python theme={null}
  # create an ongoing code
  seam.access_codes.create(
      device_id=some_lock.device_id,
      code="123456",
      name="Personal Access Code"
  )

  # create a timebound code
  seam.access_codes.create(
      device_id=some_lock.device_id,
      code="888888",
      name="Guest Access Code",
      starts_at="2028-11-12T19:00:00+0000",
      ends_at="2028-11-13T12:00:00+0000"
  )

  # list all access codes on the device
  access_codes = seam.access_codes.list(device_id=some_lock.device_id)

  print(access_codes)
  ```

  ```ruby Ruby theme={null}
  # create an ongoing code
  seam.access_codes.create(
    device_id: some_lock.device_id,
    code: "123456",
    name: "Personal Access Code"
  )

  # create a timebound code
  seam.access_codes.create(
    device_id: some_lock.device_id,
    code: "888888",
    name: "Guest Access Code",
    starts_at: "2028-11-12T19:00:00+0000",
    ends_at: "2028-11-13T12:00:00+0000"
  )

  # list all access codes on the device
  access_codes = seam.access_codes.list(device_id: some_lock.device_id)

  puts access_codes
  ```

  ```php PHP theme={null}
  <?php
  // create an ongoing code
  $seam->access_codes->create(
    device_id: $some_lock->device_id,
    code: "123456",
    name: "Personal Access Code"
  );

  // create a timebound code
  $seam->access_codes->create(
    device_id: $some_lock->device_id,
    code: "888888",
    name: "Guest Access Code",
    starts_at: "2028-11-12T19:00:00+0000",
    ends_at: "2028-11-13T12:00:00+0000"
  );

  // list all access codes on the device
  $access_codes = $seam->access_codes->list(
    device_id: $some_lock->device_id
  );

  print_r($access_codes);
  ```

  ```csharp C# theme={null}
  // create an ongoing code
  seam.AccessCodes.Create(
    deviceId: someLock.DeviceId,
    code: "123456",
    name: "Personal Access Code"
  );

  // create a timebound code
  seam.AccessCodes.Create(
    deviceId: someLock.DeviceId,
    code: "888888",
    name: "Guest Access Code",
    startsAt: "2028-11-12T19:00:00+0000",
    endsAt: "2028-11-13T12:00:00+0000"
  );

  // list all access codes on the device
  var accessCodes = seam.AccessCodes.List(
    deviceId: someLock.DeviceId
  );

  foreach (var code in accessCodes)
  {
    Console.WriteLine(code.Code);
  }
  ```

  ```java Java theme={null}
  // create an ongoing code
  seam.accessCodes().create(AccessCodesCreateRequest.builder()
      .deviceId(someLock.getDeviceId())
      .code("123456")
      .name("Personal Access Code")
      .build());

  // create a timebound code
  seam.accessCodes().create(AccessCodesCreateRequest.builder()
      .deviceId(someLock.getDeviceId())
      .code("888888")
      .name("Guest Access Code")
      .startsAt("2028-11-12T19:00:00+0000")
      .endsAt("2028-11-13T12:00:00+0000")
      .build());

  // list all access codes on the device
  var accessCodes = seam.accessCodes().list(AccessCodesListRequest.builder()
      .deviceId(someLock.getDeviceId())
      .build());

  System.out.println(accessCodes);
  ```

  ```bash cURL (bash) theme={null}
  # create an ongoing code
  curl -X 'POST' \
    'https://connect.getseam.com/access_codes/create' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d "{
      \"device_id\": \"${DEVICE_ID}\",
      \"code\": \"123456\",
      \"name\": \"Personal Access Code\"
    }"

  # create a timebound code
  curl -X 'POST' \
    'https://connect.getseam.com/access_codes/create' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d "{
      \"device_id\": \"${DEVICE_ID}\",
      \"code\": \"888888\",
      \"name\": \"Guest Access Code\",
      \"starts_at\": \"2028-11-12T19:00:00+0000\",
      \"ends_at\": \"2028-11-13T12:00:00+0000\"
    }"

  # list all access codes on the device
  curl -X 'POST' \
    'https://connect.getseam.com/access_codes/list' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d "{\"device_id\": \"${DEVICE_ID}\"}"
  ```
</CodeGroup>

***

## Next Steps

Now that you've completed this guide, you can try to connect a real KeyInCode device. To do so, make sure to switch to a non-sandbox workspace and API key as real devices cannot be connected to sandbox workspaces.

In addition, if you'd like to explore other aspects of Seam, here is a list of helpful resources:

* [Receiving webhooks](/developer-tools/webhooks) for [device events](/api/events/list)
* [Core Concepts](/core-concepts/overview)
* [Access Codes Guide](/low-level-apis/smart-locks/access-codes)

If you have any questions or want to report an issue, email us at [support@seam.co](mailto:support@seam.co).


# KeyInCode Locks
Source: https://docs.seam.co/device-and-system-integration-guides/keyincode-locks/index

Guide for using KeyInCode locks with Seam

## Overview

KeyInCode manufactures smart locks with built-in keypads designed for residential and commercial applications. Their locks provide keypad-based access management with cloud connectivity for remote control and access code programming.

Seam integrates with KeyInCode locks to provide remote lock and unlock actions, as well as online access code programming through the Seam API.

***

## Supported Devices

<DeviceList />

This integration supports KeyInCode smart locks.

For detailed information about the KeyInCode devices that Seam supports, see our [KeyInCode Supported Devices page](https://www.seam.co/manufacturers/keyincode).

***

## Supported Features

We support the following features:

* [Triggering web lock and unlock actions](/low-level-apis/smart-locks/lock-and-unlock)
* [Programming online access codes](/low-level-apis/smart-locks/access-codes) on locks that have a keypad

***

## Device Provider Key

Seam identifies these devices with the `korelock` device provider key. By default, a [Connect Webview](/core-concepts/connect-webviews) displays all of the stable providers that Seam supports, so your users can connect their KeyInCode devices without you specifying a provider list. To narrow what a Connect Webview displays, see [Customize the Brands to Display in Your Connect Webviews](/core-concepts/connect-webviews/customizing-connect-webviews#customize-the-brands-to-display-in-your-connect-webviews).

***

## Setup Instructions

For step-by-step instructions on connecting KeyInCode locks to Seam, see the [KeyInCode Setup Guide](./keyincode-setup-guide).

***

## Where to Order

<CardGroup>
  <Card title="KeyInCode - Smart Locks" href="https://keyincode.com/" />
</CardGroup>


# KeyInCode Setup Guide
Source: https://docs.seam.co/device-and-system-integration-guides/keyincode-locks/keyincode-setup-guide

Connect your KeyInCode locks to Seam.

## Overview

This guide walks you through connecting your KeyInCode locks to Seam. Your KeyInCode locks must already be installed and connected to Wi-Fi before proceeding.

***

## Step 1: Connect to Seam via Connect Webview

1. Open the [Connect Webview](/core-concepts/connect-webviews) provided by your application.
2. Select KeyInCode as the provider.
3. Log in with your KeyInCode account credentials.
4. Once authorized, your KeyInCode locks appear as devices in Seam.

***

## Step 2: Verify the Connection

After connecting, verify that your KeyInCode locks appear as devices and show as online with lock/unlock and access code capabilities.

***

## Troubleshooting

### Authorization fails in Connect Webview

Verify that you are using the correct KeyInCode account credentials.

### Locks not appearing after authorization

Ensure your KeyInCode locks are set up and online in the KeyInCode app. Only locks that are active and connected to Wi-Fi appear in Seam.


# Sandbox KeyInCode Locks
Source: https://docs.seam.co/device-and-system-integration-guides/keyincode-locks/sandbox-keyincode-locks

Add virtual KeyInCode locks to your Seam sandbox workspace using these sample credentials to test your integration without real hardware.

Use the following set of credentials to add virtual [KeyInCode locks](/device-and-system-integration-guides/keyincode-locks) to your Seam [sandbox workspace](/core-concepts/workspaces#sandbox-workspaces):

| Email Address                               | Password |
| ------------------------------------------- | -------- |
| [jane@example.com](mailto:jane@example.com) | 1234     |

The sandbox account includes two virtual locks: **Front Door Lock** and **Back Door Lock**.


# Keynest Key Lockers
Source: https://docs.seam.co/device-and-system-integration-guides/keynest-key-lockers/index

Automating physical key hand‑offs with KeyNest lockers

<img alt="KeyNest logo" />

## Overview

Connect your Keynest account to Seam to automate key pickup and drop-off for your properties. Keynest integrates directly with Seam’s Smart Lock API, letting you manage access to physical keys the same way you manage digital locks or credentials. Each physical key stored at a Keynest location appears as a device in Seam. You can issue time-bound pickup and drop-off codes through the Seam API, allowing guests, staff, or vendors to access keys securely without manual coordination.

***

## Supported Devices

<DeviceList />

This integration supports all keys stored and managed under your Keynest account. Each key is represented as a device within Seam once connected.

<Warning>
  Note: Keys stored at [Quadrient
  lockers](https://www.quadient.com/en/news/KeyNest_Selects_Parcel_Pending_by_Quadient_Open_Network_to_Expand_Key_Exchange_Services_in_the_UK)
  aren't supported.
</Warning>

***

## Supported Features

With this integration, users can manage:

* **Collection Code** - Generate codes for guests to collect keys from KeyNest Points
* **Drop-off Code** - Create codes for dropping keys off at KeyNest Points
* **Real-time Key Tracking** - Monitor key status, location, and access activity
* **Magic Link Access** - Provide guests with direct access links for seamless key collection (To Be Implemented)

***

## Device Provider Key for Connect Webview

Seam identifies these devices with the `keynest` device provider key. By default, a [Connect Webview](/core-concepts/connect-webviews) displays all of the stable providers that Seam supports, so your users can connect their Keynest keys without you specifying a provider list. To narrow what a Connect Webview displays, see [Customize the Brands to Display in Your Connect Webviews](/core-concepts/connect-webviews/customizing-connect-webviews#customize-the-brands-to-display-in-your-connect-webviews).

***

## Where to Order

Purchase KeyNest services or get more details about KeyNest locations directly from the KeyNest website:

<table>
  <thead>
    <tr>
      <th />

      <th />

      <th />

      <th />

      <th />
    </tr>
  </thead>

  <tbody>
    <tr>
      <td />

      <td>
        <strong>KeyNest</strong>
      </td>

      <td />

      <td>
        <a href="https://keynest.com/">[https://keynest.com/](https://keynest.com/)</a>
      </td>

      <td>
        <a href="/images/keynest-logo-transparent.png">
          keynest logo transparent.png
        </a>
      </td>
    </tr>
  </tbody>
</table>

***


# Keynest Setup Instructions
Source: https://docs.seam.co/device-and-system-integration-guides/keynest-key-lockers/keynest-setup-instructions

Connect your Keynest key lockers to Seam by setting up your keys in a Keynest account and choosing a supported drop-off location.

### Step 1: Set up your key in **Keynest**

If your keys are already listed in your Keynest account, skip to Step 2.

1. Sign in or [create a Keynest account](https://keynest.com/).

2. Select **Add a new key**.

3. Enter your property's postcode (i.e. W1D 3AD in London) and choose a convenient drop-off location.

   **Important**: Do not choose a Quadrient locker. Keys stored at Quadrient lockers are not supported.

4. Click **Use this KeyNest**, then follow the on-screen steps to register and drop off your key.

***

### Step 2: Connect your Keynest account to Seam

1. Note your Keynest login credentials.
2. In the Seam Connect Webview, login in. using these credentials to link your Keynest account.
3. Once connected, your existing keys will be available in Seam.

***

### Step 3: Issue pick ups

Through Seam, you can schedule pick up access codes for each key. Each code will have a defined pick up and drop off time frame, and can be revoked at anytime.

<Info>
  **Note:** The key must be stored at the designated KeyNest locker before it
  can be retrieved.
</Info>


# Sandbox Keynest Lockers
Source: https://docs.seam.co/device-and-system-integration-guides/keynest-key-lockers/sandbox-keynest-lockers

Add virtual Keynest keys to your Seam sandbox workspace using these sample credentials to test your integration without real hardware.

Use the following set of credentials to add virtual Keynest keys to your Seam [sandbox workspace](/core-concepts/workspaces#sandbox-workspaces):

| Email Address                               | Password |
| ------------------------------------------- | -------- |
| [jane@example.com](mailto:jane@example.com) | 1234     |


# Get started with Kwikset Wi-Fi Locks
Source: https://docs.seam.co/device-and-system-integration-guides/kwikset-locks/get-started-with-kwikset-wifi-locks

Learn how to connect and control your Kwikset Halo lock with the Seam API.

## Overview

Seam provides a universal API to connect and control many brands of smart locks. This guide provides a rapid introduction to connecting and controlling your [Kwikset Halo](https://www.seam.co/manufacturers/kwikset) lock using the Seam API. To learn more about other smart lock brands supported by Seam such as Yale, Schlage, and August, head over to our [integration page](https://www.seam.co/supported-devices-and-systems).

<Warning>
  Enabling MFA (Multi-Factor Authentication) on your Kwikset app can block our login flow from successfully authorizing with your account.

  Please ensure your Kwikset MFA settings are disabled before attempting to connect your account with Seam. After connecting your account, you can re-enable your MFA settings.

  To disable MFA, head to **Account Settings** in your Kwikset app:

  <img alt="Kwikset MFA Settings" />
</Warning>

## 1 — Install Seam SDK

Seam provides client libraries for many languages, such as JavaScript, Python, Ruby, PHP, and others, as well as a Postman collection and [OpenAPI](https://connect.getseam.com/openapi.json) spec.

* JavaScript / TypeScript ([npm](https://www.npmjs.com/package/seam), [GitHub](https://github.com/seamapi/javascript))
* Python ([pip](https://pypi.org/project/seam/), [GitHub](https://github.com/seamapi/python))
* Ruby Gem ([rubygem](https://rubygems.org/gems/seam), [GitHub](https://github.com/seamapi/ruby))
* PHP ([packagist](https://packagist.org/packages/seamapi/seam), [GitHub](https://github.com/seamapi/php))
* C# ([nuget](https://www.nuget.org/packages/Seam), [GitHub](https://github.com/seamapi/csharp))

<Tabs>
  <Tab title="JavaScript">
    ```bash theme={null}
    npm i seam
    ```
  </Tab>

  <Tab title="Python">
    ```bash theme={null}
    pip install seam
    # For some development environments, use pip3 in this command instead of pip.
    ```
  </Tab>

  <Tab title="Ruby">
    ```bash theme={null}
    bundle add seam
    ```
  </Tab>

  <Tab title="PHP">
    ```bash theme={null}
    composer require seamapi/seam
    ```
  </Tab>

  <Tab title="C#">
    Install using [nuget](https://www.nuget.org/packages/Seam).
  </Tab>
</Tabs>

Once installed, [sign-up for Seam](https://console.seam.co/) to get your API key, and export it as an environment variable:

```
$ export SEAM_API_KEY=seam_test2ZTo_0mEYQW2TvNDCxG5Atpj85Ffw
```

<Info>
  This guide uses a Sandbox Workspace. Only virtual devices can be connected. If
  you need to connect a real Kwikset Halo Lock, use a non-sandbox workspace and
  API key.
</Info>

## 2 — Link Kwikset Account with Seam

To control your Kwikset Halo lock via the Seam API, you must first authorize your Seam workspace against your Kwikset account. To do so, Seam provides[ Connect Webviews](/core-concepts/connect-webviews): pre-built UX flows that walk you through authorizing your application to control your Kwikset Halo lock.

#### Request a Connect Webview

<CodeGroup>
  ```javascript JavaScript theme={null}
  import { Seam } from 'seam'

  const seam = new Seam()

  const connectWebview = await seam.connectWebviews.create()

  console.log(connectWebview.login_successful) // false

  // Send the webview URL to your user
  console.log(connectWebview.url)

  ```

  ```python Python theme={null}
  from seam import Seam

  seam = Seam()

  webview = seam.connect_webviews.create()

  assert webview.login_successful is False

  # Send the webview URL to your user
  print(webview.url)
  ```

  ```ruby Ruby theme={null}
  require "seam"

  seam = Seam.new(api_key: "MY_API_KEY")

  webview = seam.connect_webviews.create()

  puts webview.login_successful # false

  # Send the webview URL to your user

  puts webview.url

  ```
</CodeGroup>

#### Authorize Your Workspace

Navigate to the URL returned by the Webview object. Since you are using a sandbox workspace, complete the login flow by entering the Kwikset [sandbox test accounts ](./kwikset-locks-sample-data)credentials below:

* **email:** [jane@example.com](mailto:jane@example.com)
* **password:** 1234

<Warning>
  Enabling MFA (Multi-Factor Authentication) on your Kwikset app can block our login flow from successfully authorizing with your account.

  Please ensure your Kwikset MFA settings are disabled before attempting to connect your account with Seam. After connecting your account, you can re-enable your MFA settings.

  To disable MFA, head to **Account Settings** in your Kwikset app:

  <img alt="Kwikset MFA Settings" />
</Warning>

<img alt="Seam Connect Webview flow to connect Kwikset account with Seam" />

Confirm the Connect Webview was successful by querying its status:

<CodeGroup>
  ```javascript JavaScript theme={null}
  const updatedWebview = await seam.connectWebviews.get(
    connectWebview.connect_webview_id,
  )

  console.log(updatedWebview.login_successful) // true
  ```

  ```python Python theme={null}
  updated_webview = seam.connect_webviews.get(connect_webview_id: webview.connect_webview_id)

  assert updated_webview.login_successful # true

  ```

  ```ruby Ruby theme={null}
  updated_webview = seam.connect_webviews.get(connect_webview_id: webview.connect_webview_id)

  puts updated_webview.login_successful # true
  ```
</CodeGroup>

## 3 — Retrieve Kwikset Halo Lock Devices

After a Kwikset account is linked with Seam, you can retrieve devices for this Kwikset account. The Seam API exposes most of the device's properties such as battery level or door lock status.

<CodeGroup>
  ```javascript JavaScript theme={null}
  const allLocks = await seam.locks.list()

  const someLock = allLocks[0]

  console.log(someLock.properties.online) // true
  console.log(someLock.properties.locked) // true

  console.log(someLock)
  /*
  {
  device_id: '10891c43-29e0-4b93-b071-34749025a123',
  device_type: 'kwikset_lock',
  capabilities_supported: [
  'lock'
  ],
  properties: {
  locked: true,
  online: true,
  manufacturer: 'kwikset',
  battery_level: 0.65,
  kwikset_metadata: {
  device_id: '10d221f8e8445dbe07',
  device_name: 'Kwikset Halo Touch',
  model_number: 'HALO-01'
  },
  name: 'Kwikset Halo Touch',
  battery: {
  level: 0.65,
  status: 'good'
  },
  image_url: 'https://connect.getseam.com/assets/images/devices/kwikset_halo_touchscreen-wi-fi-enabled-smart-lock_polished-chrome_front.png',
  image_alt_text: 'Kwikset Halo Touchscreen Wifi Enabled Smart Lock, Polished Chrome, Front'
  },
  location: null,
  }
  */

  ```

  ```python Python theme={null}
  all_locks = seam.locks.list()

  some_lock = all_locks[0]

  assert some_lock.properties["online"] is True

  assert some_lock.properties["locked"] is True

  print(some_lock)


  # Device(
  #     device_id='10891c43-29e0-4b93-b071-34749025a123',
  #     device_type='kwikset_lock',
  #     location=None,
  #     properties={
  #         'locked': True,
  #         'online': True,
  #         'manufacturer': 'kwikset',
  #         'battery_level': 0.65,
  #         'kwikset_metadata': {
  #             'device_id': '10d221f8e8445dbe07',
  #             'device_name': 'Kwikset Halo Touch',
  #             'model_number': 'HALO-01'
  #         },
  #         'name': 'Kwikset Halo Touch',
  #         'battery': {
  #             'level': 0.65,
  #             'status': 'good'
  #         },
  #         'image_url': 'https://connect.getseam.com/assets/images/devices/kwikset_halo_touchscreen-wi-fi-enabled-smart-lock_polished-chrome_front.png',
  #         'image_alt_text': 'Kwikset Halo Touchscreen Wifi Enabled Smart Lock, Polished Chrome, Front'
  #     },
  #     capabilities_supported=['lock']
  # )
  ```

  ```ruby Ruby theme={null}
  some_lock = seam.locks.list.first

  puts some_lock.properties.online # true
  puts some_lock.properties.locked # true

  puts some_lock.inspect

  # <Seam::Device:0x00438

  # device_id="10891c43-29e0-4b93-b071-34749025a123"

  # device_type="kwikset_lock"

  # properties={

  # "locked"=>true,

  # "online"=>true,

  # "manufacturer"=>"kwikset",

  # "battery_level"=>0.65,

  # "kwikset_metadata"=>{"device_id"=>"10d221f8e8445dbe07", "device_name"=>"Kwikset Halo Touch", "model_number"=>"HALO-01"},

  # "name"=>"Kwikset Halo Touch",

  # "battery"=>{"level"=>0.65, "status"=>"good"},

  # "image_url"=>"https://connect.getseam.com/assets/images/devices/kwikset_halo_touchscreen-wi-fi-enabled-smart-lock_polished-chrome_front.png",

  # "image_alt_text"=>"Kwikset Halo Touchscreen Wifi Enabled Smart Lock, Polished Chrome, Front"

  # }

  >

  ```
</CodeGroup>

**4 — Locking & Unlocking a Door**

Next, you can perform the basic action of locking and unlocking the door.

> **`POST`** `/locks/lock_door`
>
> See the [API Reference](/api/locks/lock_door) for details.

#### Unlock a door

<mark>`POST`</mark> `https://connect.getseam.com/locks/unlock_door`

**Request Body**

| Name       | Type   | Description |
| ---------- | ------ | ----------- |
| device\_id | String |             |

<CodeGroup>
  ```javascript JavaScript theme={null}
  // lock the door
  await seam.locks.lockDoor(someLock.device_id)
  const updatedLock = await seam.locks.get(someLock.device_id)
  console.log(updatedLock.properties.locked) // true

  // unlock the door
  await seam.locks.unlockDoor(someLock.device_id)
  updatedLock = await seam.locks.get(someLock.device_id)
  console.log(updatedLock.properties.locked) // false
  ```

  ```python Python theme={null}
  # lock the door
  seam.locks.lock_door(device_id: some_lock.device_id)
  updated_lock = seam.locks.get(device_id: some_lock.device_id)
  assert updated_lock.properties["locked"] is True

  # Now unlock the door

  seam.locks.unlock_door(device_id: some_lock.device_id)
  updated_lock = seam.locks.get(device_id: some_lock.device_id)
  assert updated_lock.properties["locked"] is False

  ```

  ```ruby Ruby theme={null}
  # lock the door
  seam.locks.lock_door(device_id: some_lock.device_id)
  updated_lock = seam.locks.get(device_id: some_lock.device_id)
  puts updated_lock.properties.locked # true

  # unlock the door
  seam.locks.unlock_door(device_id: some_lock.device_id)
  updated_lock = seam.locks.get(device_id: some_lock.device_id)
  puts updated_lock.properties.locked # false
  ```
</CodeGroup>

**5 — Setting Access Code on Kwikset Lock**

<Info>
  In the Kwikset app, you cannot see access codes that were set from an external source (such as Seam) unless you are connected through Bluetooth to the lock.

  If you're connected through Wi-Fi and not Bluetooth, the Kwikset app *only* shows the access codes that you have set from the app itself and not the codes set from Seam.
</Info>

Some Kwikset locks have a keypad paired to them to program access codes. These codes can then be entered to unlock a Kwikset lock.

The Seam API makes it easy to program both `ongoing` codes and `timebound` codes on a Kwikset lock. You can find out more about Kwikset lock access code in our [core concept section on access codes.](/low-level-apis/smart-locks/access-codes)

**Access Code Constraints**

Kwikset locks place the following constraints on access code attributes:

* Access code name must contain 2-14 characters.

  You can create a Seam access code for Kwikset with a name longer than 14 characters. The full name is stored in Seam, but on the Kwikset device, the name is truncated to 14 characters.

* PIN code length must be 4-8 digits.

* A `timebound` code requires both a `starts_at` timestamp and an `ends_at` timestamp.

* A `timebound` code's `starts_at` timestamp must be greater than the current time. For best results, set `starts_at` at least 15 minutes ahead of the current time.

<CodeGroup>
  ```javascript JavaScript theme={null}
  // create an ongoing code
  await seam.accessCodes.create({
    device_id: someLock.device_id,
    code: '123456',
    name: 'My Access Code',
  })

  // create a timebound code
  await seam.accessCodes.create({
  device_id: someLock.device_id,
  code: '888888',
  name: 'Scheduled Code',
  starts_at: '2028-11-12T19:23:42+0000',
  ends_at: '2028-11-13T19:23:42+0000',
  })

  // use a device_id as the "device_id" parameter
  await seam.accessCodes.list({
  device_id: someLock.device_id,
  })

  /*
  [
  {
  code: '1988',
  type: 'ongoing',
  status: 'setting',
  created_at: '2022-08-26T12:50:17.858Z',
  access_code_id: '26d6138c-6524-4f3c-ac96-43cc3bea0a8d'
  },
  {
  type: 'timebound',
  code: '888888',
  starts_at: '2028-08-12T19:24:00.000Z',
  ends_at: '2028-08-13T19:24:00.000Z',
  access_code_id: '8c2db4da-b137-4c08-a2c3-d611e6ff91b3',
  }
  ]
  */

  ```

  ```python Python theme={null}
  # create an ongoing code
  seam.access_codes.create(
      device=some_lock, code="123456", name="My Access Code"
  )

  # create a timebound code
  seam.access_codes.create(
      device=some_lock,
      code="888888",
      name="Scheduled Code",
      starts_at="2028-08-12T19:23:42+0000",
      ends_at="2028-08-13T19:23:42+0000"
  )

  # you can use a device or a device_id as the "device" parameter
  seam.access_codes.list(device=some_lock)
  # [
  #   AccessCode(
  #     access_code_id='af5272b1-2a49-4eb5-9388-2447fc7b5bd1',
  #     type='ongoing',
  #     code='123459'
  #   ),
  #   AccessCode(
  #     access_code_id='8c2db4da-b137-4c08-a2c3-d611e6ff91b3',
  #     type='timebound',
  #     code='888888',
  #     starts_at='2028-08-12T19:24:00.000Z',
  #     ends_at='2028-08-13T19:24:00.000Z',
  #   )
  # ]

  ```

  ```ruby Ruby theme={null}
  # create an ongoing code
  seam.access_codes.create(
    device_id: some_lock.device_id, code: '123456', name: 'My Access Code'
  )

  # create a timebound code

  seam.access_codes.create(
  device_id: some_lock.device_id,
  code: '888888',
  name: 'Scheduled Code',
  starts_at: '2028-08-12T19:23:42+0000',
  ends_at: '2028-08-13T19:23:42+0000'
  )

  seam.access_codes.list(device_id: some_lock.device_id)

  # [<Seam::AccessCode:0x00730

  # code="888888"

  # name="Scheduled Code"

  # type="time_bound"

  # errors=[]

  # warnings=[]

  # access_code_id="ce2c298c-364f-4b13-aa12-712f3976288e"

  # ends_at=2028-08-13 19:24:00 UTC

  # starts_at=2028-08-12 19:24:00 UTC>, <Seam::AccessCode:0x00758

  # code="123456"

  # name="My Access Code"

  # type="ongoing"

  # errors=[]

  # warnings=[]

  # access_code_id="75f49550-fc9b-481a-a158-5bc53ac9bb34">, <Seam::AccessCode:0x00780

  # code="086355"

  # name="some-code2"

  # type="ongoing"

  # errors=[]

  # warnings=[]

  # access_code_id="5243e5f3-528a-4378-ba3c-21447bf844a8">, <Seam::AccessCode:0x007a8

  # code="376525"

  # name="some-code"

  # type="ongoing"

  # errors=[]

  # warnings=[]

  # access_code_id="91a08a3d-a0bb-4ff0-bfb4-ced164353988">]

  ```

  ```php PHP theme={null}
  use Seam\SeamClient;

  $seam = new SeamClient("YOUR_API_KEY");

  $some_lock = $seam->locks->list()[0];
  $seam->access_codes->create(
  device_id: $some_lock->device_id, code: '123456', name: 'My Access Code'
  );

  $seam->access_codes->create(
  device_id: $some_lock->device_id,
  name: 'Scheduled Code',
  code: '888888',
  starts_at: '2028-08-12T19:23:42+0000',
  ends_at: '2028-08-13T19:23:42+0000'
  );

  ```
</CodeGroup>

## Next Steps

Now that you've completed this guide, you can try to connect a real Kwikset Halo device. To do so, make sure to switch to a non-sandbox workspace and API key as real devices cannot be connected to sandbox workspaces.

In addition, if you'd like to explore other aspects of Seam, here is a list of helpful resources:

* [Yale Getting Started Guide](../yale-locks/get-started-with-yale-locks)
* [August Getting Started Guide](../august-locks/get-started-with-august-locks)
* [Schlage Getting Started Guide](../schlage-locks/get-started-with-schlage-locks)
* [SmartThings Getting Started Guide](../smartthings-hubs-+-devices/get-started-with-smartthings-hubs-+-smart-locks)
* [Receiving webhook](/developer-tools/webhooks) for [device events](/api/events/list)
* [Core Concepts](/core-concepts/overview)

If you have any questions or want to report an issue, email us at [support@seam.co](mailto:support@seam.co).


# Kwikset Locks
Source: https://docs.seam.co/device-and-system-integration-guides/kwikset-locks/index

Guide for using Kwikset locks with Seam

<img alt="Kwikset logo" />

## Overview

Kwikset produces smart locks suitable for residential homes, rental properties, and vacation rentals. The Kwikset Halo and Halo Touch series offer Wi-Fi-enabled smart locks that connect directly to the existing Wi-Fi router for a property, eliminating the need for a separate smart home hub. On the other hand, the Kwikset SmartCode series provides multiple connectivity options, including Zigbee and Z-Wave. For SmartCode series locks, the Seam integration requires the use of a hub. The Seam integration enables the remote unlocking feature and the ability to set customizable access codes for the Kwikset Halo, Halo Touch, and SmartCode series.

***

## Supported Devices

<DeviceList />

This integration supports the Kwikset [Halo](https://www.kwikset.com/halo), [Halo Touch](https://www.kwikset.com/halo-touch), and [SmartCode](https://www.kwikset.com/products/electronic/electronic-smart-locks) lines of smart locks.

For detailed information about the Kwikset devices that Seam supports, see our [Kwikset Supported Devices page](https://www.seam.co/manufacturers/kwikset).

***

## Supported Features

We support the following features:

* [Triggering web lock and unlock actions](/low-level-apis/smart-locks/lock-and-unlock)
* [Programming access codes](/low-level-apis/smart-locks/access-codes)

<Info>
  Seam does not support [unmanaged access
  codes](/low-level-apis/smart-locks/access-codes/migrating-existing-access-codes)
  for Kwikset.
</Info>

***

### Device Provider Key

Seam identifies these devices with the `kwikset` device provider key. By default, a [Connect Webview](/core-concepts/connect-webviews) displays all of the stable providers that Seam supports, so your users can connect their Kwikset devices without you specifying a provider list. To narrow what a Connect Webview displays, see [Customize the Brands to Display in Your Connect Webviews](/core-concepts/connect-webviews/customizing-connect-webviews#customize-the-brands-to-display-in-your-connect-webviews).

***

## Setup Instructions

For instructions on connecting Kwikset locks to Seam, see the [Kwikset Setup Guide](./kwikset-setup-guide).

***

## Brand-Specific Restrictions

In the Kwikset app, you cannot see access codes that were set from an external source (such as Seam) unless you are connected through Bluetooth to the lock. If you're connected through Wi-Fi and not Bluetooth, the Kwikset app only shows the access codes that you have set from the app itself and not the codes set from Seam.

***

## Brand-Specific Access Code Constraints

Kwikset locks place the following constraints on access code attributes:

* Access code name must contain 2-14 characters.

  You can create a Seam access code for Kwikset with a name longer than 14 characters. The full name is stored in Seam, but on the Kwikset device, the name is truncated to 14 characters.

* PIN code length must be 4-8 digits.

* A `timebound` code requires both a `starts_at` timestamp and an `ends_at` timestamp.

* A `timebound` code's `starts_at` timestamp must be greater than the current time. For best results, set `starts_at` at least 15 minutes ahead of the current time.

***

## Brand-Specific Events

Seam supports the following events and event property values for Kwikset devices:

### Kwikset Auto-Lock

Kwikset devices have an auto-lock feature that automatically locks the device after a configurable period of time, for example, 30 seconds. The Seam API reports these auto-lock occurrences by emitting a [`lock.locked` event](/api/locks/events#lock-locked) with `automatic` as the value for the `method` property.

### Kwikset Access Denied Event

The Seam API emits a [`lock.access_denied` event](/api/locks/events#lock-access_denied) when an incorrect access code is entered three times in a row on a Kwikset device. The Kwikset device also emits warning beeps for approximately 15 seconds, and the keypad is locked during this time. The keypad remains locked for one minute after the warning beeps end.

***

## Where to Order

Order Kwikset locks from Amazon.

<table>
  <thead>
    <tr>
      <th />

      <th />

      <th />

      <th />

      <th />
    </tr>
  </thead>

  <tbody>
    <tr>
      <td />

      <td>
        <strong>Kwikset Halo, Halo Touch, and SmartCode Locks on Amazon</strong>
      </td>

      <td />

      <td>
        <a href="https://www.amazon.com/s?k=kwikset+halo+or+smartcode+lock">
          [https://www.amazon.com/s?k=kwikset+halo+or+smartcode+lock](https://www.amazon.com/s?k=kwikset+halo+or+smartcode+lock)
        </a>
      </td>

      <td />
    </tr>
  </tbody>
</table>

***


# Sandbox Kwikset Locks
Source: https://docs.seam.co/device-and-system-integration-guides/kwikset-locks/kwikset-locks-sample-data

Add virtual Kwikset locks to your Seam sandbox workspace using these sample credentials to test your integration without real hardware.

Use the following set of credentials to add virtual [Kwikset locks](/device-and-system-integration-guides/kwikset-locks) to your Seam [sandbox workspace](/core-concepts/workspaces#sandbox-workspaces):

| Email Address                                                                              | Password |
| ------------------------------------------------------------------------------------------ | -------- |
| [jane@example.com](mailto:jane@example.com) or any email address in the example.com domain | 1234     |


# Kwikset Setup Guide
Source: https://docs.seam.co/device-and-system-integration-guides/kwikset-locks/kwikset-setup-guide

Connect your Kwikset locks to Seam.

This guide walks you through connecting your Kwikset locks to Seam. Your locks must already be set up and working in the Kwikset App before proceeding.

## 1. Create a Kwikset account

If you don't already have one, download the [Kwikset App](https://www.kwikset.com/smart-locks/app) and create an account. Add your Kwikset locks in the app and confirm they are online.

## 2. Disable 2-Step Verification

In the Kwikset App, tap the top-left menu button, navigate to **Account Settings**, and disable **2-Step Verification**.

<Warning>
  You must disable **2-Step Verification** (multifactor authentication) before connecting your Kwikset account to Seam. Enabling MFA can block the Seam login process from performing successful authorization using your Kwikset account. After you connect your Kwikset account to Seam, you can re-enable **2-Step Verification** in the Kwikset App **Account Settings**.
</Warning>

## 3. Connect Kwikset to Seam

Use the login credentials for your Kwikset account to log in through the [Seam Connect Webview](/core-concepts/connect-webviews) and authorize Seam to access your devices.

## 4. Verify the connection

After completing the Connect Webview, confirm that your Kwikset locks appear in your Seam workspace and show an **online** status.

***

## Troubleshooting

If your devices don't appear after connecting:

* Confirm that your Kwikset locks are online in the Kwikset App.
* Verify that you logged in with the same Kwikset account that owns the locks.
* Wait a few minutes for the initial sync to complete, then refresh your device list.

If you receive an authorization error during the Connect Webview:

* Verify that **2-Step Verification** is disabled in the Kwikset App **Account Settings**.
* You can re-enable 2-Step Verification after the connection is established.


# Latch Access Control System
Source: https://docs.seam.co/device-and-system-integration-guides/latch-access-control-system/index

Guide for using the Latch Access Control System with Seam

<img alt="Latch logo" />

## Overview

Seam integrates seamlessly with the [Latch](https://www.latch.com/) management platform. Property managers and owners use the Latch [access control system](/low-level-apis/access-systems) (ACS) to control access across their properties. Latch enables them to manage who has access to which spaces and when, view access history, and set up and manage multiple users and guests.

The Seam integration for Latch enables you to automate the creation of residents and the issuing of credentials to these residents. Within these credentials, you specify the entrances to which the residents have access and the access schedules.

Latch enables you to install wireless door locks and intercom systems in your building. This low-cost solution does not require the hard-wired [Latch hub](https://marketing.latch.com/latch-hub) to provision and use mobile keys. However, if you want to provision PIN codes remotely, you do need to install the Latch hub.

***

## Latch ACS Resources

The Seam ACS schema consists of a series of resources that interact intuitively, enabling you to use the Seam API to manage your Latch ACS in a logical, efficient manner. Latch is a [credential-based ACS](/low-level-apis/access-systems/connect-an-acs-to-seam/understanding-access-control-system-differences#credential-based-access-control-systems), so you [create ACS users](/low-level-apis/access-systems/user-management#create-an-acs-user) and then grant them access permissions using credentials. When you create a credential, you specify the ACS user to which to assign the credential, as well as the allowed entrances and the start and end times for the access schedule.

The following diagram shows the Seam resources for a Latch ACS and the relationships between these resources:

The following table provides a brief description of each of the Seam resources for the Latch ACS:

<table>
  <thead>
    <tr>
      <th>Seam Resource</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        <a href="/api/acs/users/object">
          <code>acs\_user</code>
        </a>
      </td>

      <td>
        Individual who has been granted access to specific entrances within a
        building. A user could be a resident or temporary guest.
      </td>
    </tr>

    <tr>
      <td>
        <a href="/api/acs/entrances/object">
          <code>acs\_entrance</code>
        </a>
      </td>

      <td>
        Physical points of entry within a property that are secured with Latch's
        smart access devices.
      </td>
    </tr>

    <tr>
      <td>
        <a href="/api/acs/credentials/object">
          <code>acs\_credential</code>
        </a>
      </td>

      <td>
        PIN codes or mobile keys. You can only assign one entrance to a key
        code-based credential. You can assign multiple entrances to mobile keys.
      </td>
    </tr>
  </tbody>
</table>

For more information about managing your Latch ACS through Seam, see the following topics:

* [Programming Code-Based Latch Credentials](/device-and-system-integration-guides/latch-access-control-system/programming-code-based-latch-credentials)
* [Programming Latch ACS Mobile Credentials](/device-and-system-integration-guides/latch-access-control-system/programming-latch-acs-mobile-credentials)
* [Credential-based ACS](/low-level-apis/access-systems/connect-an-acs-to-seam/understanding-access-control-system-differences)
* [Access Control Systems](/low-level-apis/access-systems)
* [Mobile Access](/capability-guides/mobile-access)

***

## Supported Devices

<DeviceList />

This integration supports all wireless locks and readers connected to the Latch ACS.

***

## Supported Features

We support the following features:

* [Managing access systems](/low-level-apis/access-systems)
* [Issuing mobile access credentials](/capability-guides/mobile-access)

***

### Device Provider Key

Seam identifies these devices with the `latch` device provider key. By default, a [Connect Webview](/core-concepts/connect-webviews) displays all of the stable providers that Seam supports, so your users can connect their Latch ACS without you specifying a provider list. To narrow what a Connect Webview displays, see [Customize the Brands to Display in Your Connect Webviews](/core-concepts/connect-webviews/customizing-connect-webviews#customize-the-brands-to-display-in-your-connect-webviews).

***

## Brand-Specific Restrictions

Note the following restrictions on using Seam to manage your Latch ACS:

* The Latch ACS does not support remote unlock functionality. Unlock operations must occur through a mobile app.
* You cannot sync in existing users and access permissions from a Latch ACS. You can only use Seam to manage the ACS users and credentials that you create through Seam.

***

## Troubleshooting

For information about Latch ACS-related errors, including issues related to the connection between your ACS and Seam, see [Troubleshooting Your ACS](/low-level-apis/access-systems/troubleshooting-your-access-control-system).

***

## Where to Order

To purchase the Latch ACS and devices, contact Latch Sales.

<table>
  <thead>
    <tr>
      <th />

      <th />

      <th />

      <th />

      <th />
    </tr>
  </thead>

  <tbody>
    <tr>
      <td />

      <td>
        <strong>Latch Sales Contact Page</strong>
      </td>

      <td />

      <td />

      <td>
        <a href="/images/latch-logo.png">latch-logo.png</a>
      </td>
    </tr>
  </tbody>
</table>


# Latch Setup Guide
Source: https://docs.seam.co/device-and-system-integration-guides/latch-access-control-system/latch-setup-guide

Learn how to configure your Latch ACS for integration with Seam.

To connect the Latch ACS to Seam, the property manager must perform a set of setup steps in the Latch Mission Control dashboard. Then, the application developer or property manager must establish the connection in Seam. Finally, the property manager must email connection details to Seam.

## Set Up Latch ACS

The property manager performs most of this procedure. The following instructions identify the steps that the application developer can also perform:

1. Send an email to [integrations@latch.com](mailto:integrations@latch.com) with the following message:

   "I would like to connect the following buildings to the partner 'Seam': \{Name of building}"

2. Log in to Latch Mission Control at [manager.latch.com](http://manager.latch.com).

3. In the Latch Mission Control dashboard, for each building that you’ve connected:
   * In the top menu, click **Access**.
   * On the **Access** page, click **Doors**.
   * On the **Doors** tab, for each door to which you want to grant access:
     1. Click the door to which you want to grant access.
     2. On the right, click **Edit**.
     3. Under **Partner access**, select **Seam**.
     4. At the top right, click **Save**.
   * Note the building ID within the URL for this page. You must send the ID of each building you want to connect to Seam. Save the building ID for a later step with further instructions.\\

## Establish Seam Connection

The property manager or application developer must perform the following steps:

1. Create a [Connect Webview](/core-concepts/connect-webviews).
2. Display the Connect Webview and perform the following steps:
   * If the Connect Webview displays multiple brand options, select **Latch**.
   * In the **Connect a Latch Building** dialog, copy and note your Seam Connect ID. You must send this Connect ID to Seam. Save the Connect ID for a later step with further instructions.
   * Click **Continue**.

## Email Connection Details to Seam

The property manager must send [latch@getseam.com](mailto:latch@getseam.com) an email with the following information:

> I would like to connect the following Latch buildings to my workspace:
>
> * \{Your Seam workspace ID}
> * Latch building IDs:
>   * \{Latch building ID for each building that you want to connect to Seam}


# Programming Code-Based Latch Credentials
Source: https://docs.seam.co/device-and-system-integration-guides/latch-access-control-system/programming-code-based-latch-credentials

Learn how to create Latch PIN codes.

## Requirements for Syncing PIN Code Access Updates

If you want to sync access updates to Latch-controlled entrances remotely, you must install the hard-wired [Latch hub](https://marketing.latch.com/latch-hub) to connect to all the wireless entrances. Once installed, you can use Seam to program code-based credentials, and the changes will sync automatically through the hub.

Alternately, you can update entrances manually using the [Latch Manager App](https://support.latch.com/hc/en-us/articles/16123811974935-Door-Updates) whenever you've made changes to your users' access.

***

## Program a Code-Based Latch Credential

To use the Seam API to program codes for users in a [Latch ACS](./):

1. Create an [ACS user](/low-level-apis/access-systems/user-management).
   * Specify the `acs_system_id` of the Latch ACS in the building to which you want to grant the new user access.
   * Specify the details of the new ACS user, such as their `full_name`, `email_address`, and so on.
2. Create an [ACS credential](/low-level-apis/access-systems/managing-credentials).

   * Specify the `acs_user_id` of the user that you just created.
   * Specify the ID of the entrance to which you want to grant access.\
     Note that you must create a separate credential for each entrance to which you want to grant the ACS user access.
   * Specify the desired start and end dates and times for this access.
   * Set the `access_method` to `code`.

   Creating a new `acs_credential` object prompts the Latch ACS to generate a PIN code for the user.

<Info>
  When you create a credential for a Latch ACS, you cannot specify a custom
  code. Instead, you must let Latch generate the PIN code.
</Info>

The following example walks you through this process:

**Code:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  // Step 1:
  // Create the new user on the Latch ACS.
  // janeUser is a user_identity that represents
  // a user within your set of app users.
  const buildingAResident = await seam.acs.users.create({
    acs_system_id: '11111111-1111-1111-1111-111111111111',
    user_identity_id: janeUser.user_identity_id,
    full_name: 'Jane Doe',
    email_address: 'jane@example.com',
  })

  // Step 2:
  // Create a PIN code for each door for the ACS user.
  for (const entrance of entrances) {
    const credential = await seam.acs.credentials.create({
      acs_user_id: buildingAResident.acs_user_id,
      access_method: 'code',
      allowed_acs_entrance_ids: [
        // You must specify only one entrance per PIN code.
        entrance.acs_entrance_id,
      ],
      starts_at: '2024-07-13T16:50:42.072Z',
      ends_at: '2024-07-18T16:50:42.072Z',
    })

    console.log(credential)

    // It is also useful to list the entrances
    // to which the mobile key grants access.
    await seam.acs.credentials.listAccessibleEntrances({
      acs_credential_id: credential.acs_credential_id,
    })
  }
  ```

  ```bash cURL theme={null}
  # Step 1:
  # Create the new user on the Latch ACS.
  # jane_user is a user_identity that represents
  # a user within your set of app users.
  building_a_resident=$(curl -X 'POST' \
    'https://connect.getseam.com/acs/users/create' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d "{
    \"acs_system_id\": \"11111111-1111-1111-1111-111111111111\",
    \"user_identity_id\": \"$(jq -r '.user_identity.user_identity_id' <<< ${jane_user})\",
    \"full_name\": \"Jane Doe\",
    \"email_address\": \"jane@example.com\"
  }")

  # Step 2:
  # Create a PIN code for each door for the ACS user.
  for entrance_id in ${entrance_ids[@]};
  do
    # You must specify only one entrance per PIN code.
    credential=$(curl -X 'POST' \
      'https://connect.getseam.com/acs/credentials/create' \
      -H 'accept: application/json' \
      -H "Authorization: Bearer ${SEAM_API_KEY}" \
      -H 'Content-Type: application/json' \
      -d "{
      \"acs_user_id\": \"$(jq -r '.acs_user.acs_user_id' <<< ${building_a_resident})\",
      \"access_method\": \"code\",
      \"allowed_acs_entrance_ids\": [
        \"${entrance_id}\"
      ],
      \"starts_at\": \"2024-07-13T16:50:42.072Z\",
      \"ends_at\": \"2024-07-18T16:50:42.072Z\"
    }");

    echo $credential;

    # It is also useful to list the entrances
    # to which the mobile key grants access.
    # Use GET or POST.
    curl -X 'GET' \
      'https://connect.getseam.com/acs/credentials/list_accessible_entrances' \
      -H 'accept: application/json' \
      -H "Authorization: Bearer ${API_KEY}" \
      -H 'Content-Type: application/json' \
      -d "{
      \"acs_credential_id\": \"$(jq -r '.acs_credential_id' <<< ${credential})\"
    }";
  done
  ```

  ```python Python theme={null}
  # Step 1:
  # Create the new user on the Latch ACS.
  # jane_user is a user_identity that represents
  # a user within your set of app users.
  building_a_resident = seam.acs.users.create(
    acs_system_id = "11111111-1111-1111-1111-111111111111",
    user_identity_id = jane_user.user_identity_id,
    full_name = "Jane Doe",
    email_address = "jane@example.com"
  )

  # Step 2:
  # Create a PIN code for each door for the ACS user.
  for entrance in entrances:
    credential = seam.acs.credentials.create(
      acs_user_id = building_a_resident.acs_user_id,
      access_method = "code",
      allowed_acs_entrance_ids = [
        # You must specify only one entrance per PIN code.
        entrance.acs_entrance_id
      ],
      starts_at = "2024-07-13T16:50:42.072Z",
      ends_at = "2024-07-18T16:50:42.072Z"
    )

    pprint(credential)

    # View the list of entrances to which the credential
    # grants access.
    seam.acs.credentials.list_accessible_entrances(
      acs_credential_id = credential.acs_credential_id
    )
  ```

  ```ruby Ruby theme={null}
  # Coming soon!
  ```

  ```php PHP theme={null}
  // Step 1:
  // Create the new user on the Latch ACS.
  // $jane_user is a user_identity that represents
  // a user within your set of app users.
  $building_a_resident = $seam->acs->users->create(
    acs_system_id: "11111111-1111-1111-1111-111111111111",
    user_identity_id: $jane_user->user_identity_id,
    full_name: "Jane Doe",
    email_address: "jane@example.com"
  );

  // Step 2:
  // Create a PIN code for each door for the ACS user.
  foreach ($entrances as $entrance) {
    $credential = $seam->acs->credentials->create(
      acs_user_id: $building_a_resident->acs_user_id,
      access_method: "code",
      allowed_acs_entrance_ids: [
        // You must specify only one entrance per PIN code.
        $entrance->acs_entrance_id
      ],
      starts_at: "2024-07-13T16:50:42.072Z",
      ends_at: "2024-07-18T16:50:42.072Z"
    );

    echo json_encode($credential, JSON_PRETTY_PRINT);

    // It is also useful to list the entrances
    // to which the mobile key grants access.
    $seam->acs->credentials->list_accessible_entrances(
      acs_credential_id: $credential->acs_credential_id
    );
  }
  ```

  ```csharp C# theme={null}
  // Step 1:
  // Create the new user on the Latch ACS.
  // janeUser is a UserIdentity that represents
  // a user within your set of app users.
  AcsUser buildingAResident = seam.UsersAcs.Create(
    acsSystemId: "11111111-1111-1111-1111-111111111111",
    userIdentityId: janeUser.userIdentityId,
    fullName: "Jane Doe",
    emailAddress: "jane@example.com"
  );

  // Step 2:
  // Create a PIN code for each door for the ACS user.
  foreach (AcsEntrance entrance in entrances)
  {
    AcsCredential credential = seam.CredentialsAcs.Create(
      acsUserId: buildingAResident.acsUserId,
      accessMethod: "code",
      allowedAcsEntranceIds: new List<string>
      {
        // You must specify only one entrance per PIN code.
        entrance.acsEntranceId
      },
      startsAt: "2024-07-13T16:50:42Z",
      endsAt: "2024-07-18T16:50:42Z"
    );

    Console.WriteLine(credential);

    // It is also useful to list the entrances
    // to which the mobile key grants access.
    seam.CredentialsAcs.ListAccessibleEntrances(
      acsCredentialId: credential.acsCredentialId
    );
  }
  ```
</CodeGroup>

**Output:**

<CodeGroup>
  ```json JavaScript theme={null}
  {
    acs_credential_id: '66666666-6666-6666-6666-666666666666',
    acs_user_id: '33333333-3333-3333-3333-333333333333',
    code: '1234567',
    access_method: 'code',
    starts_at: '2024-07-13T16:50:42.072Z',
    ends_at: '2024-07-18T16:50:42.072Z',
    ...
  }
  [
    {
      acs_entrance_id: '55555555-5555-5555-5555-555555555555',
      display_name: 'Room Entrance',
      ...
    }
  ]
  ...
  ```

  ```json cURL theme={null}
  {
    "acs_credential":
      {
        "acs_credential_id": "66666666-6666-6666-6666-666666666666",
        "acs_user_id": "33333333-3333-3333-3333-333333333333",
        "code": "1234567",
        "access_method": "code",
        "starts_at": "2024-07-13T16:50:42.072Z",
        "ends_at": "2024-07-18T16:50:42.072Z",
        ...
      },
    "ok":true
  }
  {
    "acs_entrances": [
      {
        "acs_entrance_id": "55555555-5555-5555-5555-555555555555",
        "display_name": "Room Entrance",
        ...
      }
    ],
    "ok": true
  }
  ...
  ```

  ```json Python theme={null}
  AcsCredential(
    acs_credential_id='66666666-6666-6666-6666-666666666666',
    acs_user_id='33333333-3333-3333-3333-333333333333',
    code='1234567',
    access_method='code',
    starts_at='2024-07-13T16:50:42.072Z',
    ends_at='2024-07-18T16:50:42.072Z',
    ...
  )
  [
    AcsEntrance(
      acs_entrance_id='55555555-5555-5555-5555-555555555555',
      display_name='Room Entrance',
      ...
    )
  ]
  ...
  ```

  ```json Ruby theme={null}
  # Coming soon!
  ```

  ```json PHP theme={null}
  {
    "acs_credential_id": "66666666-6666-6666-6666-666666666666",
    "acs_user_id": "33333333-3333-3333-3333-333333333333",
    "code": "1234567",
    "access_method": "code",
    "starts_at": "2024-07-13T16:50:42.072Z",
    "ends_at": "2024-07-18T16:50:42.072Z",
    ...
  }
  [
    {
      "acs_entrance_id": "55555555-5555-5555-5555-555555555555",
      "display_name": "Room Entrance",
      ...
    }
  ]
  ...
  ```

  ```json C# theme={null}
  {
    "acs_credential_id": "66666666-6666-6666-6666-666666666666",
    "acs_user_id": "33333333-3333-3333-3333-333333333333",
    "code": "1234567",
    "access_method": "code",
    "starts_at": "2024-07-13T16:50:42Z",
    "ends_at": "2024-07-18T16:50:42Z",
    ...
  }
  {
    "acs_entrance_id": "55555555-5555-5555-5555-555555555555",
    "display_name": "Room Entrance",
    ...
  }
  ...
  ```
</CodeGroup>

***

## Next Steps

To learn more about using the Seam API with your Latch ACS, see the following topics:

* [Programming Latch ACS Mobile Keys for App Users](./programming-latch-acs-mobile-credentials)
* [Access Control Systems](/low-level-apis/access-systems)
* [Credential-based ACS](/low-level-apis/access-systems/connect-an-acs-to-seam/understanding-access-control-system-differences)
* [Managing ACS Users](/low-level-apis/access-systems/user-management)
* [Managing Credentials](/low-level-apis/access-systems/managing-credentials)
* [Mobile Access](/capability-guides/mobile-access)
* [Access Control Systems](/api/acs/object) in the Seam API reference
* [User Identities](/api/user_identities/object) in the Seam API reference


# Programming Latch ACS Mobile Credentials
Source: https://docs.seam.co/device-and-system-integration-guides/latch-access-control-system/programming-latch-acs-mobile-credentials

Learn how to create mobile credentials in the Latch ACS.

You can create mobile credentials that enable your mobile app users to unlock entrances in your [Latch access system](./). For more information about Seam mobile keys, see [Mobile Access](/capability-guides/mobile-access).

To use the Seam API to create mobile credentials for mobile app users in a Latch ACS:

1. Create a [user identity](/api/user_identities/object) that corresponds to your user's app account.

   Seam [user identities](/api/user_identities/object) enable you to match your own mobile app users to ACS users that you create using the Seam API.

2. Create an [access system user](/low-level-apis/access-systems/user-management) on the Latch access system or assign an existing access system user to the user identity.\
   The resources that you create for the access system user are available under the associated user identity.
   * In the access system user creation command, set the `user_identity_id` property for a new access system user. Alternately, use the `add_acs_user` command for user identities to assign an existing access system user to a user identity.
   * If you choose to create a new access system user, specify the `acs_system_id` of the Latch access system in the building to which you want to grant the new user access.
   * Specify the details of the access system user, such as their `full_name`, `email_address`, and so on.

3. Create a [credential](/low-level-apis/access-systems/managing-credentials) to represent the mobile key.

   * Specify the `acs_user_id`.
   * Set [`is_multi_phone_sync_credential`](/capability-guides/mobile-access/issuing-mobile-credentials-from-an-access-control-system#what-are-multi-phone-sync-credentials) to `true`.
   * Set the `access_method` to `mobile_key`.
   * Specify the IDs of the entrances to which you want to grant access.\
     Note that you can include multiple entrances in a single mobile key credential.
   * Specify the desired start and end dates and times for this access.

   Creating a new `acs_credential` object prompts the Latch access system to generate a PIN code for the user.

<Info>
  When you create a mobile key for a Latch access system, you cannot specify a
  code.
</Info>

The following example walks you through this process:

**Code:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  // Step 1:
  // Create a user identity that corresponds to your user's app account.
  const janeUser = await seam.userIdentities.create({
    email_address: 'jane@example.com',
  })

  // Step 2:
  // Create an access system user on the Latch access system
  // or assign the access system user to the user identity.
  const buildingAResident = await seam.acs.users.create({
    // To associate the ACSaccess system user with a user identity,
    // include the user_identity_id.
    // Resources that you create for this access system user
    // are available under the associated user identity.
    user_identity_id: janeUser.user_identity_id,
    acs_system_id: buildingA.acs_system_id,
    full_name: 'Jane Doe',
    email_address: 'jane@example.com',
  })

  // Step 3:
  // Create a mobile key for the entrances to which
  // you want to grant the access system user access.
  const mobileKey = await seam.acs.credentials.create({
    acs_user_id: buildingAResident.acs_user_id,
    is_multi_phone_sync_credential: true,
    access_method: 'mobile_key',
    allowed_acs_entrance_ids: [
      // You can include multiple entrances per mobile key.
      roomEntrance.acs_entrance_id,
      commonDoorEntrance.acs_entrance_id,
    ],
    starts_at: '2024-07-13T16:50:42.072Z',
    ends_at: '2024-07-18T16:50:42.072Z',
  })

  console.log(mobileKey)

  // It is also useful to list the entrances
  // to which the mobile key grants access.
  await seam.acs.credentials.listAccessibleEntrances({
    acs_credential_id: mobileKey.acs_credential_id,
  })
  ```

  ```bash cURL theme={null}
  # Step 1:
  # Create a user identity that corresponds to your user's app account.
  jane_user=$(curl -X 'POST' \
    'https://connect.getseam.com/user_identities/create' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d '{
    "email_address": "jane@example.com"
  }')

  # Step 2:
  # Create an access system user on the Latch access system
  # or assign the access system user to the user identity.

  # To associate the access system user with a user identity,
  # include the user_identity_id.
  # Resources that you create for this access system user
  # are available under the associated user identity.
  building_a_resident=$(curl -X 'POST' \
    'https://connect.getseam.com/acs/users/create' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d "{
    \"user_identity_id\": \"$(jq -r '.user_identity.user_identity_id' <<< ${jane_user})\",
    \"acs_system_id\": \"$(jq -r '.acs_system.acs_system_id' <<< ${building_a})\",
    \"full_name\": \"Jane Doe\",
    \"email_address\": \"jane@example.com\"
  }")

  # Step 3:
  # Create a mobile key for the entrances to which
  # you want to grant the access system user access.
  # You can include multiple entrances per mobile key.
  mobile_key=$(curl -X 'POST' \
    'https://connect.getseam.com/acs/credentials/create' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d "{
    \"acs_user_id\": \"$(jq -r '.acs_user.acs_user_id' <<< ${building_a_resident})\",
    \"is_multi_phone_sync_credential\": true,
    \"access_method\": \"mobile_key\",
    \"allowed_acs_entrance_ids\": [
      \"$(jq -r '.acs_entrance_id' <<< ${room_entrance})\",
      \"$(jq -r '.acs_entrance_id' <<< ${common_door_entrance})\"
    ],
    \"starts_at\": \"2024-07-13T16:50:42.072Z\",
    \"ends_at\": \"2024-07-18T16:50:42.072Z\"
  }");

  echo $mobile_key;

  # It is also useful to list the entrances
  # to which the mobile key grants access.
  # Use GET or POST.
  curl -X 'GET' \
    'https://connect.getseam.com/acs/credentials/list_accessible_entrances' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${API_KEY}" \
    -H 'Content-Type: application/json' \
    -d "{
    \"acs_credential_id\": \"$(jq -r '.acs_credential_id' <<< ${mobile_key})\"
  }"
  ```

  ```python Python theme={null}
  # Step 1:
  # Create a user identity that corresponds to your user's mobile app account.
  jane_user = seam.user_identities.create(
    email_address = "jane@example.com"
  )

  # Step 2:
  # Create an access system user on the Latch access system
  # or assign the ACS user to the user identity.
  building_a_resident = seam.acs.users.create(
    # To associate the access system user with a user identity,
    # include the user_identity_id.
    # Resources that you create for this access system user
    # are available under the associated user identity.
    user_identity_id = jane_user.user_identity_id,
    acs_system_id = building_a.acs_system_id,
    full_name = "Jane Doe",
    email_address = "jane@example.com"
  )

  # Step 3:
  # Create a mobile key for the entrances to which
  # you want to grant the access system user access.
  mobile_key = seam.acs.credentials.create(
    acs_user_id = building_a_resident.acs_user_id,
    is_multi_phone_sync_credential = True,
    access_method = "mobile_key",
    allowed_acs_entrance_ids = [
      # You can include multiple entrances per mobile key.
      room_entrance.acs_entrance_id,
      common_door_entrance.acs_entrance_id
    ],
    starts_at = "2024-07-13T16:50:42.072Z",
    ends_at = "2024-07-18T16:50:42.072Z"
  )

  pprint(mobile_key)

  # It is also useful to list the entrances
  # to which the mobile key grants access.
  seam.acs.credentials.list_accessible_entrances(
    acs_credential_id = mobile_key.acs_credential_id
  )
  ```

  ```ruby Ruby theme={null}
  # Coming soon!
  ```

  ```php PHP theme={null}
  // Step 1:
  // Create a user identity that corresponds to your user's app account.
  $jane_user = $seam->user_identities->create(
    email_address: "jane@example.com"
  );

  // Step 2:
  // Create an access system user on the Latch access system
  // or assign the access system user to the user identity.
  $building_a_resident = $seam->acs->users->create(
    // To associate the access system user with a user identity,
    // include the user_identity_id.
    // Resources that you create for this access system user
    // are available under the associated user identity.
    user_identity_id: $jane_user->user_identity_id,
    acs_system_id: $building_a->acs_system_id,
    full_name: "Jane Doe",
    email_address: "jane@example.com"
  );

  // Step 3:
  // Create a mobile key for the entrances to which
  // you want to grant the access system user access.
  $mobile_key = $seam->acs->credentials->create(
    acs_user_id: $building_a_resident->acs_user_id,
    is_multi_phone_sync_credential: true,
    access_method: "mobile_key",
    allowed_acs_entrance_ids: [
      // You can include multiple entrances per mobile key.
      $room_entrance->acs_entrance_id,
      $common_door_entrance->acs_entrance_id
    ],
    starts_at: "2024-07-13T16:50:42.072Z",
    ends_at: "2024-07-18T16:50:42.072Z"
  );

  echo json_encode($mobile_key, JSON_PRETTY_PRINT);

  // It is also useful to list the entrances
  // to which the mobile key grants access.
  $seam->acs->credentials->list_accessible_entrances(
    acs_credential_id: $mobile_key->acs_credential_id
  );
  ```

  ```csharp C# theme={null}
  // Step 1:
  // Create a user identity that corresponds to your user's app account.
  UserIdentity janeUser = seam.UserIdentities.Create(
    emailAddress: "jane@example.com"
  );

  // Step 2:
  // Create an access system user on the Latch access system
  // or assign the access system user to the user identity.
  AcsUser buildingAResident = seam.UsersAcs.Create(
    // To associate the access system user with a user identity,
    // include the userIdentityId.
    // Resources that you create for this access system user
    // are available under the associated user identity.
    userIdentityId: janeUser.userIdentityId,
    acsSystemId: buildingA.acsSystemId,
    fullName: "Jane Doe",
    emailAddress: "jane@example.com"
  );

  // Step 3:
  // Create a mobile key for the entrances to which
  // you want to grant the access system user access.
  AcsCredential mobileKey = seam.CredentialsAcs.Create(
    acsUserId: buildingAResident.acsUserId,
    isMultiPhoneSyncCredential: true,
    accessMethod: "mobile_key",
    allowedAcsEntranceIds: new List<string>
    {
      // You can include multiple entrances per mobile key.
      roomEntrance.acsEntranceId,
      commonDoorEntrance.acsEntranceId
    },
    startsAt: "2024-07-13T16:50:42Z",
    endsAt: "2024-07-18T16:50:42Z"
  );

  Console.WriteLine(mobileKey);

  // It is also useful to list the entrances
  // to which the mobile key grants access.
  seam.CredentialsAcs.ListAccessibleEntrances(
    acsCredentialId: mobileKey.acsCredentialId
  );
  ```
</CodeGroup>

**Output:**

<CodeGroup>
  ```json JavaScript theme={null}
  {
    acs_credential_id: '66666666-6666-6666-6666-666666666666',
    acs_user_id: '33333333-3333-3333-3333-333333333333',
    code: '1234567',
    access_method: 'mobile_Key',
    starts_at: '2024-07-13T16:50:42.072Z',
    ends_at: '2024-07-18T16:50:42.072Z',
    ...
  }
  [
    {
      acs_entrance_id: '55555555-5555-5555-5555-555555555555',
      display_name: 'Room Entrance',
      ...
    },
    {
      acs_entrance_id: '55555555-5555-5555-5555-000000000000',
      display_name: 'Common Door Entrance',
      ...
    }
  ]
  ```

  ```json cURL theme={null}
  {
    "acs_credential":
      {
        "acs_credential_id": "66666666-6666-6666-6666-666666666666",
        "acs_user_id": "33333333-3333-3333-3333-333333333333",
        "access_method": "mobile_key",
        "starts_at": "2024-07-13T16:50:42.072Z",
        "ends_at": "2024-07-18T16:50:42.072Z",
        ...
      },
    "ok":true
  }
  {
    "acs_entrances": [
      {
        "acs_entrance_id": "55555555-5555-5555-5555-555555555555",
        "display_name": "Room Entrance",
        ...
      },
      {
        "acs_entrance_id": "55555555-5555-5555-5555-000000000000",
        "display_name": "Common Door Entrance",
        ...
      }
    ],
    "ok": true
  }
  ```

  ```json Python theme={null}
  AcsCredential(
    acs_credential_id='66666666-6666-6666-6666-666666666666',
    acs_user_id='33333333-3333-3333-3333-333333333333',
    access_method='mobile_key',
    starts_at='2024-07-13T16:50:42.072Z',
    ends_at='2024-07-18T16:50:42.072Z',
    ...
  )
  [
    AcsEntrance(
      acs_entrance_id='55555555-5555-5555-5555-555555555555',
      display_name='Room Entrance',
      ...
    ),
    AcsEntrance(
      acs_entrance_id='55555555-5555-5555-5555-000000000000',
      display_name='Common Door Entrance',
      ...
    )
  ]
  ```

  ```json Ruby theme={null}
  # Coming soon!
  ```

  ```json PHP theme={null}
  {
    "acs_credential_id": "66666666-6666-6666-6666-666666666666",
    "acs_user_id": "33333333-3333-3333-3333-333333333333",
    "access_method": "mobile_key",
    "starts_at": "2024-07-13T16:50:42.072Z",
    "ends_at": "2024-07-18T16:50:42.072Z",
    ...
  }
  [
    {
      "acs_entrance_id": "55555555-5555-5555-5555-555555555555",
      "display_name": "Room Entrance",
      ...
    },
    {
      "acs_entrance_id": "55555555-5555-5555-5555-000000000000",
      "display_name": "Common Door Entrance",
      ...
    }
  ]
  ```

  ```json C# theme={null}
  {
    "acs_credential_id": "66666666-6666-6666-6666-666666666666",
    "acs_user_id": "33333333-3333-3333-3333-333333333333",
    "access_method": "mobile_key",
    "starts_at": "2024-07-13T16:50:42Z",
    "ends_at": "2024-07-18T16:50:42Z",
    ...
  }
  {
    "acs_entrance_id": "55555555-5555-5555-5555-555555555555",
    "display_name": "Room Entrance",
    ...
  }
  {
    "acs_entrance_id": "55555555-5555-5555-5555-000000000000",
    "display_name": "Common Door Entrance",
    ...
  }
  ```
</CodeGroup>

***

## Next Steps

To learn more about using the Seam API with your Latch ACS, see the following topics:

* [Programming PIN Codes for Latch ACS Users](./programming-code-based-latch-credentials)
* [Access Control Systems](/low-level-apis/access-systems)
* [Credential-based ACS](/low-level-apis/access-systems/connect-an-acs-to-seam/understanding-access-control-system-differences)
* [Managing ACS Users](/low-level-apis/access-systems/user-management)
* [Managing Credentials](/low-level-apis/access-systems/managing-credentials)
* [Mobile Access](/capability-guides/mobile-access)
* [Access Control Systems](/api/acs/object) in the Seam API reference
* [User Identities](/api/user_identities/object) in the Seam API reference


# Sandbox Latch Access Control System
Source: https://docs.seam.co/device-and-system-integration-guides/latch-access-control-system/sandbox-latch-access-control-system

Add a virtual Latch access control system to your Seam sandbox workspace using the Seam Console, with no credentials required, to test your integration.

You do not need to specify any credentials to add a virtual [Latch access control system](/device-and-system-integration-guides/latch-access-control-system) to your Seam [sandbox workspace](/core-concepts/workspaces#sandbox-workspaces).

To add a sandbox Latch access control system using the Seam Console:

1. In the left navigation pane of the [Seam Console](https://console.seam.co/), click **Access Systems**.
2. In the upper-right corner of the **Access Systems** page, click **+ New Access System** to display a Connect Webview.
3. Complete the Connect Webview, making sure to select **Latch** as the access control system that you want to add.\
   For a sandbox Latch access control system, you do not need to contact Seam to complete the connection.


# Creating Lockly Offline Access Codes
Source: https://docs.seam.co/device-and-system-integration-guides/lockly-locks/creating-lockly-offline-access-codes

Learn how to create Lockly offline access codes, including understanding manufacturer-specific requirements.

In addition to supporting [online access codes](/low-level-apis/smart-locks/access-codes), the Seam integration for Lockly supports the generation of offline access codes for all Lockly lock models that have a keypad. You generate offline access (PIN) codes remotely, and the manufacturer maintains a server-based registry of synchronized encryption keys (tokens) to enable these offline codes. Then, owners or managers can share these codes with users through messaging or other similar applications, and the users do not need to install a special application to unlock the device.

For Lockly locks with keypads, you can program [time-bound](/low-level-apis/smart-locks/access-codes/offline-access-codes#creating-time-bound-offline-access-codes) and [one-time-use](/low-level-apis/smart-locks/access-codes/offline-access-codes#creating-one-time-use-offline-access-codes) offline access codes. To define the validity period for each Lockly offline access code, specify the desired `starts_at` and `ends_at` timestamp. You can create as many offline access codes as you'd like, up to the limits of your device memory capacity and your Lockly subscription. You can verify your Lockly subscription in the [Lockly Access Portal](https://lap.lockly.com/lap/index.html#/login).

<Info>
  It is important to inform your Lockly lock users that the mechanism for
  entering offline access codes on Lockly devices is different from the
  mechanism for entering online access codes on these devices. For instructions,
  see
  [https://www.support.lockly.com/faq/how-to-use-oac/](https://www.support.lockly.com/faq/how-to-use-oac/).&#x20;
</Info>

For more information about using offline access codes, see [Offline Access Codes](/low-level-apis/smart-locks/access-codes#offline-access-codes) and [Managing Offline Access Codes](/low-level-apis/smart-locks/access-codes/offline-access-codes).

***

## Programming Lockly Offline Access Codes

For detailed instructions for creating time-bound offline access codes for Lockly locks, see [Creating Time-Bound Offline Access Codes](/low-level-apis/smart-locks/access-codes/offline-access-codes#creating-time-bound-offline-access-codes).

For detailed instructions for creating one-time-use offline access codes for Lockly locks, see [Creating One-Time-Use Offline Access Codes](/low-level-apis/smart-locks/access-codes/offline-access-codes#creating-one-time-use-offline-access-codes).


# Lockly Locks
Source: https://docs.seam.co/device-and-system-integration-guides/lockly-locks/index

Guide for using Lockly smart locks with Seam

<img alt="Lockly logo" />

## Overview

Seam integrates with Lockly smart locks. With a focus on security, Lockly smart locks work with a vast array of door types, such as traditional deadbolts, latch bolts, and patio doors. In addition, Lockly smart locks support time-bound and one-time-use [offline access codes](/device-and-system-integration-guides/lockly-locks/creating-lockly-offline-access-codes) that you can issue when you are not connected to your Lockly lock.

<Info>
  **Before you begin**

  Follow the [Lockly Setup Guide](/device-and-system-integration-guides/lockly-locks/lockly-setup-guide) to configure your Lockly account, and connect it to Seam.
</Info>

***

## Supported Devices

<DeviceList />

All Lockly smart locks are supported.

For models without built-in Wi-Fi, a [Secure Link Wi-Fi Hub](https://lockly.com/products/secure-link-wifi-hub) is required.

For detailed information about the Lockly devices that Seam supports, see our [Lockly Supported Devices page](https://www.seam.co/manufacturers/lockly).

***

## Supported Features

We support the following features:

#### Device control

* Lock and unlock actions (online)

#### Access code management

* Online access codes (for Wi-Fi–connected locks)
* Offline, time-bound, and one-time-use PIN codes (for keypad models)
* Custom code lengths between 6 and 8 digits (Lockly requirement)

#### Device monitoring

* Lock status
* Online/offline state
* Battery level (where supported)

***

## Connecting Lockly to Seam

To enable your users to [connect Lockly devices through Connect Webviews](/core-concepts/connect-webviews/customizing-connect-webviews#customize-the-brands-to-display-in-your-connect-webviews), include the Lockly provider:

```json theme={null}
{
}
```

After the Lockly owner completes the LAP setup steps, they can enter their programmatic credentials into the Seam Connect form to complete the connection.

[→ See: Lockly Setup Guide](/device-and-system-integration-guides/lockly-locks/lockly-setup-guide)

***

## Brand-specific notes

* **Access codes:** Lockly requires access codes to be 6–8 digits.
* **Hubs:** Some models require the Lockly Secure Link Wi-Fi Hub.
* **API access:** Lockly Access Portal users must request API enablement from Lockly support.

***

## Next Steps

<CardGroup>
  <Card title="Connect Lockly to Seam" href="/device-and-system-integration-guides/lockly-locks/lockly-setup-guide">
    Follow the setup guide to prepare your Lockly account and enable API access.
  </Card>

  <Card title="Order Locks" href="https://lockly.com/collections/door-lock">
    Purchase Lockly locks directly from their website.
  </Card>
</CardGroup>


# Sandbox Lockly Locks
Source: https://docs.seam.co/device-and-system-integration-guides/lockly-locks/lockly-lock-sample-data

Add virtual Lockly locks to your Seam sandbox workspace using these sample credentials to test your integration without real hardware.

Use the following set of credentials to add virtual [Lockly locks](/device-and-system-integration-guides/lockly-locks) to your Seam [sandbox workspace](/core-concepts/workspaces#sandbox-workspaces):

| Field                  | Value                                       |
| ---------------------- | ------------------------------------------- |
| Email                  | [jane@example.com](mailto:jane@example.com) |
| Team ID (or Client ID) | 1234                                        |
| Access Key ID          | 1234                                        |
| Access Key Secret      | 1234                                        |
| Token ID               | 1234                                        |
| Token Secret           | 1234                                        |


# Lockly Setup Guide
Source: https://docs.seam.co/device-and-system-integration-guides/lockly-locks/lockly-setup-guide

Connect your Lockly devices to Seam by setting up the Lockly mobile app and enabling Sync with LocklyOS for each of your door locks.

To use Seam with Lockly devices, ask the device owner to complete the steps below.

### 1. Set up the Lockly mobile app

1. Download the [Lockly mobile app](https://lockly.com/pages/lockly-home-app) and create an account if you don’t have one.
2. For each Lockly lock:
   * Open the lock’s card.
   * Select **Settings** in the lower-right corner.
   * Select **Sync with LocklyOS** and turn it on.

### 2. Connect Lockly to Seam

After turning on **Sync with LocklyOS** for each door lock, you can complete the connection in Seam:

1. In the form to connect Lockly to Seam, enter the login credentials used in the **Lockly** mobile app.
2. Click **Submit** to complete.

***

### Troubleshooting

If devices don't appear after connecting your account:

* Verify that **Sync with LocklyOS** is enabled for each lock in the Lockly mobile app

If your devices are offline:

* Check that your locks are online in the Lockly mobile app. If they're offline, contact [Lockly support](https://www.support.lockly.com/contact-us/) for assistance.


# Get started with Minut Sensors
Source: https://docs.seam.co/device-and-system-integration-guides/minut-sensors/get-started-with-minut-sensors

Learn how to connect and control your Minut sensors with the Seam API

## Overview

Seam provides a universal API to connect and control many brands of devices such as smart locks, thermostats, and sensors. This guide provides a rapid introduction to connecting and controlling your [Minut](https://www.seam.co/manufacturers/minut) sensors using the Seam API. To learn more about other brands of devices supported by Seam, head over to our [integration page](https://www.seam.co/supported-devices-and-systems).

## 1. Install Seam SDK

Seam provides client libraries for many languages, such as JavaScript, Python, Ruby, PHP, and others, as well as a Postman collection and [OpenAPI](https://connect.getseam.com/openapi.json) spec.

* JavaScript / TypeScript ([npm](https://www.npmjs.com/package/seam), [GitHub](https://github.com/seamapi/javascript))
* Python ([pip](https://pypi.org/project/seam/), [GitHub](https://github.com/seamapi/python))
* Ruby Gem ([rubygem](https://rubygems.org/gems/seam), [GitHub](https://github.com/seamapi/ruby))
* PHP ([packagist](https://packagist.org/packages/seamapi/seam), [GitHub](https://github.com/seamapi/php))
* C# ([nuget](https://www.nuget.org/packages/Seam), [GitHub](https://github.com/seamapi/csharp))

<Tabs>
  <Tab title="JavaScript">
    ```bash theme={null}
    npm i seam
    ```
  </Tab>

  <Tab title="Python">
    ```bash theme={null}
    pip install seam
    # For some development environments, use pip3 in this command instead of pip.
    ```
  </Tab>

  <Tab title="Ruby">
    ```bash theme={null}
    bundle add seam
    ```
  </Tab>

  <Tab title="PHP">
    ```bash theme={null}
    composer require seamapi/seam
    ```
  </Tab>

  <Tab title="C#">
    Install using [nuget](https://www.nuget.org/packages/Seam).
  </Tab>
</Tabs>

Once installed, [sign-up for Seam](https://console.seam.co/) to get your API key, and export it as an environment variable:

```
$ export SEAM_API_KEY=seam_test2ZTo_0mEYQW2TvNDCxG5Atpj85Ffw
```

<Info>
  This guide uses a Sandbox Workspace. Only virtual sensors can be connected. If
  you need to connect a real Minut sensor, use a non-sandbox workspace and API
  key.
</Info>

## 2. Link Minut Account with Seam

To control your Minut sensor via the Seam API, you must first authorize your Seam workspace against your Minut account. To do so, Seam provides[ Connect Webviews](/core-concepts/connect-webviews): pre-built UX flows that walk you through authorizing your application to control your Minut sensor.

### Create a Connect Webview

<CodeGroup>
  ```javascript JavaScript theme={null}
  import { Seam } from 'seam'
  const seam = new Seam()
  const connectWebview = await seam.connectWebviews.create()
  console.log(connectWebview.login_successful) // false
  // Send the webview URL to your user
  console.log(connectWebview.url)
  ```

  ```python Python theme={null}
  from seam import Seam
  seam = Seam()

  webview = seam.connect_webviews.create()

  assert webview.login_successful is False

  # Send this webview url to your user!

  print(webview.url)

  ```

  ```ruby Ruby theme={null}
  require "seam"

  seam = Seam.new(api_key: "MY_API_KEY")

  webview = seam.connect_webviews.create()

  puts webview.login_successful # false

  # Send the webview URL to your user
  puts webview.url
  ```

  ```php PHP theme={null}
  use Seam\SeamClient;
  $seam = new SeamClient("YOUR_API_KEY");
  $webview = $seam->connect_webviews->create();
  echo json_encode($webview)
  /*
  {"connect_webview_id":"70c4df9e-1070-441f-92f8-fd6524062cec","workspace_id":"d7418ff3-a476-4f48-9a4b-211d1d21a03d","url":"https:\/\/connect.getseam.com\/connect_webviews\/view?connect_webview_id=70c4df9e-1070-441f-92f8-fd6524062cec&auth_token=9HJbwWKbD5aJLifZcozU9WWZXxropn9Bg","connected_account_id":null,"status":"pending","custom_redirect_url":null,"custom_redirect_failure_url":null,"created_at":"2023-02-09T02:14:06.147745+00:00","error":null}
  */
  ```
</CodeGroup>

### Authorize Your Workspace

Navigate to the URL returned by the Webview object. Since you are using a sandbox workspace, complete the login flow by entering the Minut [sandbox test accounts ](./minut-noise-sensor-sample-data)credentials below:

* **email**: [jane@example.com](mailto:jane@example.com)
* **password**: 1234

<img alt="Seam Connect Webview flow to connect Minut account with Seam" />

### Get the New Webview

After you complete the login above, you'll get an event for [`connected_account.created`](/api/connected_accounts/events#connected_account-created)if you set up a [webhook handler](/developer-tools/webhooks). Otherwise you can just poll for the webview until it's status changes, as shown below:

<CodeGroup>
  ```javascript JavaScript theme={null}
  const updatedWebview = await seam.connectWebviews.get(
    connectWebview.connect_webview_id,
  )
  console.log(updatedWebview.login_successful) // true
  ```

  ```python Python theme={null}
  updated_webview = seam.connect_webviews.get(
      webview.connect_webview_id
  )

  assert updated_webview.login_successful # true

  ```

  ```ruby Ruby theme={null}
  updated_webview = seam.connect_webviews.get(connect_webview_id: webview.connect_webview_id)
  puts updated_webview.login_successful # true
  ```

  ```php PHP theme={null}
  $webview = $seam->connect_webviews->get($webview->id);
  echo json_encode($webview);
  ```
</CodeGroup>

## 3. Retrieve Minut Noise Sensors

Minut noise sensors appear with the `device_type` `"minut_sensor"`. The Minut noise sensors report properties in addition to noise levels, namely `temperature` and `humidity`.

<CodeGroup>
  ```javascript JavaScript theme={null}
  const devices = await seam.devices.list({
    device_type: 'minut_sensor',
  })
  console.log(devices[0])
  /*
  {
    "device_id": "1efc294e-3a85-403a-8a2a-21b8f8b27cfa",
    "device_type": "minut_sensor",
    "capabilities_supported": [
      "noise_detection"
    ],
    "properties": {
      "online": true,
      "manufacturer": "minut",
      "battery_level": 1,
      "minut_metadata": {
        "home_id": "f53026ff7c5e314521f285f9",
        "device_id": "e0d8283f314c5ad10b82571e",
        "home_name": "Jane's Test Home",
        "device_name": "Living Room",
        "home_address": {
          "city": "San Francisco",
          "notes": "string",
          "region": "San Francisco County",
          "country": "US",
          "post_code": "44210",
          "street_name1": "2258 24th Street",
          "street_name2": ""
        },
        "home_location": {
          "latitude": 0,
          "longitude": 0
        },
        "device_location": {
          "latitude": 0,
          "longitude": 0
        },
        "latest_sensor_values": {
          "sound": {
            "time": "1970-01-01T00:00:00.000Z",
            "value": 47.7117919921875
          },
          "humidity": {
            "time": "1970-01-01T00:00:00.000Z",
            "value": 31.110000610351562
          },
          "pressure": {
            "time": "1970-01-01T00:00:00.000Z",
            "value": 101923
          },
          "temperature": {
            "time": "1970-01-01T00:00:00.000Z",
            "value": 21.270000457763672
          },
          "accelerometer_z": {
            "time": "1970-01-01T00:00:00.000Z",
            "value": -1.00390625
          }
        }
      },
      "name": "Living Room",
      "battery": {
        "level": 1,
        "status": "full"
      },
      "image_url": "https://connect.getseam.com/assets/images/devices/minut_gen-3_front.png",
      "image_alt_text": "Minut Sensor"
    },
    "location": {
      "timezone": "America/Los_Angeles",
      "location_name": "Jane's Test Home"
    },
    "connected_account_id": "257160cb-c2f0-4ee0-9c76-be80b3751f28",
    "workspace_id": "2c5f5397-37b9-4236-beac-f47f050d42cd",
    "created_at": "2023-05-08T17:01:43.650Z",
    "errors": [],
    "warnings": []
  }
  */
  ```

  ```python Python theme={null}
  sensors = seam.devices.list(device_type="minut_sensor")

  sensors[0]

  # Device(

  # device_id='fd200f4b-3815-497a-8520-10725c597e0c',

  # device_type='minut_sensor',

  # location={

  # 'timezone': 'America/Los_Angeles',

  # 'location_name': "Jane's Test Home"

  # },

  # properties={

  # 'online': True,

  # 'manufacturer': 'minut',

  # 'battery_level': 0.5,

  # 'minut_metadata': {

  # 'home_id': 'f53026ff7c5e314521f285f9',

  # 'device_id': '5bb32b83525d243950a92ab8',

  # 'home_name': "Jane's Test Home",

  # 'device_name': 'Living Room',

  # 'home_address': {

  # 'city': 'San Francisco',

  # 'notes': 'string',

  # 'region': 'San Francisco County',

  # 'country': 'US',

  # 'post_code': '44210',

  # 'street_name1': '2258 24th Street',

  # 'street_name2': ''

  # },

  # 'home_location': {

  # 'latitude': 0,

  # 'longitude': 0

  # },

  # 'device_location': {

  # 'latitude': 0,

  # 'longitude': 0

  # },

  # 'latest_sensor_values': {

  # 'sound': {

  # 'time': '1970-01-01T00:00:00.000Z',

  # 'value': 47.7117919921875

  # },

  # 'humidity': {

  # 'time': '1970-01-01T00:00:00.000Z',

  # 'value': 31.110000610351562

  # },

  # 'pressure': {

  # 'time': '1970-01-01T00:00:00.000Z',

  # 'value': 101923

  # },

  # 'temperature': {

  # 'time': '1970-01-01T00:00:00.000Z',

  # 'value': 21.270000457763672

  # },

  # 'accelerometer_z': {

  # 'time': '1970-01-01T00:00:00.000Z',

  # 'value': -1.00390625

  # }

  # }

  # },

  # 'name': 'Living Room',

  # 'battery': {

  # 'level': 0.5,

  # 'status': 'good'

  # },

  # 'image_url': 'https://connect.getseam.com/assets/images/devices/minut_gen-3_front.png',

  # 'image_alt_text': 'Minut Sensor'

  # },

  # capabilities_supported=['noise_detection'],

  # errors=[]

  # )

  ```

  ```ruby Ruby theme={null}
  seam.devices.list(
    device_type: "minut_sensor"
  ).first
  # <Seam::Device:0x00c08
  #   device_id="01e6c107-9855-48ec-ae66-d0e839302492"
  #   device_type="minut_sensor"
  #   properties={
  #     "online"=>true,
  #     "manufacturer"=>"minut",
  #     "battery_level"=>1,
  #     "minut_metadata"=>{
  #       "home_id"=>"2978b6d5dba395ec08300e45",
  #       "device_id"=>"770bd3153deca3dee0fe0614",
  #       "home_name"=>"Jane's Test Home",
  #       "device_name"=>"Living Room",
  #       "home_address"=>{
  #         "city"=>"San Francisco",
  #         "notes"=>"string",
  #         "region"=>"San Francisco County",
  #         "country"=>"US",
  #         "post_code"=>"44210",
  #         "street_name1"=>"2258 24th Street",
  #         "street_name2"=>""
  #       },
  #       "home_location"=>{
  #         "latitude"=>0,
  #         "longitude"=>0
  #       },
  #       "device_location"=>{
  #         "latitude"=>0,
  #         "longitude"=>0
  #       },
  #       "latest_sensor_values"=>{
  #         "sound"=>{
  #           "time"=>"1970-01-01T00:00:00.000Z",
  #           "value"=>47.7117919921875
  #         },
  #         "humidity"=>{
  #           "time"=>"1970-01-01T00:00:00.000Z",
  #           "value"=>31.110000610351562
  #         },
  #         "pressure"=>{
  #           "time"=>"1970-01-01T00:00:00.000Z",
  #           "value"=>101923
  #         },
  #         "temperature"=>{
  #           "time"=>"1970-01-01T00:00:00.000Z",
  #           "value"=>21.270000457763672
  #         },
  #         "accelerometer_z"=>{
  #           "time"=>"1970-01-01T00:00:00.000Z",
  #           "value"=>-1.00390625
  #         }
  #       }
  #     },
  #     "name"=>"Living Room",
  #     "battery"=>{
  #       "level"=>1,
  #       "status"=>"full"
  #     },
  #     "image_url"=>"https://connect.getseam.com/assets/images/devices/minut_gen-3_front.png",
  #     "image_alt_text"=>"Minut Sensor"
  #   }
  #   created_at=2023-05-08 17:01:45.79 UTC
  #   errors=[]
  #   warnings=[]>
  ```

  ```php PHP theme={null}
  $devices = $seam->devices->list(device_type: 'minut_sensor');
  echo json_encode($device[0]);
  /*
  {
    "device_id": "1efc294e-3a85-403a-8a2a-21b8f8b27cfa",
    "device_type": "minut_sensor",
    "capabilities_supported": [
      "noise_detection"
    ],
    "properties": {
      "online": true,
      "manufacturer": "minut",
      "battery_level": 1,
      "minut_metadata": {
        "home_id": "f53026ff7c5e314521f285f9",
        "device_id": "e0d8283f314c5ad10b82571e",
        "home_name": "Jane's Test Home",
        "device_name": "Living Room",
        "home_address": {
          "city": "San Francisco",
          "notes": "string",
          "region": "San Francisco County",
          "country": "US",
          "post_code": "44210",
          "street_name1": "2258 24th Street",
          "street_name2": ""
        },
        "home_location": {
          "latitude": 0,
          "longitude": 0
        },
        "device_location": {
          "latitude": 0,
          "longitude": 0
        },
        "latest_sensor_values": {
          "sound": {
            "time": "1970-01-01T00:00:00.000Z",
            "value": 47.7117919921875
          },
          "humidity": {
            "time": "1970-01-01T00:00:00.000Z",
            "value": 31.110000610351562
          },
          "pressure": {
            "time": "1970-01-01T00:00:00.000Z",
            "value": 101923
          },
          "temperature": {
            "time": "1970-01-01T00:00:00.000Z",
            "value": 21.270000457763672
          },
          "accelerometer_z": {
            "time": "1970-01-01T00:00:00.000Z",
            "value": -1.00390625
          }
        }
      },
      "name": "Living Room",
      "battery": {
        "level": 1,
        "status": "full"
      },
      "image_url": "https://connect.getseam.com/assets/images/devices/minut_gen-3_front.png",
      "image_alt_text": "Minut Sensor"
    },
    "location": {
      "timezone": "America/Los_Angeles",
      "location_name": "Jane's Test Home"
    },
    "connected_account_id": "257160cb-c2f0-4ee0-9c76-be80b3751f28",
    "workspace_id": "2c5f5397-37b9-4236-beac-f47f050d42cd",
    "created_at": "2023-05-08T17:01:43.650Z",
    "errors": [],
    "warnings": []
  }
  */
  ```
</CodeGroup>

## 4. Receive Noise Events

Minut users can define noise thresholds at which noise alerts are sent.

You'll get an event for `noise_threshold.noise_threshold_triggered` when you set up a webhook handler. You can also [poll for events](/api/events/list).

<Info>
  Minut has a builtin threshold that can be triggered multiple times. Each Minut notice will trigger a `noise_threshold_triggered` event with the `minut_metadata.event_name` containing the Minut event name, which can be any of the following:

  * `disturbance_first_notice`
  * `disturbance_second_notice`
  * `disturbance_third_notice`
  * `disturbance_ended`
</Info>

<CodeGroup>
  ```javascript JavaScript theme={null}
  app.post('/my_webhook_endpoint', (req, res) => {
    const event = req.body.event;
    // {
    // "event_id": "d8ffcf85-73f7-4383-b832-ed65db93c802",
    // "device_id": "617415c6-2aa4-43ac-b436-879951f891b0",
    // "event_type": "noise_sensor.noise_threshold_triggered",
    // "workspace_id": "2c5f5397-37b9-4236-beac-f47f050d42cd",
    // "created_at": "2023-03-14T05:00:35.451Z"
    // "occurred_at": "2023-05-20T00:01:31.273Z",
    // "minut_metadata": {
    //   "minut_event_id": "2690d0909b90a06e1ceac185"
    //   "minut_event_type": "disturbance_first_notice"
    //   "minut_home_id": "f53026ff7c5e314521f285f9",
    //   "minut_user_id": "d3bd127911d71d7d7da85bd3"
    // }
  });
  ```

  ```python Python theme={null}
  @app.route("/my_webhook_endpoint", methods=["POST"])
  def endpoint():
      event = request.json["event"]
      # {
      #    noise_threshold_id: "...",
      #    noise_threshold_name: "builtin_disturbance"
      #    minut_metadata: {
      #       "event_name": "disturbance_first_notice",
      #    },
      #    device_id: "...";
      #    noise_level_decibels: 40,
      #    created_at: "2023-03-14T05:00:35.451Z"
      # }

  ```

  ```ruby Ruby theme={null}
  post '/my_webhook_endpoint' do
    request.body.rewind
    payload = JSON.parse(request.body.read)
    event = payload['event']
    # {
    #   "event_id": "d8ffcf85-73f7-4383-b832-ed65db93c802",
    #   "device_id": "617415c6-2aa4-43ac-b436-879951f891b0",
    #   "event_type": "noise_sensor.noise_threshold_triggered",
    #   "workspace_id": "2c5f5397-37b9-4236-beac-f47f050d42cd",
    #   "created_at": "2023-03-14T05:00:35.451Z"
    #   "occurred_at": "2023-05-20T00:01:31.273Z",
    #   "noiseaware_metadata": {
    #     "minut_event_id": "2690d0909b90a06e1ceac185"
    #     "minut_event_type": "disturbance_first_notice"
    #     "minut_home_id": "f53026ff7c5e314521f285f9",
    #     "minut_user_id": "d3bd127911d71d7d7da85bd3"
    #   }
    # }
  end
  ```

  ```php PHP theme={null}
  $app->post('/my_webhook_endpoint', function (Request $request, Response $response) {
      $data = $request->getParsedBody();
      $event = $data['event'];
      // {
      // "event_id": "d8ffcf85-73f7-4383-b832-ed65db93c802",
      // "device_id": "617415c6-2aa4-43ac-b436-879951f891b0",
      // "event_type": "noise_sensor.noise_threshold_triggered",
      // "workspace_id": "2c5f5397-37b9-4236-beac-f47f050d42cd",
      // "created_at": "2023-03-14T05:00:35.451Z",
      // "occurred_at": "2023-05-20T00:01:31.273Z",
      // "minut_metadata": {
      //   "minut_event_id": "2690d0909b90a06e1ceac185"
      //   "minut_event_type": "disturbance_first_notice"
      //   "minut_home_id": "f53026ff7c5e314521f285f9",
      //   "minut_user_id": "d3bd127911d71d7d7da85bd3"
      // }
  });
  ```
</CodeGroup>

## Next Steps

Now that you've completed this guide, you can try to connect a real Minut device. To do so, make sure to switch to a non-sandbox workspace and API key as real devices cannot be connected to sandbox workspaces.

If you have any questions or want to report an issue, email us at [support@seam.co](mailto:support@seam.co)


# Minut Sensors
Source: https://docs.seam.co/device-and-system-integration-guides/minut-sensors/index

Guide for using Minut sensors with Seam

<img alt="Minut logo" />

## Overview

Seam integrates with the Minut sensor to provide noise monitoring functions for the rental property and vacation rental industries. This camera-free, privacy-safe sensor notifies owners when guest noise levels exceed configured thresholds. In addition, the Minut sensor is weatherproof and, consequently, suitable for both outdoor and indoor use. For each Minut sensor, you can configure a regular noise threshold and an optional quiet hours threshold.

***

## Supported Devices

<DeviceList />

This integration supports the [Minut sensor](https://www.minut.com/product/features).

For detailed information about the Minut devices that Seam supports, see our [Minut Supported Devices page](https://www.seam.co/manufacturers/minut).

***

## Supported Features

We support the following features:

* [Configuring noise threshold settings](/capability-guides/noise-sensors/configure-noise-threshold-settings)\
  You can configure a maximum of two noise thresholds per Minut sensor. The first threshold is required and represents the regular threshold for the whole day. The second threshold is optional and represents the threshold for the quiet hours timeframe.
* [Receiving noise sensor events when noise events occur](/api/noise_sensors/noise_thresholds/events)\
  For more information, see the [`noise_sensor.noise_threshold_triggered` event](/api/noise_sensors/noise_thresholds/events#noise_sensor-noise_threshold_triggered).

***

### Device Provider Key

Seam identifies these devices with the `minut` device provider key. By default, a [Connect Webview](/core-concepts/connect-webviews) displays all of the stable providers that Seam supports, so your users can connect their Minut devices without you specifying a provider list. To narrow what a Connect Webview displays, see [Customize the Brands to Display in Your Connect Webviews](/core-concepts/connect-webviews/customizing-connect-webviews#customize-the-brands-to-display-in-your-connect-webviews).

***

## Setup Instructions

For instructions on connecting Minut sensors to Seam, see the [Minut Setup Guide](./minut-setup-guide).

***

## Where to Order

To purchase Minut sensors, visit the Minut online store.

<table>
  <thead>
    <tr>
      <th />

      <th />

      <th />

      <th />

      <th />
    </tr>
  </thead>

  <tbody>
    <tr>
      <td />

      <td>
        <strong>Minut Online Store</strong>
      </td>

      <td />

      <td>
        <a href="https://store.minut.com/">[https://store.minut.com/](https://store.minut.com/)</a>
      </td>

      <td />
    </tr>
  </tbody>
</table>

***


# Sandbox Minut Sensors
Source: https://docs.seam.co/device-and-system-integration-guides/minut-sensors/minut-noise-sensor-sample-data

Add virtual Minut sensors to your Seam sandbox workspace using these sample credentials to test your integration without real hardware.

Use either of the following sets of credentials to add virtual [Minut sensors](/device-and-system-integration-guides/minut-sensors) to your Seam [sandbox workspace](/core-concepts/workspaces#sandbox-workspaces):

| Email Address                                                                              | Password |
| ------------------------------------------------------------------------------------------ | -------- |
| [jane@example.com](mailto:jane@example.com) or any email address in the example.com domain | 1234     |


# Minut Setup Guide
Source: https://docs.seam.co/device-and-system-integration-guides/minut-sensors/minut-setup-guide

Connect your Minut sensors to Seam.

## Overview

This guide walks you through connecting your Minut noise sensors to Seam. Your sensors must already be set up and working in the Minut app before proceeding.

***

## Step 1: Confirm Your Minut Account

1. Create an account in the [Minut app](https://www.minut.com/setup) if you have not done so already.
2. In the Minut app, confirm that your Minut sensors are added and online.
3. Note your login credentials for the Minut app.

***

## Step 2: Connect to Seam via Connect Webview

1. Open the [Connect Webview](/core-concepts/connect-webviews) provided by your application.
2. Select Minut as the provider.
3. Enter your Minut app login credentials.
4. Once authorized, your Minut sensors appear as devices in Seam.

***

## Step 3: Verify the Connection

After connecting, verify that your Minut sensors appear as devices and show as online with noise monitoring capabilities.

***

## Troubleshooting

### Authorization fails in Connect Webview

Make sure you are using the same email and password that you use to log in to the Minut app. If you recently changed your password, use the updated credentials.

### Sensors not appearing after authorization

Ensure your Minut sensors are added and online in the Minut app. Only sensors that are set up in the app are visible to Seam.

### Sensor shows as offline

Check that the sensor has power and is connected to Wi-Fi. Open the Minut app to verify the sensor's connection status.


# Get started with NoiseAware Sensors
Source: https://docs.seam.co/device-and-system-integration-guides/noiseaware-sensors/get-started-with-noiseaware-sensors

Learn how to connect and control your NoiseAware devices with the Seam API

## Overview

Seam provides a universal API to connect and control many brands of devices such as smart locks, thermostats, and sensors. This guide provides a rapid introduction to connecting and controlling your [NoiseAware](https://www.seam.co/manufacturers/noiseaware) devices (called "activity zones" by NoiseAware) using the Seam API. To learn more about other brands of devices supported by Seam, head over to our [integration page](https://www.seam.co/supported-devices-and-systems).

To simplify the examples below, we'll use the following modules and utility variables:

## 1. Install Seam SDK

Seam provides client libraries for many languages, such as JavaScript, Python, Ruby, PHP, and others, as well as a Postman collection and [OpenAPI](https://connect.getseam.com/openapi.json) spec.

* JavaScript / TypeScript ([npm](https://www.npmjs.com/package/seam), [GitHub](https://github.com/seamapi/javascript))
* Python ([pip](https://pypi.org/project/seam/), [GitHub](https://github.com/seamapi/python))
* Ruby Gem ([rubygem](https://rubygems.org/gems/seam), [GitHub](https://github.com/seamapi/ruby))
* PHP ([packagist](https://packagist.org/packages/seamapi/seam), [GitHub](https://github.com/seamapi/php))
* C# ([nuget](https://www.nuget.org/packages/Seam), [GitHub](https://github.com/seamapi/csharp))

<Tabs>
  <Tab title="JavaScript">
    ```bash theme={null}
    npm i seam
    ```
  </Tab>

  <Tab title="Python">
    ```bash theme={null}
    pip install seam
    # For some development environments, use pip3 in this command instead of pip.
    ```
  </Tab>

  <Tab title="Ruby">
    ```bash theme={null}
    bundle add seam
    ```
  </Tab>

  <Tab title="PHP">
    ```bash theme={null}
    composer require seamapi/seam
    ```
  </Tab>

  <Tab title="C#">
    Install using [nuget](https://www.nuget.org/packages/Seam).
  </Tab>
</Tabs>

Once installed, [sign-up for Seam](https://console.seam.co/) to get your API key, and export it as an environment variable:

```
$ export SEAM_API_KEY=seam_test2ZTo_0mEYQW2TvNDCxG5Atpj85Ffw
```

<Info>
  This guide uses a Sandbox Workspace. Only virtual activity zones can be
  connected. If you need to connect a real Noiseaware device, use a non-sandbox
  workspace and API key.
</Info>

## 2. Link NoiseAware Account with Seam

To control your NoiseAware device via the Seam API, you must first authorize your Seam workspace against your NoiseAware account. To do so, Seam provides[ Connect Webviews](/core-concepts/connect-webviews): pre-built UX flows that walk you through authorizing your application to control your NoiseAware device.

### Create a Connect Webview

<CodeGroup>
  ```javascript JavaScript theme={null}
  import { Seam } from 'seam'

  const seam = new Seam()

  const connectWebview = await seam.connectWebviews.create()

  console.log(connectWebview.login_successful) // false

  // Send the webview URL to your user
  console.log(connectWebview.url)

  ```

  ```python Python theme={null}
  from seam import Seam
  seam = Seam()

  webview = seam.connect_webviews.create()

  assert webview.login_successful is False

  # Send this webview url to your user!
  print(webview.url)
  ```

  ```ruby Ruby theme={null}
  require "seam"

  seam = Seam.new(api_key: "MY_API_KEY")

  webview = seam.connect_webviews.create()

  puts webview.login_successful # false

  # Send the webview URL to your user

  puts webview.url

  ```

  ```php PHP theme={null}
  use Seam\SeamClient;

  $seam = new SeamClient("YOUR_API_KEY");

  $webview = $seam->connect_webviews->create();

  echo json_encode($webview)
  /*
  {"connect_webview_id":"70c4df9e-1070-441f-92f8-fd6524062cec","workspace_id":"d7418ff3-a476-4f48-9a4b-211d1d21a03d","url":"https:\/\/connect.getseam.com\/connect_webviews\/view?connect_webview_id=70c4df9e-1070-441f-92f8-fd6524062cec&auth_token=9HJbwWKbD5aJLifZcozU9WWZXxropn9Bg","connected_account_id":null,"status":"pending","custom_redirect_url":null,"custom_redirect_failure_url":null,"created_at":"2023-02-09T02:14:06.147745+00:00","error":null}
  */
  ```
</CodeGroup>

### Authorize Your Workspace

Navigate to the URL returned by the Webview object. Since you are using a sandbox workspace, complete the login flow by entering the NoiseAware [sandbox test accounts ](./noiseaware-sample-data)credentials below:

* **email**: [jane@example.com](mailto:jane@example.com)
* **password**: 1234

<img alt="Seam Connect Webview flow to connect NoiseAware account with Seam" />

### Get the New Webview

After you complete the login above, you'll get an event for [`connected_account.created`](/api/connected_accounts/events#connected_account-created)if you set up a [webhook handler](/developer-tools/webhooks). Otherwise you can just poll for the webview until it's status changes, as shown below:

<CodeGroup>
  ```javascript JavaScript theme={null}
  const updatedWebview = await seam.connectWebviews.get(
    connectWebview.connect_webview_id,
  )

  console.log(updatedWebview.login_successful) // true

  ```

  ```python Python theme={null}
  updated_webview = seam.connect_webviews.get(
      webview.connect_webview_id
  )

  assert updated_webview.login_successful # true
  ```

  ```ruby Ruby theme={null}
  updated_webview = seam.connect_webviews.get(connect_webview_id: webview.connect_webview_id)

  puts updated_webview.login_successful # true

  ```

  ```php PHP theme={null}
  $webview = $seam->connect_webviews->get($webview->id);
  echo json_encode($webview);
  ```
</CodeGroup>

## 3. Retrieve NoiseAware

NoiseAware noise devices appear with the `device_type` `"noiseaware_activity_zone"`.

<CodeGroup>
  ```javascript JavaScript theme={null}
  const devices = await seam.devices.list({
    device_type: 'noiseaware_activity_zone',
  })

  console.log(devices[0])
  /_
  {
  device_id: '617415c6-2aa4-43ac-b436-879951f891b0',
  device_type: 'noiseaware_activity_zone',
  capabilities_supported: [ 'noise_detection' ],
  properties: {
  online: true,
  manufacturer: 'noiseaware',
  has_direct_power: true,
  noiseaware_metadata: {
  device_id: '98765',
  device_name: 'Conference Room',
  noise_level_nrs: 0,
  noise_level_decibel: 2
  },
  name: 'Conference Room',
  image_url: 'https://connect.getseam.com/assets/images/devices/noiseaware_logo_square.png',
  image_alt_text: 'NoiseAware Noise Sensor'
  },
  location: null,
  connected_account_id: 'cf7d41f9-cdbb-444a-b3f0-5a8143727dbd',
  workspace_id: '2c5f5397-37b9-4236-beac-f47f050d42cd',
  created_at: '2023-05-19T20:06:10.789Z',
  errors: [],
  warnings: []
  }
  _/

  ```

  ```python Python theme={null}
  devices = seam.devices.list(device_type="noiseaware_activity_zone")

  devices[0]
  # Device(
  # Device(
  #   device_id="617415c6-2aa4-43ac-b436-879951f891b0",
  #   device_type="noiseaware_activity_zone",
  #   location=None,
  #   properties={
  #     "online": True,
  #     "manufacturer": "noiseaware",
  #     "has_direct_power": True,
  #     "noiseaware_metadata": {
  #       "device_id": "98765",
  #       "device_name": "Conference Room",
  #       "noise_level_nrs": 0,
  #       "noise_level_decibel": 2},
  #       "name": "Conference Room",
  #       "image_url": "https://connect.getseam.com/assets/images/devices/noiseaware_logo_square.png",
  #       "image_alt_text": "NoiseAware Noise Sensor"
  #     },
  #     capabilities_supported=["noise_detection"],
  #   errors=[]
  # )
  ```

  ```ruby Ruby theme={null}
  seam.devices.list(
    device_type: "noiseaware_activity_zone"
  ).first

  # <Seam::Device:0x00be0

  # device_id="617415c6-2aa4-43ac-b436-879951f891b0"

  # device_type="noiseaware_activity_zone"

  # properties={

  # "online"=>true,

  # "manufacturer"=>"noiseaware",

  # "has_direct_power"=>true,

  # "noiseaware_metadata"=>{

  # "device_id"=>"98765",

  # "device_name"=>"Conference Room",

  # "noise_level_nrs"=>0,

  # "noise_level_decibel"=>2

  # },

  # "name"=>"Conference Room",

  # "image_url"=>"https://connect.getseam.com/assets/images/devices/noiseaware_logo_square.png",

  # "image_alt_text"=>"NoiseAware Noise Sensor"

  # }

  # created_at=2023-05-19 20:06:10.789 UTC

  # errors=[]

  # warnings=[]>

  ```

  ```php PHP theme={null}
  $devices = $seam->devices->list(device_type: 'noiseaware_activity_zone');

  echo json_encode($device[0]);
  /*
  {
    device_id: '617415c6-2aa4-43ac-b436-879951f891b0',
    device_type: 'noiseaware_activity_zone',
    capabilities_supported: [ 'noise_detection' ],
    properties: {
      online: true,
      manufacturer: 'noiseaware',
      has_direct_power: true,
      noiseaware_metadata: {
        device_id: '98765',
        device_name: 'Conference Room',
        noise_level_nrs: 0,
        noise_level_decibel: 2
      },
      name: 'Conference Room',
      image_url: 'https://connect.getseam.com/assets/images/devices/noiseaware_logo_square.png',
      image_alt_text: 'NoiseAware Noise Sensor'
    },
    location: null,
    connected_account_id: 'cf7d41f9-cdbb-444a-b3f0-5a8143727dbd',
    workspace_id: '2c5f5397-37b9-4236-beac-f47f050d42cd',
    created_at: '2023-05-19T20:06:10.789Z',
    errors: [],
    warnings: []
  }
  */
  ```
</CodeGroup>

## 4. Receive Noise Events

NoiseAware users can define noise thresholds at which noise alerts are sent.

You'll get an event for `noise_threshold.noise_threshold_triggered` when you set up a webhook handler. You can also [poll for events](/api/events/list).

<Info>
  NoiseAware has three distinct noise alerts: `newNoise`, `continuedNoise`, and
  `resolvedNoise`. It is essential to keep in mind that Seam will solely trigger
  the `noise_threshold.noise_threshold_triggered` event for `newNoise`.
</Info>

<CodeGroup>
  ```javascript JavaScript theme={null}
  app.post('/my_webhook_endpoint', (req, res) => {
    const event = req.body.event;
    // {
    // "event_id": "d8ffcf85-73f7-4383-b832-ed65db93c802",
    // "device_id": "617415c6-2aa4-43ac-b436-879951f891b0",
    // "event_type": "noise_sensor.noise_threshold_triggered",
    // "workspace_id": "2c5f5397-37b9-4236-beac-f47f050d42cd",
    // "created_at": "2023-03-14T05:00:35.451Z"
    // "occurred_at": "2023-05-20T00:01:31.273Z",
    // "noiseaware_metadata": {
    //   "noiseaware_alert_info": "ALERT: Noise Sensors at [PropertyName] has sustained noise above the NRS threshold. dashboard.noiseaware.io/properties/[APIKey]",
    //   "noiseaware_alert_time": "2023-05-20T00:01:31.180Z",
    //   "noiseaware_alert_type": "newNoise",
    //   "noiseaware_property_id": 12345,
    //   "noiseaware_property_name": "Acme Corporation"
    // }
  });
  ```

  ```python Python theme={null}
  @app.route("/my_webhook_endpoint", methods=["POST"])
  def endpoint():
      event = request.json["event"]
      # {
      # "event_id": "d8ffcf85-73f7-4383-b832-ed65db93c802",
      # "device_id": "617415c6-2aa4-43ac-b436-879951f891b0",
      # "event_type": "noise_sensor.noise_threshold_triggered",
      # "workspace_id": "2c5f5397-37b9-4236-beac-f47f050d42cd",
      # "created_at": "2023-03-14T05:00:35.451Z"
      # "occurred_at": "2023-05-20T00:01:31.273Z",
      # "noiseaware_metadata": {
      #   "noiseaware_alert_info": "ALERT: Noise Sensors at [PropertyName] has sustained noise above the NRS threshold. dashboard.noiseaware.io/properties/[APIKey]",
      #   "noiseaware_alert_time": "2023-05-20T00:01:31.180Z",
      #   "noiseaware_alert_type": "newNoise",
      #   "noiseaware_property_id": 12345,
      #   "noiseaware_property_name": "Acme Corporation"
      # }

  ```

  ```ruby Ruby theme={null}
  post '/my_webhook_endpoint' do
    request.body.rewind
    payload = JSON.parse(request.body.read)
    event = payload['event']
    # {
    #   "event_id": "d8ffcf85-73f7-4383-b832-ed65db93c802",
    #   "device_id": "617415c6-2aa4-43ac-b436-879951f891b0",
    #   "event_type": "noise_sensor.noise_threshold_triggered",
    #   "workspace_id": "2c5f5397-37b9-4236-beac-f47f050d42cd",
    #   "created_at": "2023-03-14T05:00:35.451Z"
    #   "occurred_at": "2023-05-20T00:01:31.273Z",
    #   "noiseaware_metadata": {
    #     "noiseaware_alert_info": "ALERT: Noise Sensors at [PropertyName] has sustained noise above the NRS threshold. dashboard.noiseaware.io/properties/[APIKey]",
    #     "noiseaware_alert_time": "2023-05-20T00:01:31.180Z",
    #     "noiseaware_alert_type": "newNoise",
    #     "noiseaware_property_id": 12345,
    #     "noiseaware_property_name": "Acme Corporation"
    #   }
    # }
  end
  ```

  ```php PHP theme={null}
  $app->post('/my_webhook_endpoint', function (Request $request, Response $response) {
      $data = $request->getParsedBody();
      $event = $data['event'];
      // {
      //   "event_id": "d8ffcf85-73f7-4383-b832-ed65db93c802",
      //   "device_id": "617415c6-2aa4-43ac-b436-879951f891b0",
      //   "event_type": "noise_sensor.noise_threshold_triggered",
      //   "workspace_id": "2c5f5397-37b9-4236-beac-f47f050d42cd",
      //   "created_at": "2023-03-14T05:00:35.451Z",
      //   "occurred_at": "2023-05-20T00:01:31.273Z",
      //   "noiseaware_metadata": {
      //     "noiseaware_alert_info": "ALERT: Noise Sensors at [PropertyName] has sustained noise above the NRS threshold. dashboard.noiseaware.io/properties/[APIKey]",
      //     "noiseaware_alert_time": "2023-05-20T00:01:31.180Z",
      //     "noiseaware_alert_type": "newNoise",
      //     "noiseaware_property_id": 12345,
      //     "noiseaware_property_name": "Acme Corporation"
      //   }
      // }
  });
  ```
</CodeGroup>

## Next Steps

Now that you've completed this guide, you can try to connect a real NoiseAware device. To do so, make sure to switch to a non-sandbox workspace and API key as real devices cannot be connected to sandbox workspaces.

If you have any questions or want to report an issue, email us at [support@seam.co](mailto:support@seam.co)


# NoiseAware Sensors
Source: https://docs.seam.co/device-and-system-integration-guides/noiseaware-sensors/index

Guide for using NoiseAware sensors with Seam

<img alt="NoiseAware logo" />

## Overview

Seam integrates with NoiseAware sensors to provide [privacy-safe noise monitoring](https://noiseaware.com/privacy-safe-noise-monitoring/) functions for the short-term rental and vacation rental industries. NoiseAware produces both an indoor sensor and an accompanying weatherproof outdoor sensor. For each NoiseAware sensor, you can set one noise threshold per hour, and the sensor notifies owners when noise levels exceed these configured thresholds.

***

## Supported Devices

<DeviceList />

This integration supports all [NoiseAware sensors](https://noiseaware.com/features/).

For detailed information about the NoiseAware devices that Seam supports, see our [NoiseAware Supported Devices page](https://www.seam.co/manufacturers/noiseaware).

***

## Supported Features

We support the following features:

* [Configuring noise threshold settings](/capability-guides/noise-sensors/configure-noise-threshold-settings)\
  You can configure a maximum of one noise threshold per hour per Noiseaware sensor. You cannot configure thresholds with time periods that overlap.
* [Receiving noise sensor events when noise events occur](/api/noise_sensors/noise_thresholds/events)\
  For more information, see the [`noise_sensor.noise_threshold_triggered` event](/api/noise_sensors/noise_thresholds/events#noise_sensor-noise_threshold_triggered).

***

### Device Provider Key

Seam identifies these devices with the `noiseaware` device provider key. By default, a [Connect Webview](/core-concepts/connect-webviews) displays all of the stable providers that Seam supports, so your users can connect their NoiseAware devices without you specifying a provider list. To narrow what a Connect Webview displays, see [Customize the Brands to Display in Your Connect Webviews](/core-concepts/connect-webviews/customizing-connect-webviews#customize-the-brands-to-display-in-your-connect-webviews).

***

## Setup Instructions

For instructions on connecting NoiseAware sensors to Seam, see the [NoiseAware Setup Guide](./noiseaware-setup-guide).

***

## Where to Order

To purchase NoiseAware sensors, visit the NoiseAware online store.

<table>
  <thead>
    <tr>
      <th />

      <th />

      <th />

      <th />

      <th />
    </tr>
  </thead>

  <tbody>
    <tr>
      <td />

      <td>
        <strong>NoiseAware Online Store</strong>
      </td>

      <td />

      <td>
        <a href="https://noiseaware.com/cart/">[https://noiseaware.com/cart/](https://noiseaware.com/cart/)</a>
      </td>

      <td />
    </tr>
  </tbody>
</table>

***


# NoiseAware Sensors Sample Data
Source: https://docs.seam.co/device-and-system-integration-guides/noiseaware-sensors/noiseaware-sample-data

Add virtual NoiseAware sensors to your Seam sandbox workspace using these sample credentials to test your integration without real hardware.

Use either of the following sets of credentials to add virtual [NoiseAware sensors](/device-and-system-integration-guides/noiseaware-sensors) to your Seam [sandbox workspace](/core-concepts/workspaces#sandbox-workspaces):

| Email Address                               | Password |
| ------------------------------------------- | -------- |
| [jane@example.com](mailto:jane@example.com) | 1234     |
| [john@example.com](mailto:john@example.com) | 1234     |


# NoiseAware Setup Guide
Source: https://docs.seam.co/device-and-system-integration-guides/noiseaware-sensors/noiseaware-setup-guide

Connect your NoiseAware sensors to Seam.

## Overview

This guide walks you through connecting your NoiseAware noise sensors to Seam. Your sensors must already be set up and working in the NoiseAware app before proceeding.

***

## Step 1: Confirm Your NoiseAware Account

1. Install the NoiseAware mobile app for [iOS](https://apps.apple.com/us/app/noiseaware/id1436213179) or [Android](https://play.google.com/store/apps/details?id=io.noiseaware.mobile\&hl=en_US\&gl=US) if you have not done so already.
2. Create an account in the NoiseAware mobile app if you have not done so already.
3. In the NoiseAware mobile app, confirm that your NoiseAware sensors are added and online.
4. Note your login credentials for the NoiseAware mobile app.

***

## Step 2: Connect to Seam via Connect Webview

1. Open the [Connect Webview](/core-concepts/connect-webviews) provided by your application.
2. Select NoiseAware as the provider.
3. Enter your NoiseAware app login credentials.
4. Once authorized, your NoiseAware sensors appear as devices in Seam.

***

## Step 3: Verify the Connection

After connecting, verify that your NoiseAware sensors appear as devices and show as online with noise monitoring capabilities.

***

## Troubleshooting

### Authorization fails in Connect Webview

Make sure you are using the same email and password that you use to log in to the NoiseAware mobile app. If you recently changed your password, use the updated credentials.

### Sensors not appearing after authorization

Ensure your NoiseAware sensors are added and online in the NoiseAware mobile app. Only sensors that are set up in the app are visible to Seam.

### Sensor shows as offline

Check that the sensor has power and is connected to Wi-Fi. Open the NoiseAware mobile app to verify the sensor's connection status.


# Get Started with Nuki Locks
Source: https://docs.seam.co/device-and-system-integration-guides/nuki-locks/get-started-with-nuki-locks

Learn how to connect and control your Nuki locks with the Seam API.

## Overview

Seam provides a universal API to connect and control many brands of locks, including Nuki. This guide provides a rapid introduction to connecting and controlling your [Nuki](https://www.seam.co/manufacturers/nuki) locks using the Seam API. To learn more about other device brands supported by the Seam API, such as Yale, Schlage, and August, head over to our [integration page](https://www.seam.co/supported-devices-and-systems).

## 1 — Install Seam SDK

Seam provides client libraries for many languages, such as JavaScript, Python, Ruby, PHP, and others, as well as a Postman collection and [OpenAPI](https://connect.getseam.com/openapi.json) spec.

* JavaScript / TypeScript ([npm](https://www.npmjs.com/package/seam), [GitHub](https://github.com/seamapi/javascript))
* Python ([pip](https://pypi.org/project/seam/), [GitHub](https://github.com/seamapi/python))
* Ruby Gem ([rubygem](https://rubygems.org/gems/seam), [GitHub](https://github.com/seamapi/ruby))
* PHP ([packagist](https://packagist.org/packages/seamapi/seam), [GitHub](https://github.com/seamapi/php))
* C# ([nuget](https://www.nuget.org/packages/Seam), [GitHub](https://github.com/seamapi/csharp))

<Tabs>
  <Tab title="JavaScript">
    ```bash theme={null}
    npm i seam
    ```
  </Tab>

  <Tab title="Python">
    ```bash theme={null}
    pip install seam
    # For some development environments, use pip3 in this command instead of pip.
    ```
  </Tab>

  <Tab title="Ruby">
    ```bash theme={null}
    bundle add seam
    ```
  </Tab>

  <Tab title="PHP">
    ```bash theme={null}
    composer require seamapi/seam
    ```
  </Tab>

  <Tab title="C#">
    Install using [nuget](https://www.nuget.org/packages/Seam).
  </Tab>
</Tabs>

Once installed, [sign-up for Seam](https://console.seam.co/) to get your API key, and export it as an environment variable:

```
$ export SEAM_API_KEY=seam_test2ZTo_0mEYQW2TvNDCxG5Atpj85Ffw
```

<Info>
  This guide uses a Sandbox Workspace. Only virtual devices can be connected. If
  you need to connect a real Nuki device, use a non-sandbox workspace and API
  key.
</Info>

## 2 — Link Your Nuki Account with Seam

To control your Nuki locks via the Seam API, you must first authorize your Seam workspace against your Nuki KS account. To do so, Seam provides[ Connect Webviews](/core-concepts/connect-webviews): pre-built UX flows that walk you through authorizing your application to control your Nuki sites.

#### Request a Connect Webview

<CodeGroup>
  ```javascript JavaScript theme={null}
  // Use Seam SDK to create a connect webview with the provider nuki
  const createdConnectWebview = await seam.connectWebviews.create();

  // Print the created webview URL
  console.log(createdConnectWebview.url);

  ```

  ```python Python theme={null}
  # Create a webview with Nuki as the provider
  created_webview = seam.connect_webviews.create()

  # Assert that login is not yet successful
  assert created_webview.login_successful is False

  # Print the URL of the webview
  print(created_webview.url)
  ```

  ```ruby Ruby theme={null}
  # Create a connect webview with the provider "nuki"
  created_webview = seam.connect_webviews.create()

  # The webview will not be logged in, which can be confirmed

  raise 'Login should not be succesful' unless !created_webview.login_successful

  # Retrieve and print out the url of the webview

  puts created_webview.url

  ```

  ```php PHP theme={null}
  <?php
  // initiate the SDK client, you should replace this with your SDK client init portion
  $seam = new Seam\SeamClient("YOUR_API_KEY");

  // create a connect webview with provider nuki
  $connect_webview = $seam->connect_webviews->create([
  ]);

  // check if the login was successful
  assert($connect_webview->login_successful === false);

  // print the connect webview URL
  print($connect_webview->url);
  ?>
  ```
</CodeGroup>

#### Authorize Your Workspace

Navigate to the URL returned by the Webview object. Since you are using a sandbox workspace, complete the login flow by entering the Nuki [sandbox test accounts ](/device-and-system-integration-guides/nuki-locks/nuki-sample-data)credentials below:

* **email:** [john@example.com](mailto:john@example.com)
* **password:** 1234

<img alt="Seam Connect Webview flow to connect Nuki account with Seam" />

Confirm the Connect Webview was successful by querying its status:

<CodeGroup>
  ```javascript JavaScript theme={null}
  const updatedWebview = await seam.connectWebviews.get(
    connectWebview.connect_webview_id
  )

  console.log(updatedWebview.login_successful) // true

  ```

  ```python Python theme={null}
  updated_webview = seam.connect_webviews.get(connect_webview_id: webview.connect_webview_id)

  assert updated_webview.login_successful # true
  ```

  ```ruby Ruby theme={null}
  updated_webview = seam.connect_webviews.get(connect_webview_id: webview.connect_webview_id)

  puts updated_webview.login_successful # true

  ```

  ```php PHP theme={null}
  $webview = $seam->connect_webviews->get($webview->id);
  echo json_encode($webview);
  ```
</CodeGroup>

## 3 — Retrieve Nuki Devices

After a Nuki account is linked with Seam, you can retrieve devices for this Nuki account. The Seam API exposes most of the device's properties such as battery level.

<CodeGroup>
  ```javascript JavaScript theme={null}
  const allLocks = await seam.locks.list()

  const someLock = allLocks[0]

  console.log(someLock.properties.online) // true
  console.log(someLock.properties.locked) // true

  console.log(someLock)
  /_
  {
  device_id: '60d0f1b6-26ae-4366-8d1b-d20ad0d6a62e',
  device_type: 'nuki_lock',
  capabilities_supported: [ 'access_code', 'lock' ],
  properties: {
  locked: false,
  online: true,
  manufacturer: 'nuki',
  battery_level: 0.86,
  nuki_metadata: { device_id: '545636388', device_name: 'Office Lock' },
  max_active_codes_supported: 100,
  supported_code_lengths: [ 6 ],
  name: 'Office Lock'
  },
  location: null,
  connected_account_id: '32e92b46-7978-4d48-a3e7-9b04662151b3',
  workspace_id: 'd7418ff3-a476-4f48-9a4b-211d1d21a03d',
  created_at: '2023-02-11T00:46:12.940Z',
  errors: [],
  warnings: []
  }
  _/

  ```

  ```python Python theme={null}
  all_locks = seam.locks.list()

  some_lock = all_locks[0]

  assert some_lock.properties["online"] is True
  assert some_lock.properties["battery_level"] is True

  print(some_lock)
  # Device(device_id='60d0f1b6-26ae-4366-8d1b-d20ad0d6a62e', device_type='nuki_lock', location=None, properties={'locked': False, 'online': True, 'manufacturer': 'nuki', 'battery_level': 0.86, 'nuki_metadata': {'device_id': '545636388', 'device_name': 'Office Lock'}, 'max_active_codes_supported': 100, 'supported_code_lengths': [6], 'name': 'Office Lock'}, capabilities_supported=['access_code', 'lock'], errors=[])
  ```

  ```ruby Ruby theme={null}
  some_lock = seam.locks.list.first

  puts some_lock.properties.online # true
  puts some_lock.properties.locked # true

  puts some_lock

  # <Seam::Device:0x00730

  # device_id="60d0f1b6-26ae-4366-8d1b-d20ad0d6a62e"

  # device_type="nuki_lock"

  # properties={"locked"=>false, "online"=>true, "manufacturer"=>"nuki", "battery_level"=>0.86, "nuki_metadata"=>{"device_id"=>"545636388", "device_name"=>"Office Lock"}, "max_active_codes_supported": 100, "supported_code_lengths"=>[6], "name"=>"Office Lock"}

  # created_at=2023-02-11 00:46:12.94 UTC

  # errors=[]

  # warnings=[]>

  ```

  ```php PHP theme={null}
  use Seam\SeamClient;

  $seam = new SeamClient('YOUR_API_KEY');

  $locks = $seam->locks->list();

  echo json_encode($locks);
  /*
  [{"device_id":"60d0f1b6-26ae-4366-8d1b-d20ad0d6a62e","workspace_id":"d7418ff3-a476-4f48-9a4b-211d1d21a03d","connected_account_id":"32e92b46-7978-4d48-a3e7-9b04662151b3","device_type":"nuki_lock","properties":{"online":true,"locked":false,"door_open":null,"battery_level":0.86,"name":"Office Lock","manufacturer":"nuki","august_metadata":null,"schlage_metadata":null,"smartthings_metadata":null},"location":null,"created_at":"2023-02-11T00:46:12.940Z","capabilities_supported":["access_code","lock"],"errors":[]}]
  */
  ```
</CodeGroup>

### 4 — Locking & Unlocking a Door

Next, you can perform the basic action of locking and unlocking a door.

> **`POST`** `/locks/lock_door`
>
> See the [API Reference](/api/locks/lock_door) for details.

## Unlock a door

<mark>`POST`</mark>
`https://connect.getseam.com/locks/unlock_door`

#### Request Body

| Name       | Type   | Description |
| ---------- | ------ | ----------- |
| device\_id | String |             |

<CodeGroup>
  ```javascript JavaScript theme={null}
  // lock the door
  await seam.locks.lockDoor(someLock.device_id)
  const updatedLock = await seam.locks.get(someLock.device_id)
  console.log(updatedLock.properties.locked) // true

  // unlock the door
  await seam.locks.unlockDoor(someLock.device_id)
  updatedLock = await seam.locks.get(someLock.device_id)
  console.log(updatedLock.properties.locked) // false

  ```

  ```python Python theme={null}
  # lock the door
  seam.locks.lock_door(device_id: some_lock.device_id)
  updated_lock = seam.locks.get(device_id: some_lock.device_id)
  assert updated_lock.properties["locked"] is True

  # Now unlock the door
  seam.locks.unlock_door(device_id: some_lock.device_id)
  updated_lock = seam.locks.get(device_id: some_lock.device_id)
  assert updated_lock.properties["locked"] is False
  ```

  ```ruby Ruby theme={null}
  # lock the door
  seam.locks.lock_door(device_id: some_lock.device_id)
  updated_lock = seam.locks.get(device_id: some_lock.device_id)
  puts updated_lock.properties.locked # true

  # unlock the door

  seam.locks.unlock_door(device_id: some_lock.device_id)
  updated_lock = seam.locks.get(device_id: some_lock.device_id)
  puts updated_lock.properties.locked # false

  ```

  ```php PHP theme={null}
  use Seam\SeamClient;

  $seam = new SeamClient('YOUR_API_KEY');

  $some_lock = $seam->locks->list()[0];

  # unlock the door
  $seam->locks->unlock_door($lock->device_id);
  # lock the door
  $seam->locks->lock_door($lock->device_id);
  ```
</CodeGroup>

### 5 — Setting Access Code on Nuki Lock

Some Nuki locks also have a keypad paired to them to program access codes. These codes can then be entered to unlock a Nuki lock.

The Seam API makes it easy to program both `ongoing` codes and `timebound` codes on a Nuki lock. You can find out more about Nuki lock access code in our [core concept section on access codes.](/low-level-apis/smart-locks/access-codes)

<Info>
  Nuki does not let you create a code starting with the digits "12". Codes
  cannot contain the digit 0.
</Info>

<CodeGroup>
  ```javascript JavaScript theme={null}
  // create an ongoing code
  await seam.accessCodes.create({
    device_id: someLock.device_id,
    code: "123456",
    name: "Personal Access Code",
  })

  // create a timebound code
  await seam.accessCodes.create({
  device_id: someLock.device_id,
  code: "888888",
  name: "My Temp Access Code",
  starts_at: "2028-11-12T19:23:42+0000",
  ends_at: "2028-11-13T19:23:42+0000",
  })

  // use a device_id as the "device_id" parameter
  await seam.accessCodes.list({
  device_id: someLock.device_id,
  })

  ```

  ```python Python theme={null}
  # create an ongoing code
  seam.access_codes.create(
    device=some_lock,
    code="492332",
    name="Personal Access Code")

  # create a timebound code
  seam.access_codes.create(
    device=some_lock,
    code="498882",
    name="My Temp Access Code",
    starts_at="2028-08-12T19:23:42+0000",
    ends_at="2028-08-13T19:23:42+0000")

  # you can use a device or a device_id as the "device" parameter
  seam.access_codes.list(device=some_lock)


  ```

  ```ruby Ruby theme={null}
  # create an ongoing code
  seam.access_codes.create(
    device_id: some_lock.device_id, code: '123456', name: 'Personal Access Code'
  )

  # create a timebound code

  seam.access_codes.create(
  device_id: some_lock.device_id,
  code: '888888',
  name: 'My Temp Access Code',
  starts_at: '2028-08-12T19:23:42+0000',
  ends_at: '2028-08-13T19:23:42+0000'
  )

  seam.access_codes.list(device_id: some_lock.device_id)

  ```

  ```php PHP theme={null}
  use Seam\SeamClient;

  $seam = new SeamClient("YOUR_API_KEY");

  $some_lock = $seam->locks->list()[0];
  $seam->access_codes->create(
    device_id: $some_lock->device_id, code: '123456', name: 'Personal Access Code'
  );

  $seam->access_codes->create(
    device_id: $some_lock->device_id,
    name: 'My Temp Access Code',
    code: '888888',
    starts_at: '2028-08-12T19:23:42+0000',
    ends_at: '2028-08-13T19:23:42+0000'
  );

  ```
</CodeGroup>

## Next Steps

Now that you've completed this guide, you can try to connect a real Nuki device. To do so, make sure to switch to a non-sandbox workspace and API key as real devices cannot be connected to sandbox workspaces.

In addition, if you'd like to explore other aspects of Seam, here is a list of helpful resources:

* [Schlage Getting Started Guide](../schlage-locks/get-started-with-schlage-locks)
* [Yale Getting Started Guide](../yale-locks/get-started-with-yale-locks)
* [SmartThings Getting Started Guide](../smartthings-hubs-+-devices/get-started-with-smartthings-hubs-+-smart-locks)
* [Receiving webhook](/developer-tools/webhooks) for [device events](/api/events/list)
* [Core Concepts](/core-concepts/overview)

If you have any questions or want to report an issue, email us at [support@seam.co](mailto:support@seam.co).


# Nuki Locks
Source: https://docs.seam.co/device-and-system-integration-guides/nuki-locks/index

Guide for using Nuki locks with Seam

<img alt="Nuki logo" />

## Overview

Nuki produces a smart lock and accompanying products for the residential, rental, vacation rental, and corporate markets. Seam integrates directly with the Wi-Fi-enabled Nuki Smart Lock Pro, as well as with the Nuki Smart Lock through the Nuki Wi-Fi Bridge. Because Nuki Smart Locks attach to existing deadbolts, they replace only the lock components on the insides of doors.

Seam also supports the Nuki Keypad accessory for access code-based entry. In addition, the Nuki Opener works with the Nuki Bridge to control the intercom in a multi-unit building. In this way, Nuki products provide keyless access all the way from the street.

***

## Supported Devices

<DeviceList />

This integration supports all Nuki Smart Lock and Nuki Opener models that are connected to Wi-Fi, either through built-in Wi-Fi or using the [Nuki Bridge](https://nuki.io/en/bridge/). Seam also supports the addition of the optional [Nuki Keypad](https://nuki.io/en/keypad-code/) to enable entering access codes to control the lock or opener.

<Info>
  You must purchase [Nuki Smart
  Hosting](https://nuki.io/en-us/products/smart-hosting-service) for each of
  your Nuki locks to enable you to program access codes on these Nuki locks
  through Seam.
</Info>

The following table details the requirements for compatibility with this Seam integration:

<table>
  <thead>
    <tr>
      <th>Product Models</th>
      <th>Compatibility</th>
      <th>Accessories</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        <a href="https://nuki.io/en/smart-lock/">Smart Lock</a>
      </td>

      <td>Compatible only with Nuki Bridge</td>

      <td>
        <ul>
          <li>Bridge</li>
          <li>Keypad (optional)</li>
        </ul>
      </td>
    </tr>

    <tr>
      <td>
        <a href="https://nuki.io/en/smart-lock-pro/">Smart Lock Pro</a>
      </td>

      <td>Compatible</td>

      <td>
        <ul>
          <li>Keypad (optional)</li>
        </ul>
      </td>
    </tr>

    <tr>
      <td>
        <a href="https://nuki.io/en/opener/">Opener</a>
      </td>

      <td>Compatible only with Nuki Bridge</td>

      <td>
        <ul>
          <li>Bridge</li>
          <li>Keypad (optional)</li>
        </ul>
      </td>
    </tr>
  </tbody>
</table>

For detailed information about the Nuki devices that Seam supports, see our [Nuki Supported Devices page](https://www.seam.co/manufacturers/nuki).

***

## Supported Features

We support the following features:

* [Triggering web lock and unlock actions](/low-level-apis/smart-locks/lock-and-unlock)
* [Programming access codes](/low-level-apis/smart-locks/access-codes) on locks and openers that have an installed Nuki Keypad

<Info>Nuki does not allow the use of zeros in PIN codes.</Info>

***

### Device Provider Key

Seam identifies these devices with the `nuki` device provider key. By default, a [Connect Webview](/core-concepts/connect-webviews) displays all of the stable providers that Seam supports, so your users can connect their Nuki devices without you specifying a provider list. To narrow what a Connect Webview displays, see [Customize the Brands to Display in Your Connect Webviews](/core-concepts/connect-webviews/customizing-connect-webviews#customize-the-brands-to-display-in-your-connect-webviews).

***

## Setup Instructions

For instructions on connecting Nuki locks to Seam, see the [Nuki Setup Guide](./nuki-setup-guide).

***

## Brand-Specific Restrictions

Nuki imposes the following limits on Nuki App users, lock permissions, and entry codes, that is, access codes:

### Nuki App Users

For Nuki Smart Lock 2.0 and newer, you can create 200 app users.

### Lock Permissions

For Nuki Smart Lock, you can create 100 permissions.

### Access Codes

For Smart Lock 3.0 and newer connected to a Nuki Keypad, you can create 200 access codes, in addition to the aforementioned permissions.

For Smart Lock 2.0 and previous versions connected to a Nuki Keypad, you can create 100 access codes, in addition to the aforementioned permissions.

***

## Where to Order

To purchase Nuki devices, visit the Nuki online store.

<table>
  <thead>
    <tr>
      <th />

      <th />

      <th />

      <th />

      <th />
    </tr>
  </thead>

  <tbody>
    <tr>
      <td />

      <td>
        <strong>Nuki Online Store</strong>
      </td>

      <td />

      <td>
        <a href="https://shop.nuki.io/en/">[https://shop.nuki.io/en/](https://shop.nuki.io/en/)</a>
      </td>

      <td />
    </tr>
  </tbody>
</table>

***


# Sandbox Nuki Locks
Source: https://docs.seam.co/device-and-system-integration-guides/nuki-locks/nuki-sample-data

Add virtual Nuki locks to your Seam sandbox workspace using these sample credentials to test your integration without real hardware.

Use the following set of credentials to add virtual [Nuki locks](/device-and-system-integration-guides/nuki-locks) to your Seam [sandbox workspace](/core-concepts/workspaces#sandbox-workspaces):

| Email Address                                                                              | Password |
| ------------------------------------------------------------------------------------------ | -------- |
| [jane@example.com](mailto:jane@example.com) or any email address in the example.com domain | 1234     |


# Nuki Setup Guide
Source: https://docs.seam.co/device-and-system-integration-guides/nuki-locks/nuki-setup-guide

Connect your Nuki locks to Seam.

## Overview

This guide walks you through connecting your Nuki locks to Seam. Your locks must already be set up and working in the Nuki app before proceeding.

***

## Step 1: Confirm Your Nuki Account

1. Create an account in the [Nuki App](https://nuki.io/en/app/) if you have not done so already.
2. In the Nuki App, confirm that your Nuki devices are added and online.
3. Note your login credentials for the Nuki App.

***

## Step 2: Purchase Nuki Smart Hosting

You must purchase [Nuki Smart Hosting](https://nuki.io/en-us/products/smart-hosting-service) for each of your Nuki locks to enable access code programming through Seam.

1. In a web browser, navigate to [Nuki Web](https://web.nuki.io/).
2. Click **Go To Nuki Web**.
3. Log in to Nuki Web using your Nuki App credentials.
4. In the left-hand navigation pane, click **Short-Term Rental**.
5. On the **Short-term rental** page, click **Connect now**.
6. In the **Connect to short-rental integrators** dialog, click **Nuki Online Shop**.
7. In the **Please select your devices for Nuki Smart Hosting** dialog, select the devices for which you want to be able to program access codes and then click **Buy Smart Hosting**.
8. In the Nuki online store, complete your Nuki Smart Hosting purchase.

***

## Step 3: Connect to Seam via Connect Webview

1. Open the [Connect Webview](/core-concepts/connect-webviews) provided by your application.
2. Select Nuki as the provider.
3. Enter your Nuki App login credentials.
4. Once authorized, your Nuki devices appear in Seam.

***

## Step 4: Verify the Connection

After connecting, verify that your Nuki locks appear as devices and show as online with lock/unlock and access code capabilities.

***

## Troubleshooting

### Authorization fails in Connect Webview

Make sure you are using the same email and password that you use to log in to the Nuki App. If you recently changed your password, use the updated credentials.

### Locks not appearing after authorization

Ensure your Nuki devices are added and online in the Nuki App. Nuki Smart Locks (non-Pro models) require a [Nuki Bridge](https://nuki.io/en/bridge/) for Wi-Fi connectivity. Only devices connected to Wi-Fi are visible to Seam.

### Access codes not working

Confirm that you have purchased Nuki Smart Hosting for the lock and that a [Nuki Keypad](https://nuki.io/en/keypad-code/) is installed. Both are required for access code programming through Seam.

### Lock shows as offline

Check that the lock is within range of the Nuki Bridge (if applicable) and that the bridge has an active Wi-Fi connection. For Nuki Smart Lock Pro models, verify the lock's built-in Wi-Fi connection.


# Get Started with Omnitec Locks
Source: https://docs.seam.co/device-and-system-integration-guides/omnitec-locks/get-started-with-omnitec-locks

Learn how to connect and control your Omnitec lock with the Seam API.

## Overview

Seam provides a universal API to connect and control many brands of smart locks. This guide provides a rapid introduction to connecting and controlling your [Omnitec](https://www.seam.co/manufacturers/omnitec) lock using the Seam API. Omnitec locks must be connected through an [Omnitec Rent\&Pass Gateway](https://www.omnitecsystems.com/products/rent-and-pass/gateway-online) for online access.

To learn more about other smart lock brands supported by Seam, head over to our [integration page](https://www.seam.co/supported-devices-and-systems).

***

## 1 — Install Seam SDK

Seam provides client libraries for many languages, such as JavaScript, Python, Ruby, PHP, and others, as well as a Postman collection and [OpenAPI](https://connect.getseam.com/openapi.json) spec.

* JavaScript / TypeScript ([npm](https://www.npmjs.com/package/seam), [GitHub](https://github.com/seamapi/javascript))
* Python ([pip](https://pypi.org/project/seam/), [GitHub](https://github.com/seamapi/python))
* Ruby Gem ([rubygem](https://rubygems.org/gems/seam), [GitHub](https://github.com/seamapi/ruby))
* PHP ([packagist](https://packagist.org/packages/seamapi/seam), [GitHub](https://github.com/seamapi/php))
* C# ([nuget](https://www.nuget.org/packages/Seam), [GitHub](https://github.com/seamapi/csharp))
* Java ([Maven](https://central.sonatype.com/artifact/co.seam/java), [GitHub](https://github.com/seamapi/java))

<CodeGroup>
  ```bash JavaScript theme={null}
  npm i seam
  ```

  ```bash Python theme={null}
  pip install seam
  # For some development environments, use pip3 in this command instead of pip.
  ```

  ```bash Ruby theme={null}
  bundle add seam
  ```

  ```bash PHP theme={null}
  composer require seamapi/seam
  ```

  ```bash C# theme={null}
  Install using nuget: https://www.nuget.org/packages/Seam
  ```

  ```bash Java theme={null}
  // Add to your pom.xml or build.gradle — see Maven Central for details.
  ```

  ```bash cURL (bash) theme={null}
  # cURL is already installed on most systems. No additional installation needed.
  # Export your API key as an environment variable:
  export SEAM_API_KEY=seam_test2ZTo_0mEYQW2TvNDCxG5Atpj85Ffw
  ```
</CodeGroup>

Once installed, [sign up for Seam](https://console.seam.co/) to get your API key, and export it as an environment variable:

```bash theme={null}
export SEAM_API_KEY=seam_test2ZTo_0mEYQW2TvNDCxG5Atpj85Ffw
```

<Info>
  This guide uses a Sandbox Workspace. Only virtual devices can be connected. If
  you need to connect a real Omnitec lock, use a non-sandbox workspace and API key.
</Info>

***

## 2 — Link Omnitec Account with Seam

To control your Omnitec lock via the Seam API, you must first authorize your Seam workspace against your Omnitec account. To do so, Seam provides [Connect Webviews](/core-concepts/connect-webviews): pre-built UX flows that walk you through authorizing your application to control your Omnitec lock.

#### Request a Connect Webview

<CodeGroup>
  ```javascript JavaScript theme={null}
  import { Seam } from "seam";

  const seam = new Seam();

  const connectWebview = await seam.connectWebviews.create();

  console.log(connectWebview.login_successful); // false

  // Send the webview URL to your user
  console.log(connectWebview.url);
  ```

  ```python Python theme={null}
  from seam import Seam

  seam = Seam()

  webview = seam.connect_webviews.create()

  assert webview.login_successful is False

  # Send the webview URL to your user
  print(webview.url)
  ```

  ```ruby Ruby theme={null}
  require "seam"

  seam = Seam.new(api_key: "MY_API_KEY")

  webview = seam.connect_webviews.create()

  puts webview.login_successful # false

  # Send the webview URL to your user
  puts webview.url
  ```

  ```php PHP theme={null}
  <?php
  use Seam\SeamClient;

  $seam = new SeamClient("YOUR_API_KEY");

  $webview = $seam->connect_webviews->create();

  echo $webview->login_successful; // false

  // Send the webview URL to your user
  echo $webview->url;
  ```

  ```csharp C# theme={null}
  using Seam.Client;

  var seam = new SeamClient(apiToken: "YOUR_API_KEY");

  var webview = seam.ConnectWebviews.Create();

  Console.WriteLine(webview.LoginSuccessful); // false

  // Send the webview URL to your user
  Console.WriteLine(webview.Url);
  ```

  ```java Java theme={null}
  import co.seam.Seam;
  import co.seam.api.types.ConnectWebview;

  Seam seam = Seam.builder().apiKey("YOUR_API_KEY").build();

  ConnectWebview webview = seam.connectWebviews().create(
    ConnectWebviewsCreateRequest.builder()
      .build()
  );

  System.out.println(webview.getLoginSuccessful()); // false

  // Send the webview URL to your user
  System.out.println(webview.getUrl());
  ```

  ```bash cURL (bash) theme={null}
  curl -X 'POST' \
    'https://connect.getseam.com/connect_webviews/create' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d '{}'
  ```
</CodeGroup>

#### Authorize Your Workspace

Navigate to the URL returned by the Webview object. Since you are using a sandbox workspace, complete the login flow by entering the Omnitec [sandbox test account](/device-and-system-integration-guides/omnitec-locks/sandbox-omnitec-locks) credentials below:

* **email:** [jane@example.com](mailto:jane@example.com)
* **password:** 1234

During the Connect Webview flow, you will also be prompted to select a time zone. You can choose any valid time zone.

Confirm the Connect Webview was successful by querying its status:

<CodeGroup>
  ```javascript JavaScript theme={null}
  const updatedWebview = await seam.connectWebviews.get(
    connectWebview.connect_webview_id
  );

  console.log(updatedWebview.login_successful); // true
  ```

  ```python Python theme={null}
  updated_webview = seam.connect_webviews.get(
      connect_webview_id=webview.connect_webview_id
  )

  assert updated_webview.login_successful  # true
  ```

  ```ruby Ruby theme={null}
  updated_webview = seam.connect_webviews.get(
    connect_webview_id: webview.connect_webview_id
  )

  puts updated_webview.login_successful # true
  ```

  ```php PHP theme={null}
  <?php
  $updated_webview = $seam->connect_webviews->get(
    connect_webview_id: $webview->connect_webview_id
  );

  echo $updated_webview->login_successful; // true
  ```

  ```csharp C# theme={null}
  var updatedWebview = seam.ConnectWebviews.Get(
    connectWebviewId: webview.ConnectWebviewId
  );

  Console.WriteLine(updatedWebview.LoginSuccessful); // true
  ```

  ```java Java theme={null}
  ConnectWebview updatedWebview = seam.connectWebviews().get(
    ConnectWebviewsGetRequest.builder()
      .connectWebviewId(webview.getConnectWebviewId())
      .build()
  );

  System.out.println(updatedWebview.getLoginSuccessful()); // true
  ```

  ```bash cURL (bash) theme={null}
  curl -X 'POST' \
    'https://connect.getseam.com/connect_webviews/get' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d "{
      \"connect_webview_id\": \"${CONNECT_WEBVIEW_ID}\"
    }"
  ```
</CodeGroup>

***

## 3 — Retrieve Omnitec Lock Devices

After an Omnitec account is linked with Seam, you can retrieve devices for this Omnitec account. The Seam API exposes most of the device's properties such as battery level or door lock status.

<CodeGroup>
  ```javascript JavaScript theme={null}
  const allLocks = await seam.locks.list();

  const someLock = allLocks[0];

  console.log(someLock.properties.online); // true
  console.log(someLock.properties.locked); // true

  console.log(someLock);
  /*
  {
    device_id: '...',
    device_type: 'omnitec_lock',
    capabilities_supported: ['access_code', 'lock'],
    properties: {
      locked: true,
      online: true,
      manufacturer: 'omnitec',
      omnitec_metadata: {
        lock_id: '...',
        lock_name: 'Room 101',
        has_gateway: true
      },
      name: 'Room 101'
    },
    ...
  }
  */
  ```

  ```python Python theme={null}
  all_locks = seam.locks.list()

  some_lock = all_locks[0]

  assert some_lock.properties["online"] is True
  assert some_lock.properties["locked"] is True

  print(some_lock)
  # Device(
  #   device_id='...',
  #   device_type='omnitec_lock',
  #   properties={
  #     'locked': True,
  #     'online': True,
  #     'manufacturer': 'omnitec',
  #     'omnitec_metadata': {...},
  #     'name': 'Room 101'
  #   },
  #   capabilities_supported=['access_code', 'lock']
  # )
  ```

  ```ruby Ruby theme={null}
  some_lock = seam.locks.list.first

  puts some_lock.properties.online # true
  puts some_lock.properties.locked # true

  puts some_lock
  ```

  ```php PHP theme={null}
  <?php
  $locks = $seam->locks->list();

  $some_lock = $locks[0];

  echo $some_lock->properties->online; // true
  echo $some_lock->properties->locked; // true
  ```

  ```csharp C# theme={null}
  var locks = seam.Locks.List();

  var someLock = locks[0];

  Console.WriteLine(someLock.Properties.Online); // true
  Console.WriteLine(someLock.Properties.Locked); // true
  ```

  ```java Java theme={null}
  var locks = seam.locks().list();

  var someLock = locks.get(0);

  System.out.println(someLock.getProperties().getOnline()); // true
  System.out.println(someLock.getProperties().getLocked()); // true
  ```

  ```bash cURL (bash) theme={null}
  curl -X 'POST' \
    'https://connect.getseam.com/locks/list' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d '{}'
  ```
</CodeGroup>

***

## 4 — Locking & Unlocking a Door

You can perform the basic actions of locking and unlocking an Omnitec lock.

<CodeGroup>
  ```javascript JavaScript theme={null}
  // lock the door
  await seam.locks.lockDoor(someLock.device_id);
  const updatedLock = await seam.locks.get(someLock.device_id);
  console.log(updatedLock.properties.locked); // true

  // unlock the door
  await seam.locks.unlockDoor(someLock.device_id);
  const unlockedLock = await seam.locks.get(someLock.device_id);
  console.log(unlockedLock.properties.locked); // false
  ```

  ```python Python theme={null}
  # lock the door
  seam.locks.lock_door(device_id=some_lock.device_id)
  updated_lock = seam.locks.get(device_id=some_lock.device_id)
  assert updated_lock.properties["locked"] is True

  # unlock the door
  seam.locks.unlock_door(device_id=some_lock.device_id)
  updated_lock = seam.locks.get(device_id=some_lock.device_id)
  assert updated_lock.properties["locked"] is False
  ```

  ```ruby Ruby theme={null}
  # lock the door
  seam.locks.lock_door(device_id: some_lock.device_id)
  updated_lock = seam.locks.get(device_id: some_lock.device_id)
  puts updated_lock.properties.locked # true

  # unlock the door
  seam.locks.unlock_door(device_id: some_lock.device_id)
  updated_lock = seam.locks.get(device_id: some_lock.device_id)
  puts updated_lock.properties.locked # false
  ```

  ```php PHP theme={null}
  <?php
  // lock the door
  $seam->locks->lock_door(device_id: $some_lock->device_id);
  $updated_lock = $seam->locks->get(device_id: $some_lock->device_id);
  echo $updated_lock->properties->locked; // true

  // unlock the door
  $seam->locks->unlock_door(device_id: $some_lock->device_id);
  $updated_lock = $seam->locks->get(device_id: $some_lock->device_id);
  echo $updated_lock->properties->locked; // false
  ```

  ```csharp C# theme={null}
  // lock the door
  seam.Locks.LockDoor(deviceId: someLock.DeviceId);
  var updatedLock = seam.Locks.Get(deviceId: someLock.DeviceId);
  Console.WriteLine(updatedLock.Properties.Locked); // true

  // unlock the door
  seam.Locks.UnlockDoor(deviceId: someLock.DeviceId);
  updatedLock = seam.Locks.Get(deviceId: someLock.DeviceId);
  Console.WriteLine(updatedLock.Properties.Locked); // false
  ```

  ```java Java theme={null}
  // lock the door
  seam.locks().lockDoor(LocksLockDoorRequest.builder()
      .deviceId(someLock.getDeviceId())
      .build());
  var updatedLock = seam.locks().get(LocksGetRequest.builder()
      .deviceId(someLock.getDeviceId())
      .build());
  System.out.println(updatedLock.getProperties().getLocked()); // true

  // unlock the door
  seam.locks().unlockDoor(LocksUnlockDoorRequest.builder()
      .deviceId(someLock.getDeviceId())
      .build());
  updatedLock = seam.locks().get(LocksGetRequest.builder()
      .deviceId(someLock.getDeviceId())
      .build());
  System.out.println(updatedLock.getProperties().getLocked()); // false
  ```

  ```bash cURL (bash) theme={null}
  # lock the door
  curl -X 'POST' \
    'https://connect.getseam.com/locks/lock_door' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d "{\"device_id\": \"${DEVICE_ID}\"}"

  # unlock the door
  curl -X 'POST' \
    'https://connect.getseam.com/locks/unlock_door' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d "{\"device_id\": \"${DEVICE_ID}\"}"
  ```
</CodeGroup>

***

## 5 — Setting Access Codes on an Omnitec Lock

Omnitec locks with a keypad support access code programming. The Seam API makes it easy to program both `ongoing` codes and `timebound` codes on an Omnitec lock.

You can find out more about access codes in our [guide on access codes](/low-level-apis/smart-locks/access-codes).

<CodeGroup>
  ```javascript JavaScript theme={null}
  // create an ongoing code
  await seam.accessCodes.create({
    device_id: someLock.device_id,
    code: "123456",
    name: "Personal Access Code",
  });

  // create a timebound code
  await seam.accessCodes.create({
    device_id: someLock.device_id,
    code: "888888",
    name: "Guest Access Code",
    starts_at: "2028-11-12T19:00:00+0000",
    ends_at: "2028-11-13T12:00:00+0000",
  });

  // list all access codes on the device
  const accessCodes = await seam.accessCodes.list({
    device_id: someLock.device_id,
  });

  console.log(accessCodes);
  /*
  [
    {
      code: '123456',
      type: 'ongoing',
      status: 'setting',
      access_code_id: '...',
      name: 'Personal Access Code'
    },
    {
      code: '888888',
      type: 'timebound',
      status: 'setting',
      access_code_id: '...',
      name: 'Guest Access Code',
      starts_at: '2028-11-12T19:00:00.000Z',
      ends_at: '2028-11-13T12:00:00.000Z'
    }
  ]
  */
  ```

  ```python Python theme={null}
  # create an ongoing code
  seam.access_codes.create(
      device_id=some_lock.device_id,
      code="123456",
      name="Personal Access Code"
  )

  # create a timebound code
  seam.access_codes.create(
      device_id=some_lock.device_id,
      code="888888",
      name="Guest Access Code",
      starts_at="2028-11-12T19:00:00+0000",
      ends_at="2028-11-13T12:00:00+0000"
  )

  # list all access codes on the device
  access_codes = seam.access_codes.list(device_id=some_lock.device_id)

  print(access_codes)
  ```

  ```ruby Ruby theme={null}
  # create an ongoing code
  seam.access_codes.create(
    device_id: some_lock.device_id,
    code: "123456",
    name: "Personal Access Code"
  )

  # create a timebound code
  seam.access_codes.create(
    device_id: some_lock.device_id,
    code: "888888",
    name: "Guest Access Code",
    starts_at: "2028-11-12T19:00:00+0000",
    ends_at: "2028-11-13T12:00:00+0000"
  )

  # list all access codes on the device
  access_codes = seam.access_codes.list(device_id: some_lock.device_id)

  puts access_codes
  ```

  ```php PHP theme={null}
  <?php
  // create an ongoing code
  $seam->access_codes->create(
    device_id: $some_lock->device_id,
    code: "123456",
    name: "Personal Access Code"
  );

  // create a timebound code
  $seam->access_codes->create(
    device_id: $some_lock->device_id,
    code: "888888",
    name: "Guest Access Code",
    starts_at: "2028-11-12T19:00:00+0000",
    ends_at: "2028-11-13T12:00:00+0000"
  );

  // list all access codes on the device
  $access_codes = $seam->access_codes->list(
    device_id: $some_lock->device_id
  );

  print_r($access_codes);
  ```

  ```csharp C# theme={null}
  // create an ongoing code
  seam.AccessCodes.Create(
    deviceId: someLock.DeviceId,
    code: "123456",
    name: "Personal Access Code"
  );

  // create a timebound code
  seam.AccessCodes.Create(
    deviceId: someLock.DeviceId,
    code: "888888",
    name: "Guest Access Code",
    startsAt: "2028-11-12T19:00:00+0000",
    endsAt: "2028-11-13T12:00:00+0000"
  );

  // list all access codes on the device
  var accessCodes = seam.AccessCodes.List(
    deviceId: someLock.DeviceId
  );

  foreach (var code in accessCodes)
  {
    Console.WriteLine(code.Code);
  }
  ```

  ```java Java theme={null}
  // create an ongoing code
  seam.accessCodes().create(AccessCodesCreateRequest.builder()
      .deviceId(someLock.getDeviceId())
      .code("123456")
      .name("Personal Access Code")
      .build());

  // create a timebound code
  seam.accessCodes().create(AccessCodesCreateRequest.builder()
      .deviceId(someLock.getDeviceId())
      .code("888888")
      .name("Guest Access Code")
      .startsAt("2028-11-12T19:00:00+0000")
      .endsAt("2028-11-13T12:00:00+0000")
      .build());

  // list all access codes on the device
  var accessCodes = seam.accessCodes().list(AccessCodesListRequest.builder()
      .deviceId(someLock.getDeviceId())
      .build());

  System.out.println(accessCodes);
  ```

  ```bash cURL (bash) theme={null}
  # create an ongoing code
  curl -X 'POST' \
    'https://connect.getseam.com/access_codes/create' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d "{
      \"device_id\": \"${DEVICE_ID}\",
      \"code\": \"123456\",
      \"name\": \"Personal Access Code\"
    }"

  # create a timebound code
  curl -X 'POST' \
    'https://connect.getseam.com/access_codes/create' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d "{
      \"device_id\": \"${DEVICE_ID}\",
      \"code\": \"888888\",
      \"name\": \"Guest Access Code\",
      \"starts_at\": \"2028-11-12T19:00:00+0000\",
      \"ends_at\": \"2028-11-13T12:00:00+0000\"
    }"

  # list all access codes on the device
  curl -X 'POST' \
    'https://connect.getseam.com/access_codes/list' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d "{\"device_id\": \"${DEVICE_ID}\"}"
  ```
</CodeGroup>

***

## Next Steps

Now that you've completed this guide, you can try to connect a real Omnitec device. To do so, make sure to switch to a non-sandbox workspace and API key as real devices cannot be connected to sandbox workspaces.

In addition, if you'd like to explore other aspects of Seam, here is a list of helpful resources:

* [Receiving webhooks](/developer-tools/webhooks) for [device events](/api/events/list)
* [Core Concepts](/core-concepts/overview)
* [Access Codes Guide](/low-level-apis/smart-locks/access-codes)

If you have any questions or want to report an issue, email us at [support@seam.co](mailto:support@seam.co).


# Omnitec Locks
Source: https://docs.seam.co/device-and-system-integration-guides/omnitec-locks/index

Guide for using Omnitec hotel locks with Seam

## Overview

Omnitec manufactures electronic hotel locks and access control solutions designed for the hospitality industry. Their product line includes RFID-based door locks, elevator controllers, and energy management systems tailored for hotels and resorts.

Seam integrates with Omnitec online locks connected through the [Omnitec Rent\&Pass Gateway](https://www.omnitecsystems.com/products/rent-and-pass/gateway-online) to provide remote lock and unlock actions, as well as online access code programming.

***

## Supported Devices

This integration supports Omnitec online locks that are connected via an [Omnitec Rent\&Pass Gateway](https://www.omnitecsystems.com/products/rent-and-pass/gateway-online). The gateway enables real-time communication between Seam and your Omnitec locks over Wi-Fi.

<Warning>
  Seam only supports Omnitec locks that are online through a gateway. Offline-only Omnitec locks (without a gateway connection) are not supported.
</Warning>

For detailed information about the Omnitec devices that Seam supports, see our [Omnitec Supported Devices page](https://www.seam.co/manufacturers/omnitec).

***

## Supported Features

We support the following features:

* [Triggering web lock and unlock actions](/low-level-apis/smart-locks/lock-and-unlock)
* [Programming online access codes](/low-level-apis/smart-locks/access-codes) on locks that have a keypad

***

## Device Provider Key

Seam identifies these devices with the `omnitec` device provider key. By default, a [Connect Webview](/core-concepts/connect-webviews) displays all of the stable providers that Seam supports, so your users can connect their Omnitec devices without you specifying a provider list. To narrow what a Connect Webview displays, see [Customize the Brands to Display in Your Connect Webviews](/core-concepts/connect-webviews/customizing-connect-webviews#customize-the-brands-to-display-in-your-connect-webviews).

***

## Setup Instructions

For step-by-step instructions on connecting Omnitec locks to Seam — including gateway configuration and troubleshooting — see the [Omnitec Setup Guide](./omnitec-setup-guide).

***

## Where to Order

<CardGroup>
  <Card title="Omnitec Systems - Products" href="https://www.omnitecsystems.com/products/electronic-hotel-lock" />
</CardGroup>


# Omnitec Setup Guide
Source: https://docs.seam.co/device-and-system-integration-guides/omnitec-locks/omnitec-setup-guide

Connect your Omnitec locks to Seam through the Rent&Pass integration.

## Overview

This guide walks you through connecting your Omnitec hotel locks to Seam. The integration works through the [Omnitec Rent\&Pass Gateway](https://www.omnitecsystems.com/products/rent-and-pass/gateway-online), so your locks must already be online and visible in the Rent\&Pass app before proceeding.

***

## Step 1: Locate Your Integrator Credentials

The credentials used for the Seam integration are **not** the same as the login email and password used to access the Rent\&Pass app.

To find your integrator credentials:

1. Open the Omnitec Rent\&Pass app.
2. Navigate to the **Integrator Credentials** section.
3. Note the **Username** and **Password** displayed there.

<Info>
  If the "Integrator Credentials" section is not visible in your Rent\&Pass app, contact Omnitec support to have it enabled on your account.
</Info>

***

## Step 2: Connect to Seam via Connect Webview

1. Open the [Connect Webview](/core-concepts/connect-webviews) provided by your application.
2. Select Omnitec as the provider.
3. Enter the **Integrator Credentials** from the Rent\&Pass app (not your regular app login).
4. Once authorized, your online Omnitec locks appear as devices in Seam.

***

## Step 3: Verify the Connection

After connecting, verify that your online Omnitec locks appear as devices and show as online with lock/unlock and access code capabilities.

***

## Troubleshooting

### Authorization fails in Connect Webview

Make sure you are using the **Integrator Credentials** from the Rent\&Pass app, not your regular app login email and password. These are different credentials. If the "Integrator Credentials" section is not visible in the app, contact Omnitec support.

### Locks not appearing after authorization

Ensure the Rent\&Pass Gateway is powered on and connected to Wi-Fi. Only locks that are online through the gateway are visible to Seam.

### Lock shows as offline

Check that the lock is within range of the gateway and that the gateway's Wi-Fi connection is active. Re-pair the lock with the gateway if necessary.

### Gateway connection issues

Verify that the gateway's Wi-Fi network has internet access. The gateway needs to reach Omnitec's cloud servers to relay commands from Seam.


# Sandbox Omnitec Locks
Source: https://docs.seam.co/device-and-system-integration-guides/omnitec-locks/sandbox-omnitec-locks

Add virtual Omnitec locks to your Seam sandbox workspace using these sample credentials to test your integration without real hardware.

Use the following set of credentials to add virtual [Omnitec locks](/device-and-system-integration-guides/omnitec-locks) to your Seam [sandbox workspace](/core-concepts/workspaces#sandbox-workspaces):

| Email Address                               | Password | Time Zone |
| ------------------------------------------- | -------- | --------- |
| [jane@example.com](mailto:jane@example.com) | 1234     | Any       |

During the Connect Webview flow, you will also be prompted to select a time zone. You can choose any valid time zone. This setting determines how time-bound access code schedules are adjusted for the lock's local time.


# PTI Storlogix Cloud
Source: https://docs.seam.co/device-and-system-integration-guides/pti-storlogix-cloud/index

Guide for using the PTI Storlogix Cloud with Seam

<img alt="PTI logo" />

## Overview

This integration uses [Storlogix Cloud](https://ptisecurity.com/products/storlogixcloudplatform/) to create [users](/low-level-apis/access-systems), [generate PIN codes](/low-level-apis/access-systems/managing-credentials#create-a-pin-code-based-credential), and [grant users access](/low-level-apis/access-systems) to different access areas within storage rental unit facilities.

***

## Supported Devices

<DeviceList />

Seam integrates with any site that has Storlogix Cloud installed.

For detailed information about the PTI devices that Seam supports, see our [PTI Supported Devices page](https://www.seam.co/manufacturers/pti).

***

## Supported Features

We support the following features:

* [**User Management**](/low-level-apis/access-systems/user-management)

  You can administer individual [users](/low-level-apis/access-systems) and add them to [access groups](/low-level-apis/access-systems) as needed.

  To authorize a user, [add the user to a `pti_access_level` access group](/low-level-apis/access-systems/user-management/assigning-users-to-access-groups). If you wish to document that a user has rented a specific unit, include them in a `pti_unit` access group using the same endpoint. Note that certain access levels mandate a user be part of a `pti_unit` linked to that access area before they can enter those zones.

* [**Manage ACS Credentials**](/low-level-apis/access-systems/managing-credentials)

  You can create PIN code-based and key card-based ACS credentials. Note that you can assign a unique PIN code to each user, thereby facilitating secure site access.

***

### Device Provider Key

Seam identifies these devices with the `pti` device provider key. By default, a [Connect Webview](/core-concepts/connect-webviews) displays all of the stable providers that Seam supports, so your users can connect their PTI Storlogix Cloud without you specifying a provider list. To narrow what a Connect Webview displays, see [Customize the Brands to Display in Your Connect Webviews](/core-concepts/connect-webviews/customizing-connect-webviews#customize-the-brands-to-display-in-your-connect-webviews).

***

## Setup Instructions

For instructions on connecting PTI Storlogix Cloud to Seam, see the [PTI Storlogix Cloud Setup Guide](./pti-storlogix-cloud-setup-guide).

***

## Brand-Specific PIN Code Restrictions

The PIN code value must be an integer in the range 1-4294967296.

***

## Assigning Access Permissions to Users

For PTI Storlogix Cloud, you must add the [users](/low-level-apis/access-systems) to `pti_access_level` and `pti_unit` [access groups](/low-level-apis/access-systems) to give them access to their storage unit.

For example, you could assign them to the "Building A - 3/F" access level and give them access to the "A301" unit. For details, see [Assigning Users to Access Groups](/low-level-apis/access-systems/user-management/assigning-users-to-access-groups).

***

## Troubleshooting

The following warning might appear for PTI-related users:

<table>
  <thead>
    <tr>
      <th>Warning</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        <code>user.pti\_access\_level\_not\_assigned</code>
      </td>

      <td>
        A PTI user needs to be assigned to an access level before their access
        credentials can be used to enter the site.
      </td>
    </tr>
  </tbody>
</table>

***

## Where to Order

To find a local PTI Security Systems installer, contact the PTI Security Systems Sales team. You can find the contact information for this team on the [PTI Security Systems Sales Contact Us Page](https://ptisecurity.com/contact-us-sales/).

<table>
  <thead>
    <tr>
      <th />

      <th />

      <th />

      <th />

      <th />
    </tr>
  </thead>

  <tbody>
    <tr>
      <td />

      <td>
        <strong>PTI Security Systems Sales Contact Us Page</strong>
      </td>

      <td />

      <td>
        <a href="https://ptisecurity.com/contact-us-sales/">
          [https://ptisecurity.com/contact-us-sales/](https://ptisecurity.com/contact-us-sales/)
        </a>
      </td>

      <td>
        <a href="/images/contact-pti-sales.png">contact-pti-sales.png</a>
      </td>
    </tr>
  </tbody>
</table>


# PTI Storlogix Cloud Sample Data
Source: https://docs.seam.co/device-and-system-integration-guides/pti-storlogix-cloud/pti-storlogix-cloud-sample-data

Add virtual PTI Storlogix Cloud devices to your Seam sandbox workspace using these sample credentials to test your integration without real hardware.

Use the following set of credentials to add virtual [PTI Storlogix Cloud](/device-and-system-integration-guides/pti-storlogix-cloud)-connected devices to your Seam [sandbox workspace](/core-concepts/workspaces#sandbox-workspaces):

| Field                   | Value                                                              |
| ----------------------- | ------------------------------------------------------------------ |
| Site Key                | 1234                                                               |
| Site Code               | 1234                                                               |
| StorLogix Dashboard URL | [https://1234.storlogixcloud.com](https://1234.storlogixcloud.com) |
| Username                | [jane@example.com](mailto:jane@example.com)                        |
| Password                | 1234                                                               |


# PTI Storlogix Cloud Setup Guide
Source: https://docs.seam.co/device-and-system-integration-guides/pti-storlogix-cloud/pti-storlogix-cloud-setup-guide

Connect your PTI Storlogix Cloud system to Seam.

## Overview

This guide walks you through connecting your PTI Storlogix Cloud access control system to Seam. Your Storlogix Cloud site must already be set up and operational before proceeding.

***

## Step 1: Gather Your Storlogix Cloud Credentials

To connect your Storlogix site, you need the following information:

* Site code
* Site key
* Operator username
* Operator password
* Storlogix Cloud dashboard URL

To obtain this information:

1. Log in to your Storlogix Cloud dashboard using your operator username and password.
2. Note the page URL in the address bar at the top of your web browser, as well as the operator username and password that you used to log in.
3. In the top, left corner of the Storlogix Cloud dashboard, click the three-bar button.
4. Click **Operations > Company Info**.
5. Click the **Device Settings** tab.
6. Note the **SiteKey** and **SiteCode** values.

<Info>
  If you do not have access to your Storlogix Cloud dashboard -- that is, if you are unsure of your Storlogix Cloud login credentials or the dashboard URL -- contact the [PTI Security Systems Customer Support team](https://ptisecurity.my.salesforce-sites.com/apex/Support). They can assist you in retrieving your login details.

  When contacting a PTI Security Systems Customer Support agent, have your PTI Support PIN or facility information ready.

  Make sure that you obtain the appropriate credentials specifically for Storlogix Cloud dashboard access.
</Info>

***

## Step 2: Connect to Seam via Connect Webview

1. Open the [Connect Webview](/core-concepts/connect-webviews) provided by your application.
2. Select PTI Storlogix Cloud as the provider.
3. Enter the site code, site key, operator username, operator password, and dashboard URL that you gathered in Step 1.
4. Once authorized, your PTI Storlogix Cloud system is connected to Seam.

***

## Step 3: Verify the Connection

After connecting, verify that your Storlogix Cloud system appears as a connected account and that your access control resources are visible in Seam.

***

## Troubleshooting

### Authorization fails in Connect Webview

Make sure you are using the operator credentials for the Storlogix Cloud dashboard, not a different PTI login. Double-check the site code, site key, and dashboard URL values from the Device Settings tab.

### Cannot find Storlogix Cloud credentials

Contact the [PTI Security Systems Customer Support team](https://ptisecurity.my.salesforce-sites.com/apex/Support) with your PTI Support PIN or facility information to retrieve your dashboard login details.

### System connected but no access areas visible

Verify that your Storlogix Cloud site has access levels and units configured. Seam reflects the access structure defined in Storlogix Cloud.


# Ring Cameras
Source: https://docs.seam.co/device-and-system-integration-guides/ring-cameras/index

Guide for using Ring cameras and doorbells with Seam

## Overview

Ring manufactures video doorbells and security cameras designed for residential use. Their product lineup includes wired and battery-powered cameras, video doorbells, and floodlight cameras that homeowners use to monitor their properties.

Seam integrates with Ring cameras and doorbells to provide motion detection events, doorbell press events, and device status monitoring.

<Info>
  Live video streaming and historical clip downloads are not yet available via the API. Thumbnails and short clips are included directly on motion and doorbell event payloads.
</Info>

***

## Supported Devices

<DeviceList />

Seam supports two Ring device types:

* **`ring_camera`** — Ring security cameras (indoor and outdoor)
* **`ring_doorbell`** — Ring video doorbells (devices with a physical button)

Device type is determined automatically by Seam based on the device's capabilities. Doorbells are identified by their button-press capability; all other Ring devices are classified as cameras.

For detailed information about the Ring devices that Seam supports, see our [Ring Supported Devices page](https://www.seam.co/manufacturers/ring).

***

## Supported Features

| Feature                      | `ring_camera` | `ring_doorbell` |
| ---------------------------- | ------------- | --------------- |
| Motion detection events      | ✅             | ✅               |
| Doorbell press events        | —             | ✅               |
| Device online/offline status | ✅             | ✅               |
| Live video streaming         | Coming soon   | Coming soon     |
| Historical clip downloads    | Coming soon   | Coming soon     |

***

## Brand-Specific Restrictions

* **Ring Protect subscription required** for video clip access and some motion detection features. Devices without an active subscription may fire limited events.
* **Account re-linking** must be done through the Ring app. If a user's Ring account tokens expire, they need to re-link via the Connect flow — there is no automatic re-auth path.

***

## Brand-Specific Events

Seam fires the following camera-specific events for Ring devices:

* **`camera.activated`** — Fired when a Ring camera or doorbell detects motion. Includes `activation_reason`, `motion_sub_type` (human, vehicle, package, or other), `image_url`, and `video_url`.
* **`device.doorbell_rang`** — Fired when a Ring doorbell button is pressed. Includes `image_url` and `video_url`.

***

## Device Provider Key

Seam identifies these devices with the `ring` device provider key. By default, a [Connect Webview](/core-concepts/connect-webviews) displays all of the stable providers that Seam supports, so your users can connect their Ring devices without you specifying a provider list. To narrow what a Connect Webview displays, see [Customize the Brands to Display in Your Connect Webviews](/core-concepts/connect-webviews/customizing-connect-webviews#customize-the-brands-to-display-in-your-connect-webviews).

***

## Setup Instructions

For instructions on connecting Ring cameras and doorbells to Seam — including the Ring App pairing flow and troubleshooting — see the [Ring Setup Guide](./ring-setup-guide).

***

## Where to Order

<CardGroup>
  <Card title="Ring - Products" href="https://ring.com/collections" />
</CardGroup>


# Ring Setup Guide
Source: https://docs.seam.co/device-and-system-integration-guides/ring-cameras/ring-setup-guide

Connect your Ring cameras and doorbells to Seam using the Ring App pairing flow.

## Overview

This guide walks you through connecting your Ring cameras and doorbells to Seam. Ring uses a **Ring App-initiated** account linking flow — this is different from the standard OAuth flow used by most providers. The connection is initiated from inside the Ring app rather than through a redirect.

Your Ring devices must already be set up and visible in the Ring app before proceeding.

***

## Step 1: Create a Connect Webview

Create a [Connect Webview](/core-concepts/connect-webviews) with `ring` as the accepted provider. Seam generates a 6-character **pairing code** and displays it to the user.

***

## Step 2: Pair Through the Ring App

1. The user opens the Ring app on their phone.
2. Navigates to **App Store → Seam → Connect**.
3. Selects which devices to share with Seam.
4. Ring redirects the user to a Seam-hosted page where they enter the pairing code from Step 1.

<Info>
  The pairing code is displayed in the Connect Webview. The user must enter this code on the Seam-hosted page that Ring redirects to — this is what links their Ring account to your Connect Webview session.
</Info>

***

## Step 3: Verify the Connection

Once the user completes the pairing flow, a connected account is created and Seam begins syncing their Ring devices automatically. Verify that your Ring cameras and doorbells appear as devices and show as online.

Each Ring device exposes the following metadata in `device.properties`:

* `ring_metadata.device_name` — The device's display name
* `ring_metadata.has_motion_detection` — Whether the device supports motion detection
* `ring_metadata.max_resolution` — Maximum video resolution
* `ring_metadata.video_codecs` — Supported video codecs
* `ring_metadata.has_color_night_vision` — Color night vision support
* `ring_metadata.has_hdr` — HDR support

***

## Troubleshooting

### Authorization fails or pairing code is rejected

Make sure the user is entering the pairing code displayed in the Connect Webview on the Seam-hosted page that Ring redirects to. The code is 6 characters and is case-insensitive.

### Devices not appearing after pairing

Ensure the Ring devices are set up and online in the Ring app. Only devices that the user selects during the Ring App pairing flow are shared with Seam.

### Devices show as offline

Check that the Ring device has power and is connected to Wi-Fi. Ring cameras rely on a direct Wi-Fi connection to Ring's cloud servers.

### Motion events not firing

A Ring Protect subscription is required for some motion detection features. Devices without an active subscription may fire limited events or no events at all.

### Account tokens expire

If a user's Ring account tokens expire, they need to re-link through the Ring App pairing flow. There is no automatic re-auth path — create a new Connect Webview and have the user repeat the pairing process.

### New devices not appearing

Device sync runs on a periodic poll. New devices added to a Ring account after the initial connection appear in Seam within a few minutes.


# Salto KS Access Control System
Source: https://docs.seam.co/device-and-system-integration-guides/salto-ks-access-control-system/index

Guide for using the Salto KS Access Control System with Seam

<img alt="Salto KS logo" />

## Overview

[Salto KS](https://saltoks.com/) (Keys as a Service) provides a cloud-based access control system that enables property managers and owners to control access across their properties. With Salto KS, you can manage user access, set schedules, and monitor entrances efficiently. Because Salto KS is cloud-based, it provides the benefits and ease of remote management. In addition, you can monitor real-time data and analytics.

The Seam integration for Salto KS enables you to create ACS users and assign access permissions to them. In the Salto KS model, you can choose to configure access schedules directly on the `acs_user`s themselves.

***

## Salto KS Resources

The Seam ACS schema consists of a series of resources that interact intuitively, enabling you to use the Seam API to manage your Salto KS ACS in a logical, efficient manner. Salto KS is an [access group-based ACS](/low-level-apis/access-systems/connect-an-acs-to-seam/understanding-access-control-system-differences#access-group-based-access-control-systems), so you [create ACS users](/low-level-apis/access-systems/user-management#create-an-acs-user) and then assign them to access groups to specify the entrances to which these users have access. You can also configure access schedules for ACS users.

The following diagram shows the Seam resources for a Salto KS ACS and the relationships between these resources:

The following table provides a brief description of each of the Seam resources for the Salto Space ACS:

<table>
  <thead>
    <tr>
      <th>Seam Resource</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        <a href="/api/acs/users/object">
          <code>acs\_user</code>
        </a>
      </td>

      <td>
        Individual who has been granted access to specific entrances within a
        property. ACS users could include employees, residents, and temporary
        guests. You can configure access schedules for users, if desired. You
        assign a unique credential to each user.
      </td>
    </tr>

    <tr>
      <td>
        <a href="/api/acs/access_groups/object">
          <code>acs\_access\_group</code>
        </a>
      </td>

      <td>
        Collection of users with shared access permissions. Instead of assigning
        permissions individually, users are grouped based on their access needs.
        Access groups streamline the management of access rights and ensure
        consistency.
      </td>
    </tr>

    <tr>
      <td>
        <code>access\_schedule</code>
      </td>

      <td>
        Timeframe during which access is permitted. By associating schedules
        with ACS users and then assigning users to access groups, property
        managers can control when users can enter specific areas, enhancing
        security and operational efficiency.

        <br />

        If you set an access schedule for a Salto KS ACS user, the user appears
        as "unsubscribed" in the ACS until the <code>starts\_at</code> time. Once
        the start time arrives, Seam switches the ACS user to "subscribed,"
        which activates their access.
      </td>
    </tr>

    <tr>
      <td>
        <a href="/api/acs/entrances/object">
          <code>acs\_entrance</code>
        </a>
      </td>

      <td>
        Physical points of entry within a property that are secured with Salto
        KS smart access devices. Access permissions are assigned to these
        entrances through access groups and access schedules.
      </td>
    </tr>

    <tr>
      <td>
        <a href="/api/acs/credentials/object">
          <code>acs\_credential</code>
        </a>
      </td>

      <td>
        <p>PINs, key cards or tags, or mobile keys.</p>

        <ul>
          <li>
            PINs: Unique personal identification numbers assigned to each user.
            For Salto KS, you cannot specify a custom PIN code. Instead, Salto
            KS generates the PIN code.
          </li>

          <li>
            Key cards or tags: Physical cards that users can swipe or tap at
            access points.
          </li>

          <li>
            Mobile keys: Digital keys stored on users' mobile devices, enabling
            them to access entrances using their smartphones.
          </li>
        </ul>
      </td>
    </tr>
  </tbody>
</table>

For more information about managing your Salto KS ACS through Seam, see the following topics:

* [Programming Salto KS PIN Code Credentials](/device-and-system-integration-guides/salto-ks-access-control-system/programming-code-based-salto-ks-credentials)
* [Programming Salto KS Mobile Credentials](/device-and-system-integration-guides/salto-ks-access-control-system/programming-salto-ks-mobile-credentials)
* [Access Group-Based Access Control Systems](/low-level-apis/access-systems/connect-an-acs-to-seam/understanding-access-control-system-differences#access-group-based-access-control-systems)
* [Access Control Systems](/low-level-apis/access-systems)
* [Mobile Access](/capability-guides/mobile-access)

***

## Supported Devices

<DeviceList />

This integration supports all Salto locks connected to the Salto KS ACS.

***

## Supported Features

We support the following features:

* [Managing access systems](/low-level-apis/access-systems)
* [Issuing code-based credentials](/device-and-system-integration-guides/salto-ks-access-control-system/programming-code-based-salto-ks-credentials)
* [Issuing mobile access credentials](/capability-guides/mobile-access)

***

### Device Provider Key

Seam identifies these devices with the `salto_ks` device provider key. By default, a [Connect Webview](/core-concepts/connect-webviews) displays all of the stable providers that Seam supports, so your users can connect their Salto KS ACS without you specifying a provider list. To narrow what a Connect Webview displays, see [Customize the Brands to Display in Your Connect Webviews](/core-concepts/connect-webviews/customizing-connect-webviews#customize-the-brands-to-display-in-your-connect-webviews).

***

## Brand-Specific Restrictions

Note the following Salto KS restrictions:

### Salto KS Account Type

You must use a Salto KS production environment account to connect to Seam. You cannot use "Accept Environment" credentials.

To confirm that your Salto KS account is a production environment account, note the Salto KS dashboard URL. Make sure that the subdomain within this URL is `app`, for example, `https://app.saltoks.com`.

A subdomain of `app-accept`, for example, `https://app-accept.saltoks.com`, indicates an "Accept Environment" that you cannot connect to Seam.

### ACS Credentials

When creating a credential for Salto KS, you cannot specify a custom PIN code. Instead, Salto KS generates the PIN code.

***

## Brand-Specific Behaviors

Note the following Salto KS behaviors:

### Proximity Behavior

To use access devices successfully within a Salto KS access system, it is important to understand the following proximity behavior requirements:

#### Card Readers

Card readers within a Salto KS access system are powered. By default, near detection mode is enabled, which means that readers can read a BLE credential from up to around 30 cm away. If you disable near detection mode, the range increases to around 15 meters. For more details, see [this Salto KS document](https://support.saltosystems.com/ks/hardware/lock-information-and-settings/#im-having-proximity-issues-how-close-does-a-phone-need-to-be-to-a-lock-to-open-it).

To disable or enable near detection mode:

1. Log in to the [Salto KS web app](https://app.saltoks.com/).
2. In the top navigation pane, click **Locks**.
3. Click the reader for which you’d like to modify the proximity settings.
4. On the reader page, click **Settings**.
5. In the **Near Detection Mode** area, click **Edit**.
6. In the **Near Detection Mode** dialog:
   * To disable near detection mode, clear the **Enable near detection mode** checkbox.
   * To enable near detection mode, select the **Enable near detection mode** checkbox.
7. Click **Save**.
8. Repeat this process for all additional readers for which you want to disable or enable near detection mode.

#### Unit Doors

Unit door locks within a Salto KS access system must first be woken up, and then a credential can be read. To use mobile keys with these locks, you must hold (tap) the back of the phone to the lock. There is no way to disable this requirement.

***

## Troubleshooting

For information about Salto KS ACS-related errors, see [Troubleshooting Your ACS](/low-level-apis/access-systems/troubleshooting-your-access-control-system).

***

## Where to Order

To purchase the Salto KS ACS and devices, contact Salto KS Sales.

<table>
  <thead>
    <tr>
      <th />

      <th />

      <th />

      <th />

      <th />
    </tr>
  </thead>

  <tbody>
    <tr>
      <td />

      <td>
        <strong>Salto KS Sales Contact Page</strong>
      </td>

      <td />

      <td>
        <a href="https://saltosystems.com/en/contact/">
          [https://saltosystems.com/en/contact/](https://saltosystems.com/en/contact/)
        </a>
      </td>

      <td>
        <a href="/images/salto-ks-logo.png">salto-ks-logo.png</a>
      </td>
    </tr>
  </tbody>
</table>


# Programming Salto KS PIN Code Credentials
Source: https://docs.seam.co/device-and-system-integration-guides/salto-ks-access-control-system/programming-code-based-salto-ks-credentials

Learn how to create Salto KS PIN codes.

To use the Seam API to program codes for users in a [Salto KS ACS](./):

1. Create an [ACS user](/low-level-apis/access-systems/user-management).
   * For Salto KS, you can specify the `access_schedule` for the new ACS user. An `access_schedule` consists of `starts_at` and `ends_at` times. In this case, a Salto KS ACS user appears as "unsubscribed" in the ACS until the `starts_at` time. Once the start time arrives, Seam switches the ACS user to "subscribed," which activates their access.
2. Assign access permissions to the ACS user by assigning them to one or more [access groups](/low-level-apis/access-systems/user-management/assigning-users-to-access-groups).
   * Each access group is preconfigured with specific entrances and schedules.
3. Create an [ACS credential](/low-level-apis/access-systems/managing-credentials).

   * Specify the ID of the ACS user.
   * Set the `access_method` to `code`.

   Creating a new `acs_credential` object triggers the Salto KS ACS to generate a PIN code for the user.

<Info>
  When you create a credential for a Salto KS ACS, you cannot specify a custom
  code. Instead, you must let Salto KS generate the PIN code.
</Info>

The following example walks you through this process:

**Code:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  // Get the ACS system.
  const buildingA = await seam.acs.systems.get({
    acs_system_id: '11111111-1111-1111-1111-111111111111',
  })

  // Step 1:
  // Create the new ACS user, including the
  // desired access schedule.
  const acsUser = await seam.acs.users.create({
    full_name: 'Jane Doe',
    acs_system_id: buildingA.acs_system_id,
    access_schedule: {
      starts_at: '2024-11-01T15:00:00.000Z',
      ends_at: '2024-11-04T11:00:00.000Z',
    },
  })

  // Step 2:
  // Add the ACS user to all desired access groups.
  const accessGroupIds = [
    '44444444-4444-4444-4444-333333333333',
    '44444444-4444-4444-4444-444444444444',
  ]
  for (const accessGroupId of accessGroupIds) {
    await seam.acs.users.addToAccessGroup({
      acs_user_id: acsUser.acs_user_id,
      acs_access_group_id: accessGroupId,
    })
  }

  // Step 3:
  // Create a PIN code for the ACS user.
  const pinCode = await seam.acs.credentials.create({
    acs_user_id: acsUser.acs_user_id,
    access_method: 'code',
  })

  // View the new credential.
  console.log(pinCode)
  ```

  ```bash cURL theme={null}
  # Get the ACS system.
  building_a=$(curl -X 'POST' \
    'https://connect.getseam.com/acs/systems/get' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d "{
    \"acs_system_id\": \"11111111-1111-1111-1111-111111111111\"
  }")

  # Step 1:
  # Create the new ACS user, including the
  # desired access schedule.
  acs_user=$(curl -X 'POST' \
    'https://connect.getseam.com/acs/users/create' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d "{
    \"full_name\": \"Jane Doe\",
    \"acs_system_id\": \"$(jq -r '.acs_system.acs_system_id' <<< ${building_a})\",
    \"access_schedule\": {
        \"starts_at\": \"2024-11-01T15:00:00.000Z\",
        \"ends_at\": \"2024-11-04T11:00:00.000Z\"
    }
  }")

  # Step 2:
  # Add the ACS user to all desired access groups.
  declare -a access_group_ids=("44444444-4444-4444-4444-333333333333" "44444444-4444-4444-4444-444444444444")
  for access_group_id in ${access_group_ids[@]};
  do
    curl -X 'POST' \
      'https://connect.getseam.com/acs/users/add_to_access_group' \
      -H 'accept: application/json' \
      -H "Authorization: Bearer ${SEAM_API_KEY}" \
      -H 'Content-Type: application/json' \
      -d "{
      \"acs_user_id\": \"$(jq -r '.acs_user.acs_user_id' <<< ${acs_user})\",
      \"acs_access_group_id\": \"$access_group_id\"
    }";
  done

  # Step 3:
  # Create a PIN code for the ACS user.
  pin_code=$(curl -X 'POST' \
    'https://connect.getseam.com/acs/credentials/create' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d "{
    \"acs_user_id\": \"$(jq -r '.acs_user.acs_user_id' <<< ${acs_user})\",
    \"access_method\": \"code\"
  }")

  # View the new credential.
  echo $pin_code
  ```

  ```python Python theme={null}
  # Get the ACS system.
  building_a = seam.acs.systems.get(
    acs_system_id="11111111-1111-1111-1111-111111111111"
  )

  # Step 1:
  # Create the new ACS user, including the
  # desired access schedule.
  acs_user = seam.acs.users.create(
    full_name = "Jane Doe",
    acs_system_id = building_a.acs_system_id,
    access_schedule = {
      "starts_at": "2024-11-01T15:00:00.000Z",
      "ends_at": "2024-11-04T11:00:00.000Z"
    }
  )

  # Step 2:
  # Add the ACS user to all desired access groups.
  access_group_ids = [
    "44444444-4444-4444-4444-333333333333",
    "44444444-4444-4444-4444-444444444444"
  ]
  for access_group_id in access_group_ids:
    seam.acs.users.add_to_access_group(
      acs_user_id = acs_user.acs_user_id,
      acs_access_group_id = access_group_id
    )

  # Step 3:
  # Create a PIN code for the ACS user.
  pin_code = seam.acs.credentials.create(
    acs_user_id = acs_user.acs_user_id,
    access_method = "code"
  )

  # View the new credential.
  pprint(pin_code)
  ```

  ```ruby Ruby theme={null}
  # Coming soon!
  ```

  ```php PHP theme={null}
  // Get the ACS system.
  $building_a = $seam->acs->systems->get(
    acs_system_id: "11111111-1111-1111-1111-111111111111"
  );

  // Step 1:
  // Create the new ACS user, including the
  // desired access schedule.
  $acs_user = $seam->acs->users->create(
    full_name: "Jane Doe",
    acs_system_id: $building_a->acs_system_id,
    access_schedule: array(
      "starts_at" => "2024-11-01T15:00:00.000Z",
      "ends_at" => "2024-11-04T11:00:00.000Z"
    )
  );

  // Step 2:
  // Add the ACS user to all desired access groups.
  $access_group_ids = array(
    "44444444-4444-4444-4444-333333333333",
    "44444444-4444-4444-4444-444444444444"
  );
  foreach ($access_group_ids as $access_group_id) {
    $seam->acs->users->add_to_access_group(
      acs_user_id: $acs_user->acs_user_id,
      acs_access_group_id: $access_group_id
    );
  };

  // Step 3:
  // Create a PIN code for the ACS user.
  $pin_code = $seam->acs->credentials->create(
    acs_user_id: $acs_user->acs_user_id,
    access_method: "code"
  );

  // View the new credential.
  echo json_encode($pin_code, JSON_PRETTY_PRINT);
  ```

  ```csharp C# theme={null}
  // Coming soon!
  ```
</CodeGroup>

**Output:**

<CodeGroup>
  ```json JavaScript theme={null}
  {
    acs_credential_id: '66666666-6666-6666-6666-666666666666',
    acs_system_id: '11111111-1111-1111-1111-111111111111',
    acs_user_id: '33333333-3333-3333-3333-333333333333',
    code: '123456',
    access_method: 'code',
    ...
  }
  ```

  ```json cURL theme={null}
  {
    "acs_credential":{
      "acs_credential_id": "66666666-6666-6666-6666-666666666666",
      "acs_system_id": "11111111-1111-1111-1111-111111111111",
      "acs_user_id": "33333333-3333-3333-3333-333333333333",
      "code": "123456",
      "access_method": "code",
      ...
    }
  }
  ```

  ```json Python theme={null}
  AcsCredential(
    acs_credential_id='66666666-6666-6666-6666-666666666666',
    acs_system_id='11111111-1111-1111-1111-111111111111',
    acs_user_id='33333333-3333-3333-3333-333333333333',
    code='123456',
    access_method='code',
    ...
  )
  ```

  ```json Ruby theme={null}
  # Coming soon!
  ```

  ```json PHP theme={null}
  {
    "acs_credential_id": "66666666-6666-6666-6666-666666666666",
    "acs_system_id": "11111111-1111-1111-1111-111111111111",
    "acs_user_id": "33333333-3333-3333-3333-333333333333",
    "code": "123456",
    "access_method": "code",
    ...
  }
  ```

  ```json C# theme={null}
  // Coming soon!
  ```
</CodeGroup>

***

## Next Steps

To learn more about using the Seam API with your Salto KS ACS, see the following topics:

* [Access Control Systems](/low-level-apis/access-systems)
* [Access Group-Based Access Control Systems](/low-level-apis/access-systems/connect-an-acs-to-seam/understanding-access-control-system-differences#access-group-based-access-control-systems)
* [Managing ACS Users](/low-level-apis/access-systems/user-management)
* [Managing Credentials](/low-level-apis/access-systems/managing-credentials)
* [Mobile Access](/capability-guides/mobile-access)
* [Access Control Systems](/api/acs/object) in the Seam API reference
* [User Identities](/api/user_identities/object) in the Seam API reference


# Programming Salto KS Mobile Credentials
Source: https://docs.seam.co/device-and-system-integration-guides/salto-ks-access-control-system/programming-salto-ks-mobile-credentials

Learn how to create mobile credentials in the Salto KS ACS.

You can create mobile credentials that enable your mobile app users to unlock entrances in your [Salto KS ACS](./). For more information about Seam mobile keys, see [Mobile Access](/capability-guides/mobile-access).

To use the Seam API to create mobile credentials for mobile app users in a Salto KS ACS:

1. Create a [user identity](/api/user_identities/object).

   Seam user identities enable you to match your own mobile app users to ACS users that you create using the Seam API.

2. Create an [ACS user](/low-level-apis/access-systems/user-management) on the Salto KS ACS or assign an existing ACS user to the user identity.\
   The resources that you create for the ACS user are available under the associated user identity.
   * For Salto KS, you can specify the `access_schedule` for the ACS user. The `access_schedule` consists of `starts_at` and `ends_at` times. In this case, a Salto KS ACS user appears as "unsubscribed" in the ACS until the `starts_at` time. Once the start time arrives, Seam switches the ACS user to "subscribed," which activates their access.

3. Assign the ACS user to one or more [access groups](/low-level-apis/access-systems/user-management/assigning-users-to-access-groups).
   * Each access group is preconfigured with the allowed entrances.

4. Create an [ACS credential](/low-level-apis/access-systems/managing-credentials) to represent the mobile key.
   * Specify the ID of the ACS user.
   * Set [`is_multi_phone_sync_credential`](/capability-guides/mobile-access/issuing-mobile-credentials-from-an-access-control-system#what-are-multi-phone-sync-credentials) to `true`.
   * Set the `access_method` to `mobile_key`.

The following example walks you through this process:

**Code:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  // Get the access system.
  const buildingA = await seam.acs.systems.get({
    acs_system_id: '11111111-1111-1111-1111-111111111111',
  })

  // Define the listing.
  const listing = {
    listingId: '2222222-2222',
    seamAccessGroupIds: ['555555-5555', '666666-6666'],
  }

  // Define the reservation.
  const reservation = {
    reservationId: '3333122-433',
    guestEmail: 'jane@example.com',
    listingId: '2222222-2222',
    checkIn: '2024-11-01T15:00:00.000Z',
    checkOut: '2024-11-04T11:00:00.000Z',
  }

  // Step 1:
  // Create a user identity that corresponds to your user's app account.
  const janeUser = await seam.userIdentities.create({
    email_address: 'jane@example.com',
  })

  // Step 2:
  // Create an access system user on the Salto KS access system.
  // Specify the access schedule for the user.
  const reservationUser = await seam.acs.users.create({
    user_identity_id: janeUser.user_identity_id,
    full_name: reservation.reservationId,
    acs_system_id: buildingA.acs_system_id,
    access_schedule: {
      starts_at: reservation.checkIn,
      ends_at: reservation.checkOut,
    },
  })

  // Step 3:
  // Add the access system user to all access groups for the listing.
  for (const groupIdToAdd of listing.seamAccessGroupIds) {
    await seam.acs.users.addToAccessGroup({
      acs_user_id: reservationUser.acs_user_id,
      acs_access_group_id: groupIdToAdd,
    })
  }

  // Step 4:
  // Create a mobile key for the access system user.
  const reservationMobileKey = await seam.acs.credentials.create({
    acs_user_id: reservationUser.acs_user_id,
    access_method: 'mobile_key',
    is_multi_phone_sync_credential: true,
  })

  // View the new credential.
  console.log(reservationMobileKey)
  ```

  ```bash cURL theme={null}
  # Get the access system.
  building_a=$(curl -X 'POST' \
    'https://connect.getseam.com/acs/systems/get' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d "{
    \"acs_system_id\": \"11111111-1111-1111-1111-111111111111\"
  }")

  # Define the listing.
  listing_id="2222222-2222"
  declare -a seam_access_group_ids=("555555-5555" "666666-6666")

  # Define the reservation.
  declare -A reservation=( \
    ["reservation_id"]="3333122-433" \
    ["guest_email"]="jane@example.com" \
    ["listing_id"]="2222222-2222", \
    ["check_in"]="2024-11-01T15:00:00.000Z" \
    ["check_out"]="2024-11-04T11:00:00.000Z" \
  )

  # Step 1:
  # Create a user identity that corresponds to your user's app account.
  jane_user=$(curl -X 'POST' \
    'https://connect.getseam.com/user_identities/create' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d '{
    "email_address": "jane@example.com"
  }')

  # Step 2:
  # Create an access system user on the Salto KS access system.
  # Specify the access schedule for the user.
  reservation_user=$(curl -X 'POST' \
    'https://connect.getseam.com/acs/users/create' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d "{
    \"user_identity_id\": \"$(jq -r '.user_identity.user_identity_id' <<< ${jane_user})\",
    \"full_name\": \"${reservation[reservation_id]}\",
    \"acs_system_id\": \"$(jq -r '.acs_system.acs_system_id' <<< ${building_a})\",
    \"access_schedule\": {
        \"starts_at\": \"${reservation[check_in]}\",
        \"ends_at\": \"${reservation[check_out]}\"
    }
  }")

  # Step 3:
  # Add the access system user to all access groups for the listing.
  for group_id_to_add in ${seam_access_group_ids[@]};
  do
    curl -X 'POST' \
      'https://connect.getseam.com/acs/users/add_to_access_group' \
      -H 'accept: application/json' \
      -H "Authorization: Bearer ${SEAM_API_KEY}" \
      -H 'Content-Type: application/json' \
      -d "{
      \"acs_user_id\": \"$(jq -r '.acs_user.acs_user_id' <<< ${reservation_user})\",
      \"acs_access_group_id\": \"$group_id_to_add\"
    }";
  done

  # Step 4:
  # Create a mobile key for the access system user.
  reservation_mobile_key=$(curl -X 'POST' \
    'https://connect.getseam.com/acs/credentials/create' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d "{
    \"acs_user_id\": \"$(jq -r '.acs_user.acs_user_id' <<< ${reservation_user})\",
    \"is_multi_phone_sync_credential\": true,
    \"access_method\": \"mobile_key\"
  }");

  # View the new credential.
  echo $reservation_mobile_key;
  ```

  ```python Python theme={null}
  # Get the access system.
  building_a = seam.acs.systems.get(
    acs_system_id = "11111111-1111-1111-1111-111111111111"
  )

  # Define the listing.
  listing = {
    "listing_id": "2222222-2222",
    "seam_access_group_ids": [
      "555555-5555",
      "666666-6666"
    ]
  }

  # Define the reservation.
  reservation = {
    "reservation_id": "3333122-433",
    "guest_email": "jane@example.com",
    "listing_id": "2222222-2222",
    "check_in": "2024-11-01T15:00:00.000Z",
    "check_out": "2024-11-04T11:00:00.000Z"
  }

  # Step 1:
  # Create a user identity that corresponds to your user's mobile app account.
  jane_user = seam.user_identities.create(
    email_address = "jane@example.com"
  )

  # Step 2:
  # Create an access system user on the Salto KS access system.
  # Specify the access schedule for the user.
  reservation_user = seam.acs.users.create(
    user_identity_id = jane_user.user_identity_id,
    acs_system_id = building_a.acs_system_id,
    full_name = reservation["reservation_id"],
    access_schedule = {
      "starts_at": reservation["check_in"],
      "ends_at": reservation["check_out"]
    }
  )

  # Step 3:
  # Add the access system user to all access groups for the listing.
  for group_id_to_add in listing["seam_access_group_ids"]:
    seam.acs.users.add_to_access_group(
      acs_user_id = reservation_user.acs_user_id,
      acs_access_group_id = group_id_to_add
    )

  # Step 4:
  # Create a mobile key for the access system user.
  reservation_mobile_key = seam.acs.credentials.create(
    acs_user_id = reservation_user.acs_user_id,
    is_multi_phone_sync_credential = True,
    access_method = "mobile_key"
  )

  # View the new credential.
  pprint(reservation_mobile_key)
  ```

  ```ruby Ruby theme={null}
  # Get the access system.
  building_a = seam.acs.systems.get(
    acs_system_id: "11111111-1111-1111-1111-111111111111"
  )

  # Define the listing.
  listing = {
    listing_id: "2222222-2222",
    seam_access_group_ids: [
      "555555-5555",
      "666666-6666"
    ]
  }

  # Define the reservation.
  reservation = {
    reservation_id: "3333122-433",
    guest_email: "jane@example.com",
    listing_id: "2222222-2222",
    check_in: "2024-11-01T15:00:00.000Z",
    check_out: "2024-11-04T11:00:00.000Z"
  }

  # Step 1:
  # Create a user identity that corresponds to your user's app account.
  jane_user = seam.user_identities.create(
    email_address = "jane@example.com"
  )

  # Step 2:
  # Create an access system user on the Salto KS access system.
  # Specify the access schedule for the user.
  reservation_user = seam.acs.users.create(
    user_identity_id: jane_user.user_identity_id,
    acs_system_id: building_a.acs_system_id,
    full_name: reservation[:reservation_id],
    access_schedule = {
      "starts_at": reservation[:check_in],
      "ends_at": reservation[:check_out]
    }
  )

  # Step 3:
  # Add the access system user to all access groups for the listing.
  access_group_ids = [
    "44444444-4444-4444-4444-333333333333",
    "44444444-4444-4444-4444-444444444444"
  ]
  listing[:access_group_ids].each do |group_id_to_add|
    seam.acs.users.add_to_access_group(
      acs_user_id: reservation[:acs_user_id],
      acs_access_group_id: group_id_to_add
    )
  end

  # Step 4:
  # Create a mobile key for the access system user.
  reservation_mobile_key = seam.acs.credentials.create(
    acs_user_id: reservation_user[:acs_user_id],
    is_multi_phone_sync_credential: true,
    access_method: "mobile_key"
  )

  # View the new credential.
  puts reservation_mobile_key.inspect
  ```

  ```php PHP theme={null}
  // Get the access system.
  $building_a = $seam->acs->systems->get(
    acs_system_id: "11111111-1111-1111-1111-111111111111"
  );

  // Define the listing.
  $listing = array(
    "listing_id" => "2222222-2222",
    "seam_access_group_ids" => array(
      "555555-5555",
      "666666-6666"
    )
  );

  // Define the reservation.
  $reservation = array(
    "reservation_id" => "3333122-433",
    "guest_email" => "jane@example.com",
    "listing_id" => "2222222-2222",
    "check_in" => "2024-11-01T15:00:00.000Z",
    "check_out" => "2024-11-04T11:00:00.000Z"
  );

  // Step 1:
  // Create a user identity that corresponds to your user's app account.
  $jane_user = $seam->user_identities->create(
    email_address: "jane@example.com"
  );

  // Step 2:
  // Create an access system user on the Salto KS access system.
  // Specify the access schedule for the user.
  $reservation_user = $seam->acs->users->create(
    user_identity_id: $jane_user->user_identity_id,
    full_name: $reservation["reservation_id"],
    acs_system_id: $building_a->acs_system_id,
    access_schedule: array(
      "starts_at" => $reservation["check_in"],
      "ends_at" => $reservation["check_out"]
    )
  );

  // Step 3:
  // Add the access system user to all access groups for the listing.
  foreach ($listing['seam_access_group_ids'] as $group_id_to_add) {
    $seam->acs->users->add_to_access_group(
      acs_user_id: $reservation_user->acs_user_id,
      acs_access_group_id: $group_id_to_add
    );
  };

  // Step 4:
  // Create a mobile key for the access system user.
  $reservation_mobile_key = $seam->acs->credentials->create(
    acs_user_id: $reservation_user->acs_user_id,
    is_multi_phone_sync_credential: true,
    access_method: "mobile_key"
  );

  // View the new credential.
  echo json_encode($reservation_mobile_key, JSON_PRETTY_PRINT);
  ```

  ```csharp C# theme={null}
  // Coming soon!
  ```
</CodeGroup>

**Output:**

<CodeGroup>
  ```json JavaScript theme={null}
  {
    acs_credential_id: '66666666-6666-6666-6666-666666666666',
    acs_system_id: '11111111-1111-1111-1111-111111111111',
    acs_user_id: '33333333-3333-3333-3333-333333333333',
    access_method: 'mobile_key',
    ...
  }
  ```

  ```json cURL theme={null}
  {
    "acs_credential":{
      "acs_credential_id": "66666666-6666-6666-6666-666666666666",
      "acs_system_id": "11111111-1111-1111-1111-111111111111",
      "acs_user_id": "33333333-3333-3333-3333-333333333333",
      "access_method": "mobile_key",
      ...
    }
  }
  ```

  ```json Python theme={null}
  AcsCredential(
    acs_credential_id='66666666-6666-6666-6666-666666666666',
    acs_system_id='11111111-1111-1111-1111-111111111111',
    acs_user_id='33333333-3333-3333-3333-333333333333',
    access_method='mobile_key',
    ...
  )
  ```

  ```json Ruby theme={null}
  <Seam::Resources::AcsCredential:0x00618
    acs_credential_id="66666666-6666-6666-6666-666666666666"
    acs_system_id="11111111-1111-1111-1111-111111111111"
    acs_user_id="33333333-3333-3333-3333-333333333333"
    access_method="mobile_key"
    ...
  >
  ```

  ```json PHP theme={null}
  {
    "acs_credential_id": "66666666-6666-6666-6666-666666666666",
    "acs_system_id": "11111111-1111-1111-1111-111111111111",
    "acs_user_id": "33333333-3333-3333-3333-333333333333",
    "access_method": "mobile_key",
    ...
  }
  ```

  ```json C# theme={null}
  // Coming soon!
  ```
</CodeGroup>

***

## Next Steps

To learn more about using the Seam API with your Salto KS ACS, see the following topics:

* [Programming Code-Based Salto KS Credentials](./programming-code-based-salto-ks-credentials)
* [Access Control Systems](/low-level-apis/access-systems)
* [Credential-based ACS](/low-level-apis/access-systems/connect-an-acs-to-seam/understanding-access-control-system-differences)
* [Managing ACS Users](/low-level-apis/access-systems/user-management)
* [Managing Credentials](/low-level-apis/access-systems/managing-credentials)
* [Mobile Access](/capability-guides/mobile-access)
* [Access Control Systems](/api/acs/object) in the Seam API reference
* [User Identities](/api/user_identities/object) in the Seam API reference


# Salto KS Setup Instructions
Source: https://docs.seam.co/device-and-system-integration-guides/salto-ks-access-control-system/salto-ks-setup-instructions

Learn how to connect your Salto KS access system to Seam.

This topic describes how to connect your Salto KS sites to Seam.

## Prerequisites

Note the following requirements before connecting your Salto KS access control system to Seam:

### Site Admin

You must use a Salto KS web app user account that has "Site Admin" rights.

### Salto KS Production Environment

You must use a Salto KS production environment account to connect to Seam. You cannot use "Accept Environment" credentials.

To confirm that your Salto KS account is a production environment account, note the Salto KS dashboard URL. Make sure that the subdomain within this URL is `app`, for example, `https://app.saltoks.com`.

A subdomain of `app-accept`, for example, `https://app-accept.saltoks.com`, indicates an "Accept Environment" that you cannot connect to Seam.

### Released Salto KS Sites

Make sure that your installer has released your Salto KS sites. Seam cannot perform actions on unreleased Salto KS sites.

***

## Setup Process

To connect the Salto KS ACS to Seam:

1. Create a [Connect Webview](/core-concepts/connect-webviews).
2. Display the Connect Webview and perform the following steps:
   1. If the Connect Webview displays multiple brand options, select **Salto KS**.
   2. In the **Enter your credentials** dialog, type your username and password for the Salto KS web app.
   3. Select the Salto KS sites that you want to integrate with Seam.
   4. Click **Allow and Continue** to confirm that you allow Seam to add the requisite admin user to your Salto KS site for the integration with Seam.

      <Warning> Do not suspend or remove the Seam Integration admin user from your Salto KS site. </Warning>
   5. Click **Close**.


# Sandbox Salto KS Access Control System
Source: https://docs.seam.co/device-and-system-integration-guides/salto-ks-access-control-system/sandbox-salto-ks-access-control-system

Add a virtual Salto KS access control system to your Seam sandbox workspace using these sample credentials to test your integration without real hardware.

Use the following set of credentials to add the virtual [Salto KS access control system](/device-and-system-integration-guides/salto-ks-access-control-system) to your Seam [sandbox workspace](/core-concepts/workspaces#sandbox-workspaces):

| Email Address                               | Password |
| ------------------------------------------- | -------- |
| [jane@example.com](mailto:jane@example.com) | 1234     |


# Special Requirements for Android Mobile Access SDK Development
Source: https://docs.seam.co/device-and-system-integration-guides/salto-ks-access-control-system/special-requirements-for-android-mobile-access-sdk-development

Learn the requirements and restrictions for developing Android apps that integrate with the Salto KS ACS.

## Add Required Dependencies

To develop an Android mobile app that integrates with the Salto KS ACS, you must add a set of required dependencies, as follows:

1. Copy the Seam Android SDK `.aar` file (for example, `seam-phone-sdk-android-release.aar`) into the `libs` directory for your project.
2. Add the following lines to the [`app/build.gradle`](https://developer.android.com/studio/build/dependencies) file for your app:

```gradle theme={null}
gradle
repositories {
    flatDir {
        dirs 'libs'
    }
    mavenCentral()
}
dependencies {
    implementation(files('libs/seam-phone-sdk-android-release.aar'))

    // Required dependencies
    implementation("androidx.core:core-ktx:1.9.0")
    implementation("org.jetbrains.kotlinx:kotlinx-serialization-json:1.5.1")
    implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.7.3")
    implementation("io.ktor:ktor-client-core:2.3.5")
    implementation("io.ktor:ktor-client-cio:2.3.5")
    implementation("io.ktor:ktor-client-cio-jvm:2.3.5")
    implementation("org.bouncycastle:bcprov-jdk15on:1.69")
    implementation("com.google.code.gson:gson:2.8.5")
    implementation("org.slf4j:slf4j-api:1.7.25")
}
```


# Get started with Salto KS Locks
Source: https://docs.seam.co/device-and-system-integration-guides/salto-locks/get-started-with-salto-locks

Learn how to connect and control your Salto lock with the Seam API.

## Overview

Seam provides a universal API to connect and control many brands of locks. This guide provides a rapid introduction to connecting and controlling your [Salto](https://www.seam.co/manufacturers/salto) locks using the Seam API. To learn more about other device brands supported by the Seam API, such as Yale, Schlage, and August, head over to our [integration page](https://www.seam.co/supported-devices-and-systems).

Note that Salto offers multiple lines of products: Salto Space, Salto KS, and Salto Nebula. This guide is specifically for Salto KS. Salto Space is an on-prem system that is offline. Salto Nebula is not yet fully available as of this writing.

## 1 — Install Seam SDK

Seam provides client libraries for many languages, such as JavaScript, Python, Ruby, PHP, and others, as well as a Postman collection and [OpenAPI](https://connect.getseam.com/openapi.json) spec.

* JavaScript / TypeScript ([npm](https://www.npmjs.com/package/seam), [GitHub](https://github.com/seamapi/javascript))
* Python ([pip](https://pypi.org/project/seam/), [GitHub](https://github.com/seamapi/python))
* Ruby Gem ([rubygem](https://rubygems.org/gems/seam), [GitHub](https://github.com/seamapi/ruby))
* PHP ([packagist](https://packagist.org/packages/seamapi/seam), [GitHub](https://github.com/seamapi/php))
* C# ([nuget](https://www.nuget.org/packages/Seam), [GitHub](https://github.com/seamapi/csharp))

<Tabs>
  <Tab title="JavaScript">
    ```bash theme={null}
    npm i seam
    ```
  </Tab>

  <Tab title="Python">
    ```bash theme={null}
    pip install seam
    # For some development environments, use pip3 in this command instead of pip.
    ```
  </Tab>

  <Tab title="Ruby">
    ```bash theme={null}
    bundle add seam
    ```
  </Tab>

  <Tab title="PHP">
    ```bash theme={null}
    composer require seamapi/seam
    ```
  </Tab>

  <Tab title="C#">
    Install using [nuget](https://www.nuget.org/packages/Seam).
  </Tab>
</Tabs>

Once installed, [sign-up for Seam](https://console.seam.co/) to get your API key, and export it as an environment variable:

```
$ export SEAM_API_KEY=seam_test2ZTo_0mEYQW2TvNDCxG5Atpj85Ffw
```

<Info>
  This guide uses a Sandbox Workspace. Only virtual devices can be connected. If
  you need to connect a real Salto site, use a non-sandbox workspace and API
  key.
</Info>

## 2 — Link Your Salto KS Account with Seam

To control your Salto locks via the Seam API, you must first authorize your Seam workspace against your Salto KS account. To do so, Seam provides[ Connect Webviews](/core-concepts/connect-webviews): pre-built UX flows that walk you through authorizing your application to control your Salto sites.

#### Create a Connect Webview

**Code:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  import { Seam } from 'seam'

  const seam = new Seam() // Seam automatically uses your exported SEAM_API_KEY.

  const connectWebview = await seam.connectWebviews.create()

  console.log(connectWebview.login_successful) // false

  // Use the returned Connect Webview URL to display
  // the Connect Webview authorization flow to your user.
  console.log(connectWebview.url)
  ```

  ```bash cURL theme={null}
  curl -X 'POST' \
    'https://connect.getseam.com/connect_webviews/create' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d '{}' | jq -r '"Login Successful (false): " + (.connect_webview.login_successful | tostring),
    "URL: " + .connect_webview.url'
    # Use the returned Connect Webview URL to display
    # the Connect Webview authorization flow to your user.
  ```

  ```python Python theme={null}
  from seam import Seam

  seam = Seam()  # Seam automatically uses your exported SEAM_API_KEY.

  connect_webview = seam.connect_webviews.create()

  assert connect_webview.login_successful is False

  # Use the returned Connect Webview URL to display
  # the Connect Webview authorization flow to your user.
  print(connect_webview.url)
  ```

  ```ruby Ruby theme={null}
  require "seam"

  seam = Seam.new() # Seam automatically uses your exported SEAM_API_KEY.

  connect_webview = seam.connect_webviews.create()

  puts connect_webview.login_successful # false

  # Use the returned Connect Webview URL to display
  # the Connect Webview authorization flow to your user.
  puts connect_webview.url
  ```

  ```php PHP theme={null}
  <?php
  require 'vendor/autoload.php';

  $seam = new Seam\SeamClient(); // Seam automatically uses your exported SEAM_API_KEY.

  $connect_webview = $seam->connect_webviews->create();

  echo $connect_webview->login_successful ? 'true' : 'false', "\n"; // false

  // Use the returned Connect Webview URL to display
  // the Connect Webview authorization flow to your user.
  echo $connect_webview->url;
  ```

  ```csharp C# theme={null}
  using Seam.Client;

  var seam = new SeamClient(apiToken: SEAM_API_KEY);

  var connectWebview = seam.ConnectWebviews.Create();

  Console.WriteLine(connectWebview.LoginSuccessful); // False

  // Use the returned Connect Webview URL to display
  // the Connect Webview authorization flow to your user.
  Console.WriteLine(connectWebview.Url);
  ```
</CodeGroup>

**Output:**

<CodeGroup>
  ```json JavaScript theme={null}
  false
  https://connect.getseam.com/connect_webviews/view?connect_webview_id=12345678-1234-1234-1234-123456789012&auth_token=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
  ```

  ```json cURL theme={null}
  Login Successful (false): false
  https://connect.getseam.com/connect_webviews/view?connect_webview_id=12345678-1234-1234-1234-123456789012&auth_token=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
  ```

  ```json Python theme={null}
  https://connect.getseam.com/connect_webviews/view?connect_webview_id=12345678-1234-1234-1234-123456789012&auth_token=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
  ```

  ```json Ruby theme={null}
  false
  https://connect.getseam.com/connect_webviews/view?connect_webview_id=12345678-1234-1234-1234-123456789012&auth_token=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
  ```

  ```json PHP theme={null}
  false
  https://connect.getseam.com/connect_webviews/view?connect_webview_id=12345678-1234-1234-1234-123456789012&auth_token=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
  ```

  ```json C# theme={null}
  False
  https://connect.getseam.com/connect_webviews/view?connect_webview_id=12345678-1234-1234-1234-123456789012&auth_token=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
  ```
</CodeGroup>

#### Authorize Your Workspace

Navigate to the URL returned by the Webview object. Since you are using a sandbox workspace, complete the login flow by entering the Salto [sandbox test accounts ](./sandbox-salto-ks-locks)credentials below:

* **email:** [jane@example.com](mailto:jane@example.com)
* **password:** 1234

<Warning>
  During the authorization process, Seam adds an admin user to your Salto KS
  site. Do not suspend or remove this Seam Integration admin user.
</Warning>

<picture>
  <source />

  <img alt="Seam Connect Webview flow to connect your Salto KS account with Seam" />
</picture>

Confirm the Connect Webview was successful by querying its status:

<CodeGroup>
  ```javascript JavaScript theme={null}
  const updatedWebview = await seam.connectWebviews.get(
    connectWebview.connect_webview_id,
  )

  console.log(updatedWebview.login_successful) // true

  ```

  ```python Python theme={null}
  updated_webview = seam.connect_webviews.get(connect_webview_id: webview.connect_webview_id)

  assert updated_webview.login_successful # true
  ```

  ```ruby Ruby theme={null}
  updated_webview = seam.connect_webviews.get(connect_webview_id: webview.connect_webview_id)

  puts updated_webview.login_successful # true

  ```

  ```php PHP theme={null}
  $webview = $seam->connect_webviews->get('729847ff-98e0-418d-aeba-1e3cb38157c6');
  assert($webview->status == 'pending');
  ```
</CodeGroup>

## 3 — Retrieve Salto Devices

After a Salto account is linked with Seam, you can retrieve devices for this Salto account. The Seam API exposes most of the device's properties such as battery level.

<CodeGroup>
  ```javascript JavaScript theme={null}
  const allLocks = await seam.locks.list()

  const someLock = allLocks[0]

  console.log(someLock.properties.online) // true
  console.log(someLock.properties.locked) // true

  console.log(someLock)
  /_
  {
  "device_id": "681bf7bc-e7c6-48e6-acfe-6dbabd0615c5",
  "device_type": "salto_lock",
  "capabilities_supported": [
  "access_code",
  "lock"
  ],
  "properties": {
  "locked": true,
  "online": true,
  "battery_level": 1,
  "salto_metadata": {
  "model": "wall_reader_pin",
  "lock_id": "lock_2",
  "lock_type": "wall_reader_pin",
  "locked_state": "locked",
  "battery_level": "fresh",
  "customer_reference": "BACK DOOR"
  },
  "has_direct_power": true,
  "max_active_codes_supported": 100,
  "supported_code_lengths": [
  6
  ],
  "name": "BACK DOOR"
  },
  "location": null,
  "connected_account_id": "690dead6-e176-4f25-930b-9aef7c7137ad",
  "workspace_id": "d7418ff3-a476-4f48-9a4b-211d1d21a03d",
  "created_at": "2023-02-08T22:14:09.921Z",
  "errors": [],
  "warnings": []
  }
  _/

  ```

  ```python Python theme={null}
  all_locks = seam.locks.list()

  some_lock = all_locks[0]

  assert some_lock.properties["online"] is True
  assert some_lock.properties["battery_level"] is True

  print(some_lock)
  # Device(device_id='681bf7bc-e7c6-48e6-acfe-6dbabd0615c5', device_type='salto_lock', location=None, properties={'locked': True, 'online': True, 'battery_level': 1, 'salto_metadata': {'model': 'wall_reader_pin', 'lock_id': 'lock_2', 'lock_type': 'wall_reader_pin', 'locked_state': 'locked', 'battery_level': 'fresh', 'customer_reference': 'BACK DOOR'}, 'has_direct_power': True, 'max_active_codes_supported': 100, 'supported_code_lengths': [6], 'name': 'BACK DOOR'}, capabilities_supported=['access_code', 'lock'])
  ```

  ```ruby Ruby theme={null}
  some_lock = seam.locks.list.first

  puts some_lock.properties.online # true
  puts some_lock.properties.locked # true

  puts some_lock

  # <Seam::Device:0x005c8

  # device_id="681bf7bc-e7c6-48e6-acfe-6dbabd0615c5"

  # device_type="salto_lock"

  # properties={"locked"=>true, "online"=>true, "battery_level"=>1, "salto_metadata"=>{"model"=>"wall_reader_pin", "lock_id"=>"lock_2", "lock_type"=>"wall_reader_pin", "locked_state"=>"locked", "battery_level"=>"fresh", "customer_reference"=>"BACK DOOR"}, "has_direct_power"=>true, "max_active_codes_supported": 100, "supported_code_lengths"=>[6], "name"=>"BACK DOOR"}

  # created_at=2023-02-08 22:14:09.921 UTC

  # errors=[]

  # warnings=[]>

  ```

  ```php PHP theme={null}
  use Seam\SeamClient;

  $seam = new SeamClient('YOUR_API_KEY');

  $locks = $seam->locks->list();

  echo json_encode($locks);
  /*
  [{"device_id":"681bf7bc-e7c6-48e6-acfe-6dbabd0615c5","workspace_id":"d7418ff3-a476-4f48-9a4b-211d1d21a03d","connected_account_id":"690dead6-e176-4f25-930b-9aef7c7137ad","device_type":"salto_lock","properties":{"online":true,"locked":true,"door_open":null,"battery_level":1,"name":"BACK DOOR","manufacturer":null,"august_metadata":null,"schlage_metadata":null,"smartthings_metadata":null},"location":null,"created_at":"2023-02-08T22:14:09.921Z","capabilities_supported":["access_code","lock"],"errors":[]},{"device_id":"c9fc699a-3f87-4d23-b5c2-1f8ac85aeca1","workspace_id":"d7418ff3-a476-4f48-9a4b-211d1d21a03d","connected_account_id":"690dead6-e176-4f25-930b-9aef7c7137ad","device_type":"salto_lock","properties":{"online":true,"locked":true,"door_open":null,"battery_level":1,"name":"EXTRA DOOR","manufacturer":null,"august_metadata":null,"schlage_metadata":null,"smartthings_metadata":null},"location":null,"created_at":"2023-02-08T22:14:09.952Z","capabilities_supported":[],"errors":[]},{"device_id":"da9dcedb-20ee-46df-8c08-e5268f624377","workspace_id":"d7418ff3-a476-4f48-9a4b-211d1d21a03d","connected_account_id":"690dead6-e176-4f25-930b-9aef7c7137ad","device_type":"salto_lock","properties":{"online":true,"locked":true,"door_open":null,"battery_level":1,"name":"FRONT_DOOR","manufacturer":null,"august_metadata":null,"schlage_metadata":null,"smartthings_metadata":null},"location":null,"created_at":"2023-02-08T22:14:09.890Z","capabilities_supported":["access_code","lock"],"errors":[]}]
  */
  ```
</CodeGroup>

### 4 — Locking & Unlocking a Door

Next, you can perform the basic action of locking and unlocking a door.

<Warning>
  Note that Salto KS disables this functionality by default and requires a
  special pass-through waiver via Seam. Please contact Seam to configure your IQ
  hubs to enable this functionality.
</Warning>

> **`POST`** `/locks/lock_door`
>
> See the [API Reference](/api/locks/lock_door) for details.

## Unlock a door

<mark>`POST`</mark>
`https://connect.getseam.com/locks/unlock_door`

#### Request Body

| Name       | Type   | Description |
| ---------- | ------ | ----------- |
| device\_id | String |             |

<CodeGroup>
  ```javascript JavaScript theme={null}
  // lock the door
  await seam.locks.lockDoor(someLock.device_id)
  const updatedLock = await seam.locks.get(someLock.device_id)
  console.log(updatedLock.properties.locked) // true

  // unlock the door
  await seam.locks.unlockDoor(someLock.device_id)
  updatedLock = await seam.locks.get(someLock.device_id)
  console.log(updatedLock.properties.locked) // false

  ```

  ```python Python theme={null}
  # lock the door
  seam.locks.lock_door(device_id: some_lock.device_id)
  updated_lock = seam.locks.get(device_id: some_lock.device_id)
  assert updated_lock.properties["locked"] is True

  # Now unlock the door
  seam.locks.unlock_door(device_id: some_lock.device_id)
  updated_lock = seam.locks.get(device_id: some_lock.device_id)
  assert updated_lock.properties["locked"] is False
  ```

  ```ruby Ruby theme={null}
  # lock the door
  seam.locks.lock_door(device_id: some_lock.device_id)
  updated_lock = seam.locks.get(device_id: some_lock.device_id)
  puts updated_lock.properties.locked # true

  # unlock the door

  seam.locks.unlock_door(device_id: some_lock.device_id)
  updated_lock = seam.locks.get(device_id: some_lock.device_id)
  puts updated_lock.properties.locked # false

  ```

  ```php PHP theme={null}
  use Seam\SeamClient;

  $seam = new SeamClient('YOUR_API_KEY');

  $some_lock = $seam->locks->list()[0];

  # unlock the door
  $seam->locks->unlock_door($lock->device_id);
  # lock the door
  $seam->locks->lock_door($lock->device_id);
  ```
</CodeGroup>

### 5 — Setting Access Code on Salto Lock

Some Salto locks and access points will have a keypad available to program access codes. These codes can then be entered to unlock the door.

The Seam API makes it easy to program both `ongoing` codes and `timebound` codes on an Salto lock. You can find out more about Salto lock access code in our [core concept section on access codes.](/low-level-apis/smart-locks/access-codes)

<Info>
  Salto does not let you specify a code for an access code. Instead Salto
  generates a 6-digit code, which the Seam API returns.
</Info>

<CodeGroup>
  ```javascript JavaScript theme={null}
  // create an ongoing code
  await seam.accessCodes.create({
    device_id: someLock.device_id,
    name: 'Personal Access Code',
  })

  // create a timebound code
  await seam.accessCodes.create({
  device_id: someLock.device_id,
  name: 'My Temp Access Code',
  starts_at: '2028-11-12T19:23:42+0000',
  ends_at: '2028-11-13T19:23:42+0000',
  })

  // use a device_id as the "device_id" parameter
  await seam.accessCodes.list({
  device_id: someLock.device_id,
  })

  /_
  [
  {
  access_code_id: '631a3a30-3fa7-462a-b3bc-65528ccf8765',
  device_id: '681bf7bc-e7c6-48e6-acfe-6dbabd0615c5',
  name: 'My Temp Access Code',
  code: null,
  is_waiting_for_code_assignment: true,
  common_code_key: null,
  type: 'time_bound',
  status: 'unset',
  starts_at: '2028-08-12T19:24:00.000Z',
  ends_at: '2028-08-13T19:24:00.000Z',
  created_at: '2023-02-08T23:28:57.061Z',
  errors: [],
  warnings: []
  },
  {
  access_code_id: '774986f8-5fad-4911-a4fb-e5a2ef9f15bd',
  device_id: '681bf7bc-e7c6-48e6-acfe-6dbabd0615c5',
  name: 'Personal Access Code',
  code: '10542',
  common_code_key: null,
  type: 'ongoing',
  status: 'set',
  created_at: '2023-02-08T23:10:54.096Z',
  errors: [],
  warnings: []
  },
  ]
  _/

  ```

  ```python Python theme={null}
  # create an ongoing code
  seam.access_codes.create(
    device=some_lock,
    name="Personal Access Code")

  # create a timebound code
  seam.access_codes.create(
    device=some_lock,
    name="My Temp Access Code",
    starts_at="2028-08-12T19:23:42+0000",
    ends_at="2028-08-13T19:23:42+0000")

  # you can use a device or a device_id as the "device" parameter
  seam.access_codes.list(device=some_lock)

  # [
  #   AccessCode(access_code_id='631a3a30-3fa7-462a-b3bc-65528ccf8765', type='time_bound', code=None, starts_at='2028-08-12T19:24:00.000Z', ends_at='2028-08-13T19:24:00.000Z', name='My Temp Access Code', status='unset', common_code_key=None),
  #  AccessCode(access_code_id='4d2f4952-5446-4051-ba7e-a6fc01a376d7', type='ongoing', code='59026', starts_at=None, ends_at=None, name='Personal Access Code', status='set', common_code_key=None)
  #  ]

  ```

  ```ruby Ruby theme={null}
  # create an ongoing code
  seam.access_codes.create(
    device_id: some_lock.device_id, name: 'Personal Access Code'
  )

  # create a timebound code

  seam.access_codes.create(
  device_id: some_lock.device_id,
  name: 'My Temp Access Code',
  starts_at: '2028-08-12T19:23:42+0000',
  ends_at: '2028-08-13T19:23:42+0000'
  )

  seam.access_codes.list(device_id: some_lock.device_id)

  # [<Seam::AccessCode:0x00690

  # access_code_id="631a3a30-3fa7-462a-b3bc-65528ccf8765"

  # name="My Temp Access Code"

  # code=nil

  # type="time_bound"

  # starts_at=2028-08-12 19:24:00 UTC

  # ends_at=2028-08-13 19:24:00 UTC

  # errors=[]

  # warnings=[]>, <Seam::AccessCode:0x006b8

  # access_code_id="774986f8-5fad-4911-a4fb-e5a2ef9f15bd"

  # name="Personal Access Code"

  # code="10542"

  # type="ongoing"

  # errors=[]

  # warnings=[]>]

  ```

  ```php PHP theme={null}
  use Seam\SeamClient;

  $seam = new SeamClient("YOUR_API_KEY");

  $some_lock = $seam->locks->list()[0];
  $seam->access_codes->create(
    device_id: $some_lock->device_id, name: 'Personal Access Code'
  );

  $seam->access_codes->create(
    device_id: $some_lock->device_id,
    name: 'My Temp Access Code',
    starts_at: '2028-08-12T19:23:42+0000',
    ends_at: '2028-08-13T19:23:42+0000'
  );

  echo json_encode($access_code)
  /*
  [{"access_code_id":"19cea367-fd8c-40b7-9ce3-6dec76fe1763","name":"My Temp Access Code","type":"time_bound","status":"unset","starts_at":"2028-08-12T19:24:00.000Z","ends_at":"2028-08-13T19:24:00.000Z","code":null,"created_at":"2023-02-09T05:53:46.293Z","errors":[],"warnings":[]},{"access_code_id":"f797a8f0-b8f7-4734-9bea-962de5cad413","name":"Personal Access Code","type":"ongoing","status":"set","starts_at":null,"ends_at":null,"code":"37840","created_at":"2023-02-09T05:53:46.172Z","errors":[],"warnings":[]}]
  */
  ```
</CodeGroup>

###

## Next Steps

Now that you've completed this guide, you can try to connect a real Salto device. To do so, make sure to switch to a non-sandbox workspace and API key as real devices cannot be connected to sandbox workspaces.

In addition, if you'd like to explore other aspects of Seam, here is a list of helpful resources:

* [Schlage Getting Started Guide](../schlage-locks/get-started-with-schlage-locks)
* [Yale Getting Started Guide](../yale-locks/get-started-with-yale-locks)
* [SmartThings Getting Started Guide](../smartthings-hubs-+-devices/get-started-with-smartthings-hubs-+-smart-locks)
* [Receiving webhook](/developer-tools/webhooks) for [device events](/api/events/list)
* [Core Concepts](/core-concepts/overview)

If you have any questions or want to report an issue, email us at [support@seam.co](mailto:support@seam.co).


# Salto KS Locks
Source: https://docs.seam.co/device-and-system-integration-guides/salto-locks/index

Guide for using Salto KS door locks with Seam

<img alt="Salto logo" />

## Overview

Salto Systems produces world-class electronic access control solutions. Their locks work with a vast array of entrance types, from traditional doors and elevators, to key cylinders and parking stiles. They also support a versatile range of key credentials; their locks work with RFID tags, mobile keys, and PIN codes. Using their mobile app and app dashboard, businesses can easily assign, monitor, and revoke access rights.

<Info>
  Seam supports two integrations for Salto KS. We recommend using the [Salto KS
  access control system
  integration](/device-and-system-integration-guides/salto-ks-access-control-system)
  because it provides more robust functionality, such as managing ACS users and
  credentials. However, if you want to connect a single or just a few Salto KS
  locks, you can choose the Salto KS lock integration that this topic describes.
</Info>

***

## Supported Devices

<DeviceList />

This integration works any devices connected via their [Salto KS platform](https://saltoks.com/).

For detailed information about the Salto devices that Seam supports, see our [Salto Supported Devices page](https://www.seam.co/manufacturers/salto).

***

## Supported Features

We support the following features:

* [Triggering web unlock actions](/api/locks/unlock_door)
* [Programming access codes](/low-level-apis/smart-locks/access-codes) on door locks and card readers that have a PIN pad

***

### Device Provider Key

Seam identifies these devices with the `salto_ks` device provider key. By default, a [Connect Webview](/core-concepts/connect-webviews) displays all of the stable providers that Seam supports, so your users can connect their Salto devices without you specifying a provider list. To narrow what a Connect Webview displays, see [Customize the Brands to Display in Your Connect Webviews](/core-concepts/connect-webviews/customizing-connect-webviews#customize-the-brands-to-display-in-your-connect-webviews).

***

## Setup Instructions

For instructions on connecting Salto KS locks to Seam, see the [Salto KS Lock Setup Guide](./salto-ks-setup-guide).

## Brand-Specific Integration Considerations

### Access Code Limitations

Salto does not allow a user to configure custom PIN codes. When creating an access code on a Salto door lock, their system will automatically generate a 6-10 digit PIN code. You will be able to retrieve the PIN code from the `code` property on the access code object.

### Salto-Specific Access Code Errors

`salto_site_user_not_subscribed`

When you encounter this error, it means that the Salto KS site has exceeded the allowed number of users, as defined by its subscription plan. There are a few ways to resolve this:

1. You can reduce the number of access codes you've created. Each access code will take up one user slot.
2. You can ask the device owner to contact their Salto installer to increase the subscription limit on their site.

***

## Troubleshooting

### What to do with a Salto lock with an `unknown` device type?

A Salto lock displaying an `unknown` device type indicates a weak connection with the Salto IQ hub. Please contact a Salto installer for assistance.

***

## Where to Order

Get in touch with a Salto representative in your region. They can refer you to a local installer that will service your area.

<table>
  <thead>
    <tr>
      <th />

      <th />

      <th />

      <th />

      <th />
    </tr>
  </thead>

  <tbody>
    <tr>
      <td />

      <td>
        <strong>Salto Systems Sales Contact</strong>
      </td>

      <td />

      <td>
        <a href="https://saltosystems.com/en-us/offices/">
          [https://saltosystems.com/en-us/offices/](https://saltosystems.com/en-us/offices/)
        </a>
      </td>

      <td />
    </tr>
  </tbody>
</table>


# Salto KS Lock Setup Guide
Source: https://docs.seam.co/device-and-system-integration-guides/salto-locks/salto-ks-setup-guide

Connect your Salto KS locks to Seam.

## Overview

This guide walks you through connecting your Salto KS locks to Seam. Your locks must already be set up and working in the Salto KS platform before proceeding.

<Info>
  Seam supports two integrations for Salto KS. We recommend using the [Salto KS
  access control system
  integration](/device-and-system-integration-guides/salto-ks-access-control-system)
  because it provides more robust functionality, such as managing ACS users and
  credentials. However, if you want to connect a single or just a few Salto KS
  locks, you can choose the Salto KS lock integration described in this guide.
</Info>

***

## Prerequisites

Before connecting your Salto KS devices to Seam, confirm the following:

* **Site Admin rights:** You must use a Salto KS web app user account that has "Site Admin" rights.
* **Production environment:** You must use a Salto KS production environment account. You cannot use "Accept Environment" credentials. To confirm your account type, check the Salto KS dashboard URL. The subdomain must be `app` (for example, `https://app.saltoks.com`). A subdomain of `app-accept` (for example, `https://app-accept.saltoks.com`) indicates an Accept Environment that cannot connect to Seam.
* **Released sites:** Make sure that your installer has released your Salto KS sites. Seam cannot perform actions on unreleased Salto KS sites.

***

## Step 1: Confirm Your Salto KS Account

1. Create an account in the [Salto KS app](https://app.saltoks.com/) if you have not done so already.
2. In the Salto KS app, confirm that your Salto KS devices are added and online.
3. Note your login credentials for the Salto KS app.

***

## Step 2: Connect to Seam via Connect Webview

1. Open the [Connect Webview](/core-concepts/connect-webviews) provided by your application.
2. If the Connect Webview displays multiple brand options, select **Salto KS**.
3. In the **Enter your credentials** dialog, type your username and password for the Salto KS web app and then click **Log In**.
4. Select **Full Access** and then click **Yes, Allow**.
5. Select the Salto KS sites that you want to integrate with Seam and then click **Continue**.
6. Click **Allow and Continue** to confirm that you allow Seam to add the requisite admin user to your Salto KS site for the integration with Seam.

<Warning>Do not suspend or remove the Seam Integration admin user from your Salto KS site.</Warning>

***

## Step 3: Verify the Connection

After connecting, verify that your Salto KS locks appear as devices and show as online with unlock and access code capabilities.

***

## Troubleshooting

### Authorization fails in Connect Webview

Make sure you are using a Salto KS account with Site Admin rights and a production environment URL (`https://app.saltoks.com`). Accept Environment credentials (`https://app-accept.saltoks.com`) cannot connect to Seam.

### Locks not appearing after authorization

Ensure your Salto KS sites have been released by your installer. Seam cannot perform actions on unreleased sites. Also confirm that devices are online in the Salto KS app.

### `salto_site_user_not_subscribed` error

This error means the Salto KS site has exceeded the allowed number of users for its subscription plan. To resolve this:

1. Reduce the number of access codes you have created. Each access code takes up one user slot.
2. Ask the device owner to contact their Salto installer to increase the subscription limit on their site.

### Lock shows an `unknown` device type

This indicates a weak connection with the Salto IQ hub. Contact a Salto installer for assistance.


# Sandbox Salto KS Locks
Source: https://docs.seam.co/device-and-system-integration-guides/salto-locks/sandbox-salto-ks-locks

Add virtual Salto KS locks to your Seam sandbox workspace using these sample credentials to test your integration without real hardware.

Use the following set of credentials to add virtual [Salto KS locks](/device-and-system-integration-guides/salto-locks) to your Seam [sandbox workspace](/core-concepts/workspaces#sandbox-workspaces):

| Email Address                               | Password |
| ------------------------------------------- | -------- |
| [jane@example.com](mailto:jane@example.com) | 1234     |


# Salto ProAccess Space Access System
Source: https://docs.seam.co/device-and-system-integration-guides/salto-proaccess-space-access-system/index

Guide for using the Salto ProAccess Space Access System with Seam

<img alt="Salto Space logo" />

## Overview

[Salto ProAccess Space](https://saltosystems.com/en-us/solutions/salto-space/salto-space-products/proaccess-space-management-software/) provides an on-premises access system that enables property managers and owners to control access across their properties. Because it is an on-premises solution, Salto Space provides support for both online and offline access devices. You can manage user access and monitor entrances efficiently. Salto Space is a good choice for enterprises that need full local security.

The Seam integration for Salto Space enables you to create access system users and assign access permissions to them. In the Salto Space model, you assign users to access groups that grant access to specific sets of entrances. Then, you create credentials to define the access mechanisms for the users' access grants.

This integration requires [Seam Bridge](/capability-guides/seam-bridge) to connect the on-premises Salto Space access system with Seam.

***

## Salto Space Resources

The Seam access system schema consists of a series of resources that interact intuitively, enabling you to use the Seam API to manage your Salto Space access system in a logical, efficient manner. Salto Space is an [access group-based access system](/low-level-apis/access-systems/connect-an-acs-to-seam/understanding-access-control-system-differences#access-group-based-access-control-systems), so you [create access system users](/low-level-apis/access-systems/user-management#create-an-acs-user) and then assign them to access groups to specify the entrances to which these users have access.

The following diagram shows the Seam resources for a Salto Space access system and the relationships between these resources:

The following table provides a brief description of each of the Seam resources for the Salto Space access system:

<table>
  <thead>
    <tr>
      <th>Seam Resource</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        <a href="/api/acs/users/object">
          <code>acs\_user</code>
        </a>
      </td>

      <td>
        Individual who has been granted access to specific entrances within a
        property. Access system users could include employees, residents, and
        visitors. You assign a unique credential to each user.
      </td>
    </tr>

    <tr>
      <td>
        <a href="/api/acs/access_groups/object">
          <code>acs\_access\_group</code>
        </a>
      </td>

      <td>
        Collection of users with shared access permissions, called "user access
        levels" in Salto Space. Instead of assigning permissions individually,
        users are grouped based on their access needs. Access groups streamline
        the management of access rights and ensure consistency.
      </td>
    </tr>

    <tr>
      <td>
        <a href="/api/acs/entrances/object">
          <code>acs\_entrance</code>
        </a>
      </td>

      <td>
        Physical points of entry within a property that are secured with Salto
        smart access devices, called "access points" in Salto Space. Salto Space
        supports both online and offline entrances. Access permissions are
        assigned to these entrances through access groups.
      </td>
    </tr>

    <tr>
      <td>
        <a href="/api/acs/credentials/object">
          <code>acs\_credential</code>
        </a>
      </td>

      <td>
        <p>Key cards or mobile keys.</p>

        <ul>
          <li>
            Key cards: Physical cards that users can swipe or tap at access
            points. For Salto Space, you encode credentials onto cards.
          </li>

          <li>
            Mobile keys: Digital keys stored on users' mobile devices, enabling
            them to access entrances using their smartphones.
          </li>
        </ul>

        <div>
          <p>
            For each access system user, Salto Space supports a maximum of one
            key card credential and one mobile key credential.
          </p>
        </div>
      </td>
    </tr>
  </tbody>
</table>

For more information about managing your Salto Space access system through Seam, see the following topics:

* [Programming Salto Space Card-based Credentials](./programming-salto-space-card-based-credentials)
* [Programming Salto Space Mobile Credentials](./programming-salto-space-mobile-credentials)
* [Access Group-Based Access Systems](/low-level-apis/access-systems/connect-an-acs-to-seam/understanding-access-control-system-differences#access-group-based-access-control-systems)
* [Access Systems](/low-level-apis/access-systems)
* [Mobile Access](/capability-guides/mobile-access)

***

## Supported Devices

<DeviceList />

This integration supports all Salto locks connected to the Salto Space ACS.

***

## Supported Features

We support the following features:

* [Managing access systems](/low-level-apis/access-systems)
* [Issuing card-based credentials](./programming-salto-space-card-based-credentials)
* [Issuing mobile access credentials](/capability-guides/mobile-access)

***

### Device Provider Key

Seam identifies these devices with the `salto_space` device provider key. By default, a [Connect Webview](/core-concepts/connect-webviews) displays all of the stable providers that Seam supports, so your users can connect their Salto Space access system without you specifying a provider list. To narrow what a Connect Webview displays, see [Customize the Brands to Display in Your Connect Webviews](/core-concepts/connect-webviews/customizing-connect-webviews#customize-the-brands-to-display-in-your-connect-webviews).

***

## Brand-Specific Behaviors

Note the following Salto Space behaviors:

### Proximity Behavior

To use access devices successfully within a Salto Space access system, it is important to understand the following proximity behavior requirements:

#### Card Readers

Card readers within a Salto Space access system are powered. By default, near detection mode is enabled (that is, "far opening" is disabled), which means that readers can read a BLE credential from up to around 30 cm away. If you enable far opening, the range increases to around 15 meters.

To enable or disable far opening:

1. Log in to the Salto ProAccess Space desktop app.
2. In the top navigation pane, go to **System > Salto Network**.
3. Click the triangle next to the controller that hosts the reader for which you’d like to modify the proximity settings.
4. In the **Inputs** area for the controller, click the desired reader.
5. In the configuration window for the reader, enable or disable far opening.
6. Repeat this process for all additional readers for which you want to enable or disable far opening.

***

## Troubleshooting

For information about Salto Space access system-related errors, see [Troubleshooting Your Access System](/low-level-apis/access-systems/troubleshooting-your-access-control-system).

***

## Where to Order

To purchase the Salto Space access system and devices, contact Salto Space Sales.

<table>
  <thead>
    <tr>
      <th />

      <th />

      <th />

      <th />

      <th />
    </tr>
  </thead>

  <tbody>
    <tr>
      <td />

      <td>
        <strong>Salto Space Sales Contact Page</strong>
      </td>

      <td />

      <td>
        <a href="https://saltosystems.com/en-us/contact/">
          [https://saltosystems.com/en-us/contact/](https://saltosystems.com/en-us/contact/)
        </a>
      </td>

      <td>
        <a href="/images/salto-space-logo.png">salto-space-logo.png</a>
      </td>
    </tr>
  </tbody>
</table>


# Programming Salto Space Card-based Credentials
Source: https://docs.seam.co/device-and-system-integration-guides/salto-proaccess-space-access-system/programming-salto-space-card-based-credentials

Learn how to create plastic card-based credentials for Salto Space.

For each access system user in a [Salto Space access system](./), you can create a maximum of one key card credential and one [mobile key credential](./programming-salto-space-mobile-credentials). For Salto Space, you create card credentials and then encode them onto plastic key cards for users.

To use the Seam API to create card credentials for a Salto Space access system:

1. Create an [access system user](/low-level-apis/access-systems/user-management).

2. Assign access permissions to the user by assigning them to one or more [access groups](/low-level-apis/access-systems/user-management/assigning-users-to-access-groups).
   * Each access group is preconfigured with specific entrances.

3. Create a [credential](/low-level-apis/access-systems/managing-credentials).
   * Specify the ID of the access system user.
   * Set the `access_method` to `card`.
   * Choose whether to assign a new card to the user or update the user's existing card. Use the Boolean `salto_space_metadata.assign_new_key` parameter when creating the credential.

     Consider the following situations:

     * To assign a first, new card to a user, set `salto_space_metadata.assign_new_key` to `true`.
     * To replace a user's card—for example, if a user has lost their card—delete the user's previous credential and then create a new credential, setting `salto_space_metadata.assign_new_key` to `true`. Remember that a Salto Space user can only have one key card at a time.
     * To update a user's card with changed access permissions, set `salto_space_metadata.assign_new_key` to `false`. For example, this option is applicable if a user's access group assignment has changed or if the set of entrances for an access group has changed.

4. Encode the credential onto a card.

   <Info>
     Make sure that each of your Salto Space sites is equipped with a supported
     card encoder. The [NCoder card
     encoder](https://saltosystems.com/en-us/products/ncoder/) is compatible
     with the Seam integration.
   </Info>

   1. Use the `/acs/encoders/list` endpoint to retrieve a list of available
      encoders. Then, choose the encoder that you want to use to write the
      credential to the card.\ See [Retrieve
      Encoders](/low-level-apis/access-systems/working-with-card-encoders-and-scanners/creating-and-encoding-card-based-credentials#2-retrieve-encoders).
   2. Use the `/acs/encoders/encode_credential` endpoint to encode the
      credential onto the card, using the encoder that you have chosen.\ See
      [Encode the
      Card](/low-level-apis/access-systems/working-with-card-encoders-and-scanners/creating-and-encoding-card-based-credentials#3-encode-the-card).
   3. Confirm that the card was encoded successfully using polling or a
      [webhook](/developer-tools/webhooks).\ See
      [Confirm Successful
      Encoding](/low-level-apis/access-systems/working-with-card-encoders-and-scanners/creating-and-encoding-card-based-credentials#4-confirm-successful-encoding).
      Also, see a list of [common encoding
      errors](/low-level-apis/access-systems/working-with-card-encoders-and-scanners/creating-and-encoding-card-based-credentials#common-encoding-errors).

The following example walks you through this process:

**Code:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  // Get the access system.
  const buildingA = await seam.acs.systems.get({
    acs_system_id: '11111111-1111-1111-1111-111111111111',
  })

  // Step 1:
  // Create the new access system user.
  const janeUser = await seam.acs.users.create({
    full_name: 'Jane Doe',
    phone_number: '+15555550100',
    acs_system_id: buildingA.acs_system_id,
  })

  // Step 2:
  // Add the access system user to all desired access groups.
  const accessGroupIds = [
    '44444444-4444-4444-4444-333333333333',
    '44444444-4444-4444-4444-444444444444',
  ]
  for (const accessGroupId of accessGroupIds) {
    await seam.acs.users.addToAccessGroup({
      acs_user_id: janeUser.acs_user_id,
      acs_access_group_id: accessGroupId,
    })
  }

  // Step 3:
  // Create a card credential for the access system user.
  const cardCredential = await seam.acs.credentials.create({
    acs_user_id: janeUser.acs_user_id,
    access_method: 'card',
    salto_space_metadata: {
      // This example assigns a new card to the user.
      // To update an existing card, set assign_new_card to false.
      assign_new_card: true,
    },
  })

  // Step 4:
  // Encode the credential onto a card.
  // First, get the encoder that you want to use.
  const encoder = (
    await seam.acs.encoders.list({
      acs_system_ids: [building_a.acs_system_id],
    })
  )[0]

  // Then, encode the card.
  const encodingActionAttempt = await seam.acs.encoders.encodeCredential({
    acs_credential_id: cardCredential.acs_credential_id,
    acs_encoder_id: encoder.acs_encoder_id,
  })

  // To confirm that the encoding succeeded,
  // poll the returned action attempt
  // until its status is success.
  await seam.actionAttempts.get({
    action_attempt_id: encodingActionAttempt.action_attempt_id,
  })
  ```

  ```bash cURL theme={null}
  # Get the access system.
  building_a=$(curl -X 'POST' \
    'https://connect.getseam.com/acs/systems/get' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d "{
    \"acs_system_id\": \"11111111-1111-1111-1111-111111111111\"
  }")

  # Step 1:
  # Create the new access system user.
  jane_user=$(curl -X 'POST' \
    'https://connect.getseam.com/acs/users/create' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d "{
    \"full_name\": \"Jane Doe\",
    \"phone_number\": \"+15555550100\",
    \"acs_system_id\": \"$(jq -r '.acs_system.acs_system_id' <<< ${building_a})\"
  }")

  # Step 2:
  # Add the access system user to all desired access groups.
  declare -a access_group_ids=("44444444-4444-4444-4444-333333333333" "44444444-4444-4444-4444-444444444444")
  for access_group_id in ${access_group_ids[@]};
  do
    curl -X 'POST' \
      'https://connect.getseam.com/acs/users/add_to_access_group' \
      -H 'accept: application/json' \
      -H "Authorization: Bearer ${SEAM_API_KEY}" \
      -H 'Content-Type: application/json' \
      -d "{
      \"acs_user_id\": \"$(jq -r '.acs_user.acs_user_id' <<< ${jane_user})\",
      \"acs_access_group_id\": \"$access_group_id\"
    }";
  done

  # Step 3:
  # Create a card credential for the access system user.
  # This example assigns a new card to the user.
  # To update an existing card, set assign_new_card to false.
  card_credential=$(curl -X 'POST' \
    'https://connect.getseam.com/acs/credentials/create' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d "{
    \"acs_user_id\": \"$(jq -r '.acs_user.acs_user_id' <<< ${jane_user})\",
    \"access_method\": \"card\",
    \"salto_space_metadata\": {
      \"assign_new_card\": true
    }
  }")

  # Step 4:
  # Encode the credential onto a card.
  # First, get the encoder that you want to use.
  encoder=$(curl -X 'POST' \
    'https://connect.getseam.com/acs/encoders/list' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d "{
    \"acs_system_id\": \"$(jq -r '.acs_system.acs_system_id' <<< ${building_a})\"
  }" | jq -r '.acs_encoders[0]')

  # Then, encode the card.
  encoding_action_attempt=$(curl -X 'POST' \
    'https://connect.getseam.com/acs/encoders/encode_credential' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d "{
    \"acs_credential_id\": \"$(jq -r '.acs_credential.acs_credential_id' <<< ${card_credential})\",
    \"acs_encoder_id\": \"$(jq -r '.acs_encoder_id' <<< ${encoder})\"
  }")

  # To confirm that the encoding succeeded,
  # poll the returned action attempt
  # until its status is success.
  curl -X 'POST' \
    'https://connect.getseam.com/action_attempts/get' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d "{
    \"action_attempt_id\": \"$(jq -r '.action_attempt.action_attempt_id' <<< ${encoding_action_attempt})\"
  }"
  ```

  ```python Python theme={null}
  # Get the access system.
  building_a = seam.acs.systems.get(
    acs_system_id="11111111-1111-1111-1111-111111111111"
  )

  # Step 1:
  # Create the new access system user.
  jane_user = seam.acs.users.create(
    full_name = "Jane Doe",
    phone_number = "+15555550100",
    acs_system_id = building_a.acs_system_id
  )

  # Step 2:
  # Add the access system user to all desired access groups.
  access_group_ids = [
    "44444444-4444-4444-4444-333333333333",
    "44444444-4444-4444-4444-444444444444"
  ]
  for access_group_id in access_group_ids:
    seam.acs.users.add_to_access_group(
      acs_user_id = jane_user.acs_user_id,
      acs_access_group_id = access_group_id
    )

  # Step 3:
  # Create a card credential for the access system user.
  card_credential = seam.acs.credentials.create(
    acs_user_id = jane_user.acs_user_id,
    access_method = "card",
    salto_space_metadata = {
      # This example assigns a new card to the user.
      # To update an existing card, set assign_new_card to False.
      "assign_new_card": True
    }
  )

  # Step 4:
  # Encode the credential onto a card.
  # First, get the encoder that you want to use.
  encoder = seam.acs.encoders.list(
    acs_system_ids = [building_a.acs_system_id]
  )[0]

  # Then, encode the card.
  encoding_action_attempt = seam.acs.encoders.encode_credential(
    acs_credential_id = card_credential.acs_credential_id,
    acs_encoder_id = encoder.acs_encoder_id
  )

  # To confirm that the encoding succeeded,
  # poll the returned action attempt
  # until its status is success.
  seam.action_attempts.get(
    action_attempt_id = encoding_action_attempt.action_attempt_id
  )
  ```

  ```ruby Ruby theme={null}
  # Get the access system.
  building_a = seam.acs.systems.get(
    acs_system_id: "11111111-1111-1111-1111-111111111111"
  )

  # Step 1:
  # Create the new access system user.
  jane_user = seam.acs.users.create(
    full_name: "Jane Doe",
    phone_number: "+15555550100",
    acs_system_id: building_a.acs_system_id
  )

  # Step 2:
  # Add the access system user to all desired access groups.
  access_group_ids = [
    "44444444-4444-4444-4444-333333333333",
    "44444444-4444-4444-4444-444444444444"
  ]
  access_group_ids.each do |access_group_id|
    seam.acs.users.add_to_access_group(
      acs_user_id: jane_user.acs_user_id,
      acs_access_group_id: access_group_id
    )
  end

  # Step 3:
  # Create a card credential for the access system user.
  card_credential = seam.acs.credentials.create(
    acs_user_id: jane_user.acs_user_id,
    access_method: "card",
    salto_space_metadata: {
      # This example assigns a new card to the user.
      # To update an existing card, set assign_new_card to false.
      "assign_new_card": true
    }
  )

  # Step 4:
  # Encode the credential onto a card.
  # First, get the encoder that you want to use.
  encoder = (seam.acs.encoders.list(
    acs_system_ids: [building_a.acs_system_id]
  ))[0]

  # Then, encode the card.
  encoding_action_attempt = seam.acs.encoders.encode_credential(
    acs_credential_id: card_credential.acs_credential_id,
    acs_encoder_id: encoder.acs_encoder_id
  )

  # To confirm that the encoding succeeded,
  # poll the returned action attempt
  # until its status is success.
  seam.action_attempts.get(
    action_attempt_id: encoding_action_attempt.action_attempt_id
  )
  ```

  ```php PHP theme={null}
  // Get the access system.
  $building_a = $seam->acs->systems->get(
    acs_system_id: "11111111-1111-1111-1111-111111111111"
  );

  // Step 1:
  // Create the new access system user.
  $jane_user = $seam->acs->users->create(
    full_name: "Jane Doe",
    phone_number: "+15555550100",
    acs_system_id: $building_a->acs_system_id
  );

  // Step 2:
  // Add the access system user to all desired access groups.
  $access_group_ids = array(
    "44444444-4444-4444-4444-333333333333",
    "44444444-4444-4444-4444-444444444444"
  );
  foreach ($access_group_ids as $access_group_id) {
    $seam->acs->users->add_to_access_group(
      acs_user_id: $jane_user->acs_user_id,
      acs_access_group_id: $access_group_id
    );
  };

  // Step 3:
  // Create a card credential for the access system user.
  $card_credential = $seam->acs->credentials->create(
    acs_user_id: $jane_user->acs_user_id,
    access_method: "card",
    salto_space_metadata: {
      // This example assigns a new card to the user.
      // To update an existing card, set assign_new_card to false.
      "assign_new_card": true
    }
  );

  // Step 4:
  // Encode the credential onto a card.
  // First, get the encoder that you want to use.
  $encoder = $seam->acs->encoders->list(
    acs_system_ids: [$building_a->acs_system_id]
  )[0];

  // Then, encode the card.
  $encoding_action_attempt = $seam->acs->encoders->encode_credential(
    acs_credential_id: $card_credential->acs_credential_id,
    acs_encoder_id: $encoder->acs_encoder_id
  );

  // To confirm that the encoding succeeded,
  // poll the returned action attempt
  // until its status is success.
  $seam->action_attempts->get(
    action_attempt_id: $encoding_action_attempt->action_attempt_id
  );
  ```

  ```csharp C# theme={null}
  // Coming soon!
  ```
</CodeGroup>

**Output:**

<CodeGroup>
  ```json JavaScript theme={null}
  {
    acs_credential_id: '66666666-6666-6666-6666-666666666666',
    acs_user_id: '33333333-3333-3333-3333-333333333333',
    access_method: 'card',
    is_issued: false,
    ...
  }

  {
    status: 'success',
    action_attempt_id: '11111111-2222-3333-4444-555555555555",
    action_type: 'ENCODE_CREDENTIAL',
    result: {
      acs_credential_id: "66666666-6666-6666-6666-666666666666',
      card_number: '1234abc',
      is_issued: true,
      issued_at: '2025-03-01T19:46:06.113Z',
      ...
    },
    error: null
  }
  ```

  ```json cURL theme={null}
  {
    "acs_credential":{
      "acs_credential_id": "66666666-6666-6666-6666-666666666666",
      "acs_user_id": "33333333-3333-3333-3333-333333333333",
      "access_method": "card",
      "is_issued": false,
      ...
    }
  }

  {
    "action_attempt":
      {
        "status": "success",
        "action_attempt_id": "11111111-2222-3333-4444-555555555555",
        "action_type": "ENCODE_CREDENTIAL",
        "result": {
          "acs_credential_id": "66666666-6666-6666-6666-666666666666",
          "card_number": "1234abc",
          "is_issued": true,
          "issued_at": "2025-03-01T19:46:06.113Z",
          ...
        },
        "error": null
      },
    "ok": true
  }
  ```

  ```json Python theme={null}
  AcsCredential(
    acs_credential_id='66666666-6666-6666-6666-666666666666',
    acs_user_id='33333333-3333-3333-3333-333333333333',
    access_method='card',
    is_issued=False,
    ...
  )

  ActionAttempt(
    status='success',
    action_attempt_id='11111111-2222-3333-4444-555555555555',
    action_type='ENCODE_CREDENTIAL',
    result={
      acs_credential_id='66666666-6666-6666-6666-666666666666',
      card_number='1234abc',
      is_issued=True,
      issued_at='2025-03-01T19:46:06.113Z',
      ...
    },
    error=null
  )
  ```

  ```json Ruby theme={null}
  <Seam::Resources::AcsCredential:0x00410
    acs_credential_id="66666666-6666-6666-6666-666666666666"
    acs_user_id="33333333-3333-3333-3333-333333333333"
    access_method="card"
    is_issued=false
    ...
  >

  <Seam::Resources::ActionAttempt:0x00410
    status="success"
    action_attempt_id="11111111-2222-3333-4444-555555555555"
    action_type="ENCODE_CREDENTIAL"
    result={
      acs_credential_id="66666666-6666-6666-6666-666666666666"
      card_number="1234abc"
      is_issued=true,
      issued_at="2025-03-01T19:46:06.113Z"
      ...
    }
    error=nil
  >
  ```

  ```json PHP theme={null}
  {
    "acs_credential_id": "66666666-6666-6666-6666-666666666666",
    "acs_user_id": "33333333-3333-3333-3333-333333333333",
    "access_method": "card",
    "is_issued": false,
    ...
  }

  {
    "status": "success",
    "action_attempt_id": "11111111-2222-3333-4444-555555555555",
    "action_type": "ENCODE_CREDENTIAL",
    "result": {
      "acs_credential_id": "66666666-6666-6666-6666-666666666666",
      "card_number": "1234abc",
      "is_issued": true,
      "issued_at": "2025-03-01T19:46:06.113Z",
      ...
    },
    "error": null
  }
  ```

  ```json C# theme={null}
  // Coming soon!
  ```
</CodeGroup>

***

## Next Steps

You can use an encoder to scan a plastic key card to read its encoded parameters. The scan result includes the card's properties, such as its card number, serial number, and other useful details. For more information, see [Scanning Encoded Cards](/low-level-apis/access-systems/working-with-card-encoders-and-scanners/scanning-encoded-cards).

***

## Learn More

To find out more about using the Seam API with your Salto Space access system, see the following topics:

* [Access Systems](/low-level-apis/access-systems)
* [Access Group-Based Access Systems](/low-level-apis/access-systems/connect-an-acs-to-seam/understanding-access-control-system-differences#access-group-based-access-control-systems)
* [Managing Access System Users](/low-level-apis/access-systems/user-management)
* [Managing Credentials](/low-level-apis/access-systems/managing-credentials)
* [Working with Card Encoders and Scanners](/low-level-apis/access-systems/working-with-card-encoders-and-scanners)
* [Access Systems](/api/acs/object) in the Seam API reference


# Programming Salto Space Mobile Credentials
Source: https://docs.seam.co/device-and-system-integration-guides/salto-proaccess-space-access-system/programming-salto-space-mobile-credentials

Learn how to create mobile credentials in the Salto Space access system.

You can create mobile credentials that enable your mobile app users to unlock entrances in your [Salto Space access system](./). For each Salto Space user, you can create a maximum of one [key card credential](./programming-salto-space-card-based-credentials) and one mobile key credential. For more information about Seam mobile keys, see [Mobile Access](/capability-guides/mobile-access).

To use the Seam API to create mobile credentials for mobile app users in a Salto Space access system:

1. Create a [user identity](/api/user_identities/object).

   Seam user identities enable you to match your own mobile app users to access system users that you create using the Seam API.

2. Create an [access system user](/low-level-apis/access-systems/user-management) on the Salto Space access system or assign an existing access system user to the user identity.\
   The resources that you create for the access system user are available under the associated user identity.

3. Assign the access system user to one or more [access groups](/low-level-apis/access-systems/user-management/assigning-users-to-access-groups).
   * Each access group is preconfigured with the allowed entrances.

4. Create a [credential](/low-level-apis/access-systems/managing-credentials) to represent the mobile key.
   * Specify the ID of the access system user.
   * Set [`is_multi_phone_sync_credential`](/capability-guides/mobile-access/issuing-mobile-credentials-from-an-access-control-system#what-are-multi-phone-sync-credentials) to `true`.
   * Set the `access_method` to `mobile_key`.

The following example walks you through this process:

**Code:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  // Get the access system.
  const buildingA = await seam.acs.systems.get({
    acs_system_id: '11111111-1111-1111-1111-111111111111',
  })

  // Step 1:
  // Create a user identity that corresponds to your user's app account.
  const janeUser = await seam.userIdentities.create({
    full_name: 'Jane Doe',
  })

  // Step 2:
  // Create an access system user on the Salto Space access system.
  const accessSystemUser = await seam.acs.users.create({
    user_identity_id: janeUser.user_identity_id,
    acs_system_id: buildingA.acs_system_id,
    full_name: janeUser.full_name,
    phone_number: '+15555550100',
  })

  // Step 3:
  // Add the access system user to all desired access groups.
  const accessGroupIds = [
    '44444444-4444-4444-4444-333333333333',
    '44444444-4444-4444-4444-444444444444',
  ]
  for (const accessGroupId of accessGroupIds) {
    await seam.acs.users.addToAccessGroup({
      acs_user_id: accessSystemUser.acs_user_id,
      acs_access_group_id: accessGroupId,
    })
  }

  // Step 4:
  // Create a mobile key for the access system user.
  const mobileKey = await seam.acs.credentials.create({
    acs_user_id: accessSystemUser.acs_user_id,
    access_method: 'mobile_key',
    is_multi_phone_sync_credential: true,
  })
  ```

  ```bash cURL theme={null}
  # Get the access system.
  building_a=$(curl -X 'POST' \
    'https://connect.getseam.com/acs/systems/get' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d "{
    \"acs_system_id\": \"11111111-1111-1111-1111-111111111111\"
  }")

  # Step 1:
  # Create a user identity that corresponds to your user's app account.
  jane_user=$(curl -X 'POST' \
    'https://connect.getseam.com/user_identities/create' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d '{
    "full_name": "Jane Doe"
  }')

  # Step 2:
  # Create an access system user on the Salto Space access system.
  access_system_user=$(curl -X 'POST' \
    'https://connect.getseam.com/acs/users/create' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d "{
    \"user_identity_id\": \"$(jq -r '.user_identity.user_identity_id' <<< ${jane_user})\",
    \"acs_system_id\": \"$(jq -r '.acs_system.acs_system_id' <<< ${building_a})\",
    \"full_name\": \"$(jq -r '.user_identity.full_name' <<< ${jane_user})\",
    \"phone_number\": \"+15555550100\"
  }")

  # Step 3:
  # Add the access system user to all desired access groups.
  declare -a access_group_ids=("44444444-4444-4444-4444-333333333333" "44444444-4444-4444-4444-444444444444")
  for access_group_id in ${access_group_ids[@]};
  do
    curl -X 'POST' \
      'https://connect.getseam.com/acs/users/add_to_access_group' \
      -H 'accept: application/json' \
      -H "Authorization: Bearer ${SEAM_API_KEY}" \
      -H 'Content-Type: application/json' \
      -d "{
      \"acs_user_id\": \"$(jq -r '.acs_user.acs_user_id' <<< ${access_system_user})\",
      \"acs_access_group_id\": \"$access_group_id\"
    }";
  done

  # Step 4:
  # Create a mobile key for the access system user.
  mobile_key=$(curl -X 'POST' \
    'https://connect.getseam.com/acs/credentials/create' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d "{
    \"acs_user_id\": \"$(jq -r '.acs_user.acs_user_id' <<< ${access_system_user})\",
    \"is_multi_phone_sync_credential\": true,
    \"access_method\": \"mobile_key\"
  }")
  ```

  ```python Python theme={null}
  # Get the access system.
  building_a = seam.acs.systems.get(
    acs_system_id = "11111111-1111-1111-1111-111111111111"
  )

  # Step 1:
  # Create a user identity that corresponds to your user's mobile app account.
  jane_user = seam.user_identities.create(
    full_name = "Jane Doe"
  )

  # Step 2:
  # Create an access system user on the Salto Space access system.
  access_system_user = seam.acs.users.create(
    user_identity_id = jane_user.user_identity_id,
    acs_system_id = building_a.acs_system_id,
    full_name = jane_user.full_name,
    phone_number = "+15555550100"
  )

  # Step 3:
  # Add the access system user to all desired access groups.
  access_group_ids = [
    "44444444-4444-4444-4444-333333333333",
    "44444444-4444-4444-4444-444444444444"
  ]
  for access_group_id in seam_access_group_ids:
    seam.acs.users.add_to_access_group(
      acs_user_id = access_system_user.acs_user_id,
      acs_access_group_id = access_group_id
    )

  # Step 4:
  # Create a mobile key for the access system user.
  mobile_key = seam.acs.credentials.create(
    acs_user_id = access_system_user.acs_user_id,
    is_multi_phone_sync_credential = True,
    access_method = "mobile_key"
  )
  ```

  ```ruby Ruby theme={null}
  # Get the access system.
  building_a = seam.acs.systems.get(
    acs_system_id: "11111111-1111-1111-1111-111111111111"
  )

  # Step 1:
  # Create a user identity that corresponds to your user's app account.
  jane_user = seam.user_identities.create(
    full_name: "Jane Doe"
  )

  # Step 2:
  # Create an access system user on the Salto Space access system.
  access_system_user = seam.acs.users.create(
    user_identity_id: jane_user.user_identity_id,
    acs_system_id: building_a.acs_system_id,
    full_name: jane_user.full_name,
    phone_number: "+15555550100"
  )

  # Step 3:
  # Add the access system user to all desired access groups.
  access_group_ids = [
    "44444444-4444-4444-4444-333333333333",
    "44444444-4444-4444-4444-444444444444"
  ]
  access_group_ids.each do |access_group_id|
    seam.acs.users.add_to_access_group(
      acs_user_id: access_system_user.acs_user_id,
      acs_access_group_id: access_group_id
    )
  end

  # Step 4:
  # Create a mobile key for the access system user.
  mobile_key = seam.acs.credentials.create(
    acs_user_id: access_system_user.acs_user_id,
    access_method: "mobile_key",
    is_multi_phone_sync_credential: true
  )
  ```

  ```php PHP theme={null}
  // Get the access system.
  $building_a = $seam->acs->systems->get(
    acs_system_id: "11111111-1111-1111-1111-111111111111"
  );

  // Step 1:
  // Create a user identity that corresponds to your user's app account.
  $jane_user = $seam->user_identities->create(
    full_name: "Jane Doe"
  );

  // Step 2:
  // Create an access system user on the Salto Space access system.
  $access_system_user = $seam->acs->users->create(
    user_identity_id: $jane_user->user_identity_id,
    acs_system_id: $building_a->acs_system_id,
    full_name: $jane_user->full_name,
    phone_number: "+15555550100"
  );

  // Step 3:
  // Add the access system user to all desired access groups.
  $access_group_ids = array(
    "44444444-4444-4444-4444-333333333333",
    "44444444-4444-4444-4444-444444444444"
  );
  foreach ($access_group_ids as $access_group_id) {
    $seam->acs->users->add_to_access_group(
      acs_user_id: $access_system_user->acs_user_id,
      acs_access_group_id: $access_group_id
    );
  };

  // Step 4:
  // Create a mobile key for the access system user.
  $mobile_key = $seam->acs->credentials->create(
    acs_user_id: $access_system_user->acs_user_id,
    is_multi_phone_sync_credential: true,
    access_method: "mobile_key"
  );
  ```

  ```csharp C# theme={null}
  // Coming soon!
  ```
</CodeGroup>

**Output:**

<CodeGroup>
  ```json JavaScript theme={null}
  {
    acs_credential_id: '66666666-6666-6666-6666-666666666666',
    acs_user_id: '33333333-3333-3333-3333-333333333333',
    access_method: 'mobile_key',
    ...
  }
  ```

  ```json cURL theme={null}
  {
    "acs_credential":{
      "acs_credential_id": "66666666-6666-6666-6666-666666666666",
      "acs_user_id": "33333333-3333-3333-3333-333333333333",
      "access_method": "mobile_key",
      ...
    }
  }
  ```

  ```json Python theme={null}
  AcsCredential(
    acs_credential_id='66666666-6666-6666-6666-666666666666',
    acs_user_id='33333333-3333-3333-3333-333333333333',
    access_method='mobile_key',
    ...
  )
  ```

  ```json Ruby theme={null}
  <Seam::Resources::AcsCredential:0x00618
    acs_credential_id="66666666-6666-6666-6666-666666666666"
    acs_user_id="33333333-3333-3333-3333-333333333333"
    access_method="mobile_key"
    ...
  >
  ```

  ```json PHP theme={null}
  {
    "acs_credential_id": "66666666-6666-6666-6666-666666666666",
    "acs_user_id": "33333333-3333-3333-3333-333333333333",
    "access_method": "mobile_key",
    ...
  }
  ```

  ```json C# theme={null}
  // Coming soon!
  ```
</CodeGroup>

***

## Learn More

To find out more about using the Seam API with your Salto Space access system, see the following topics:

* [Programming Salto Space Card-based Credentials](./programming-salto-space-card-based-credentials)
* [Access Systems](/low-level-apis/access-systems)
* [Access Group-Based Access Systems](/low-level-apis/access-systems/connect-an-acs-to-seam/understanding-access-control-system-differences#access-group-based-access-control-systems)
* [Managing Access System Users](/low-level-apis/access-systems/user-management)
* [Managing Credentials](/low-level-apis/access-systems/managing-credentials)
* [Mobile Access](/capability-guides/mobile-access)
* [Access Systems](/api/acs/object) in the Seam API reference
* [User Identities](/api/user_identities/object) in the Seam API reference


# Salto Space Setup Instructions
Source: https://docs.seam.co/device-and-system-integration-guides/salto-proaccess-space-access-system/salto-space-setup-instructions

Learn how to connect your Salto Space access system to Seam.

This topic describes how to connect your Salto Space sites to Seam.

## Prerequisites

This section describes the steps that you must take before connecting your Salto Space sites to Seam.

### Integrate with Live Salto Space Sites

These setup instructions assume that you are integrating existing, live Salto Space sites with Seam.

***

### SHIP Settings for Seam Integration

Before connecting your Salto Space access system to Seam, you must first configure the SHIP settings in the Salto ProAccess Space Management Software. In these settings, choose which transport protocol you want to use to connect your Salto Space site to Seam. The Seam integration for Salto Space supports both HTTP(S) and Salto Transport Protocol (STP).

If you want to use HTTP(S), also specify the username and password that you want to use for the connection to Seam.

Perform the following process for each Salto Space site that you want to integrate with Seam:

1. Log in to the Salto ProAccess Space desktop app.
2. In the top navigation pane, go to **System > General options**.
3. On the **General options** page, click the **SHIP** tab.
4. In the **Salto SHIP Server** pane:
   1. Select **Enable**.
   2. In the **Transport Protocol** area, select **HTTP(S)** or **STP**.
   3. If you've selected **HTTP(S)**:
      1. In the **Authentication** field, select **Basic**.
      2. In the **Username** field, type a username for the integration with Seam, for example, `Seam_Integration`.
      3. In the **Password** field, type a password for this Seam integration user.
   4. If you've selected **STP**:
      1. In the **TCP/IP port** field, select or type the number of the port that you want to use.
5. In the lower-right corner of the **General options** page, click **Save**.
6. Note the username and password or TCP/IP port that you have specified in the SHIP settings. You must use this information to connect your Salto Space site to Seam.

***

### LAN URL and Host of the Salto Space Server

During the process of connecting your Salto Space access system to Seam, you must specify the host IP address or LAN URL of your Salto Space server, depending on the transport protocol that you want to use to connect your Salto Space site to Seam.

To identify this URL:

1. On the Windows computer that is running the Salto Space server, open a **Command Prompt** window.

   That is, click **Start**, type `cmd`, and press **Enter**.

2. In the **Command Prompt** window, type `ipconfig` and then press **Enter**.

   This command displays the computer's Windows IP configuration.

3. Note the IPv4 address that the computer is using to connect to the internet.

   This IP address identifies the host of the Salto Space server. It most likely starts with `192`.

4. Prepend `http://` and append the port number `8100` to the IP address to form the LAN URL.

   For example, if the computer's IP address is `192.168.1.101`, the LAN URL is `http://192.168.1.101:8100`.

5. If you want to use HTTP(S) when connecting your Salto Space access system to Seam, note the LAN URL. If you want to use Salto Transport Protocol (STP) when connecting your Salto Space access system to Seam, note the IP address that identifies the host of the Salto Space server.

***

## Setup Process

Perform the following process for each Salto Space site that you want to integrate with Seam:

1. In the top navigation pane of [Seam Console](https://console.seam.co/), click **ACS Systems**.

2. On the **Access Systems** page, click **New Access System**.

   Seam Console displays a Connect Webview that enables you to connect your access system to Seam.

3. In the Connect Webview, click **Continue**.

4. If the Connect Webview displays multiple brand options, click **Salto Space**.

5. On the **Set up your Seam Bridge** page, click [**latest Seam Bridge**](https://www.seam.co/seam-bridge/releases/latest).

   [Seam Bridge](/capability-guides/seam-bridge) is a software-only component that enables you to connect on-premises software systems to the Seam platform. Because Salto Space is an on-premises access system, Seam Bridge is required for Salto Space systems.

6. Download the Seam Bridge executable onto the on-premises computer that is running Salto Space or onto a computer on the same network.

   For systems requirements, see [Seam Bridge](/capability-guides/seam-bridge).

7. Run the downloaded Seam Bridge app.

8. In the **Welcome to Seam Bridge** window, type a name for the site that you are connecting using Seam Bridge and then click **Start pairing**.

9. Copy the pairing code.

10. In the Connect Webview, click **Continue**.

11. On the **Seam Bridge Connection** page:
    1. In the **Enter your pairing token** field, paste the pairing code that you copied.
    2. Click **Submit**.

12. On the **Enter your system details** page:
    1. In the **System Name** field, type a name to identify the Salto Space site within your Seam workspace.
    2. In the **Transport Type used by the Salto Space Server** field, select **HTTP** or **STP (Salto Transport Protocol)**.
    3. Click **Submit**.

13. On the **Enter your credentials** page:
    1. If you have chosen to use HTTP(S):
       1. In the **LAN URL of the Salto Space server** field, type the [LAN URL that you identified for the Salto Space server](#lan-url-and-host-of-the-salto-space-server) before beginning this process.

          For example: `http://192.168.1.101:8100`

       2. In the **Username** field, type the username that you configured in the [Salto Space SHIP settings](#prerequisites).

       3. In the **Password** field, type the password that you configured in the Salto Space SHIP settings.

    2. If you have chosen to use STP:
       1. In the **Host of the Salto Space server** field, type the [IP address that you identified for the Salto Space server](#lan-url-and-host-of-the-salto-space-server) before beginning this process.

          For example: `192.168.1.101`

       2. In the **TCP/IP Port configured in the Salto Space server** field, type the TCP/IP port number that you configured in the [Salto Space SHIP settings](#prerequisites).

    3. Click **Submit**.

14. Click **Close**.


# Sandbox Salto Space Access System
Source: https://docs.seam.co/device-and-system-integration-guides/salto-proaccess-space-access-system/sandbox-salto-space-access-control-system

Add a virtual Salto Space access system to your Seam sandbox workspace using these Seam Bridge and connection credentials to test your integration.

Use the following set of credentials to add the virtual Salto Space access system to your Seam [sandbox workspace](/core-concepts/workspaces#sandbox-workspaces):

## Sandbox Seam Bridge Connection Credentials

| Pairing Token                        | Bridge Name                       |
| ------------------------------------ | --------------------------------- |
| 123456 (or any six-character string) | My Network (or any unique string) |

## Salto Space Connection Credentials

### HTTP

<table>
  <thead>
    <tr>
      <th>System Name</th>
      <th>Transport Type used by the Salto Space Server</th>
      <th>LAN URL of the Salto Space server</th>
      <th>Username</th>
      <th>Password</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        Any string to identify this Salto Space site, for example, My Salto
        Space Site
      </td>

      <td>HTTP</td>
      <td>[http://192.168.1.101:8100](http://192.168.1.101:8100)</td>
      <td>jane</td>
      <td>1234</td>
    </tr>
  </tbody>
</table>

### Salto Transport Protocol (STP)

| System Name                                                                    | Transport Type used by the Salto Space Server | Host of the Salto Space server                 | TCP/IP Port configured in the Salto Space server |
| ------------------------------------------------------------------------------ | --------------------------------------------- | ---------------------------------------------- | ------------------------------------------------ |
| Any string to identify this Salto Space site, for example, My Salto Space Site | STP (Salto Transport Protocol)                | Any IPv4 addresses, for example, 192.168.1.101 | Any port number, for example, 8100               |


# Get started with Schlage Locks
Source: https://docs.seam.co/device-and-system-integration-guides/schlage-locks/get-started-with-schlage-locks

Learn how to connect and control your Schlage lock with the Seam API.

## Overview

Seam provides a universal API to connect and control many brands of smart locks. This guide provides a rapid introduction to connecting and controlling your [Schlage](https://www.seam.co/manufacturers/schlage) lock using the Seam API. Note that this guide is intended for Schlage Sense locks and Schlage Encode locks that connect to wifi. For Z-Wave Schlage locks such as Schlage Connect, head over to [our guide for SmartThings](../smartthings-hubs-+-devices/get-started-with-smartthings-hubs-+-smart-locks).

To learn more about other smart lock brands supported by Seam such as August, Yale, and Salto, head over to our [integration page](https://www.seam.co/supported-devices-and-systems).

## 1 — Install Seam SDK

Seam provides client libraries for many languages, such as JavaScript, Python, Ruby, PHP, and others, as well as a Postman collection and [OpenAPI](https://connect.getseam.com/openapi.json) spec.

* JavaScript / TypeScript ([npm](https://www.npmjs.com/package/seam), [GitHub](https://github.com/seamapi/javascript))
* Python ([pip](https://pypi.org/project/seam/), [GitHub](https://github.com/seamapi/python))
* Ruby Gem ([rubygem](https://rubygems.org/gems/seam), [GitHub](https://github.com/seamapi/ruby))
* PHP ([packagist](https://packagist.org/packages/seamapi/seam), [GitHub](https://github.com/seamapi/php))
* C# ([nuget](https://www.nuget.org/packages/Seam), [GitHub](https://github.com/seamapi/csharp))

<Tabs>
  <Tab title="JavaScript">
    ```bash theme={null}
    npm i seam
    ```
  </Tab>

  <Tab title="Python">
    ```bash theme={null}
    pip install seam
    # For some development environments, use pip3 in this command instead of pip.
    ```
  </Tab>

  <Tab title="Ruby">
    ```bash theme={null}
    bundle add seam
    ```
  </Tab>

  <Tab title="PHP">
    ```bash theme={null}
    composer require seamapi/seam
    ```
  </Tab>

  <Tab title="C#">
    Install using [nuget](https://www.nuget.org/packages/Seam).
  </Tab>
</Tabs>

Once installed, [sign-up for Seam](https://console.seam.co/) to get your API key, and export it as an environment variable:

```
$ export SEAM_API_KEY=seam_test2ZTo_0mEYQW2TvNDCxG5Atpj85Ffw
```

<Info>
  This guide uses a Sandbox Workspace. Only virtual devices can be connected. If
  you need to connect a real Schlage Lock, use a non-sandbox workspace and API
  key.
</Info>

## 2 — Link Schlage Account with Seam

To control your Schlage lock via the Seam API, you must first authorize your Seam workspace against your Schlage account. To do so, Seam provides[ Connect Webviews](/core-concepts/connect-webviews): pre-built UX flows that walk you through authorizing your application to control your Schlage lock.

#### Request a Connect Webview

<CodeGroup>
  ```javascript JavaScript theme={null}
  import { Seam } from 'seam'

  const seam = new Seam()

  const { connect_webview: connectWebview } = await seam.connectWebviews.create()

  console.log(connectWebview.login_successful) // false

  // Send the webview URL to your user
  console.log(connectWebview.url)

  ```

  ```python Python theme={null}
  from seam import Seam

  seam = Seam()

  webview = seam.connect_webviews.create()

  assert webview.login_successful is False

  # Send the webview URL to your user
  print(webview.url)
  ```

  ```ruby Ruby theme={null}
  require "seam"

  seam = Seam.new(api_key: "MY_API_KEY")

  webview = seam.connect_webviews.create()

  puts webview.login_successful # false

  # Send the webview URL to your user

  puts webview.url

  ```
</CodeGroup>

#### Authorize Your Workspace

Navigate to the URL returned by the Webview object. Since you are using a sandbox workspace, complete the login flow by entering the Schlage [sandbox test accounts ](./schlage-encode-sample-data)credentials below:

* **email:** [jane@example.com](mailto:jane@example.com)
* **password:** 1234
* **2-factor-auth:** 123456

Confirm the Connect Webview was successful by querying its status:

<CodeGroup>
  ```javascript JavaScript theme={null}
  const updatedWebview = await seam.connectWebviews.get(
    connectWebview.connect_webview_id,
  )

  console.log(updatedWebview.login_successful) // true
  ```

  ```python Python theme={null}
  updated_webview = seam.connect_webviews.get(connect_webview_id: webview.connect_webview_id)

  assert updated_webview.login_successful # true

  ```

  ```ruby Ruby theme={null}
  updated_webview = seam.connect_webviews.get(connect_webview_id: webview.connect_webview_id)

  puts updated_webview.login_successful # true
  ```
</CodeGroup>

## 3 — Retrieve Schlage Lock Devices

After a Schlage account is linked with Seam, you can retrieve devices for this Schlage account. The Seam API exposes most of the device's properties such as battery level or door lock status.

<CodeGroup>
  ```javascript JavaScript theme={null}
  const allLocks = await seam.locks.list()

  const someLock = allLocks[0]

  console.log(someLock.properties.online) // true
  console.log(someLock.properties.locked) // true

  console.log(someLock)
  /*
  {
    device_id: 'e2d95c42-b2bf-4d07-9211-7407d9c90c73',
    device_type: 'schlage_lock',
    capabilities_supported: [ 'access_code', 'lock' ],
    properties: {
      locked: false,
      online: true,
      manufacturer: 'schlage',
      battery_level: 0.48,
      schlage_metadata: {
        device_id: 'device-1',
        device_name: 'FRONT DOOR',
        access_code_length: 4
      },
      name: 'FRONT DOOR'
    },
    location: null,
    connected_account_id: '1de737bc-12d1-4631-8a56-dbb2e61f1f51',
    workspace_id: 'd7418ff3-a476-4f48-9a4b-211d1d21a03d',
    created_at: '2022-12-16T01:15:17.478Z',
    errors: [],
    warnings: []
  }
  */
  ```

  ```ruby Ruby theme={null}
  some_lock = seam.locks.list.first

  puts some_lock.properties.online # true
  puts some_lock.properties.locked # true

  puts some_lock
  # <Seam::Device:0x009b0
  #   device_id="e2d95c42-b2bf-4d07-9211-7407d9c90c73"
  #   device_type="schlage_lock"
  #   properties={
  #     "locked"=>false,
  #     "online"=>true,
  #     "manufacturer"=>"schlage",
  #     "battery_level"=>0.48,
  #     "schlage_metadata"=>{"device_id"=>"device-1", "device_name"=>"FRONT DOOR", "access_code_length"=>4},
  #     "name"=>"FRONT DOOR"}
  #   created_at=2022-12-16 01:15:17.478 UTC
  #   errors=[]
  #   warnings=[]>
  ```

  ```python Python theme={null}
  all_locks = seam.locks.list()

  some_lock = all_locks[0]

  assert some_lock.properties["online"] is True
  assert some_lock.properties["locked"] is True

  print(some_lock)
  # Device(device_id='e2d95c42-b2bf-4d07-9211-7407d9c90c73',
  #   device_type='schlage_lock',
  #   location=None,
  #   properties={
  #     'locked': True,
  #     'online': True,
  #     'manufacturer': 'schlage',
  #     'battery_level': 0.48,
  #     'schlage_metadata': {'device_id': 'device-1', 'device_name': 'FRONT DOOR', 'access_code_length': 4},
  #     'name': 'FRONT DOOR'
  #   },
  #   capabilities_supported=['access_code', 'lock'])
  ```
</CodeGroup>

### 4 — Locking & Unlocking a Door

Next, you can perform the basic action of locking and unlocking the door.

> **`POST`** `/locks/lock_door`
>
> See the [API Reference](/api/locks/lock_door) for details.

## Unlock a door

<mark>`POST`</mark>
`https://connect.getseam.com/locks/unlock_door`

#### Request Body

| Name       | Type   | Description |
| ---------- | ------ | ----------- |
| device\_id | String |             |

<CodeGroup>
  ```javascript JavaScript theme={null}
  // lock the door
  await seam.locks.lockDoor(someLock.device_id)
  const updatedLock = await seam.locks.get(someLock.device_id)
  console.log(updatedLock.properties.locked) // true

  // unlock the door
  await seam.locks.unlockDoor(someLock.device_id)
  updatedLock = await seam.locks.get(someLock.device_id)
  console.log(updatedLock.properties.locked) // false
  ```

  ```python Python theme={null}
  # lock the door
  seam.locks.lock_door(device_id: some_lock.device_id)
  updated_lock = seam.locks.get(device_id: some_lock.device_id)
  assert updated_lock.properties["locked"] is True

  # Now unlock the door
  seam.locks.unlock_door(device_id: some_lock.device_id)
  updated_lock = seam.locks.get(device_id: some_lock.device_id)
  assert updated_lock.properties["locked"] is False
  ```

  ```ruby Ruby theme={null}
  # lock the door
  seam.locks.lock_door(device_id: some_lock.device_id)
  updated_lock = seam.locks.get(device_id: some_lock.device_id)
  puts updated_lock.properties.locked # true

  # unlock the door
  seam.locks.unlock_door(device_id: some_lock.device_id)
  updated_lock = seam.locks.get(device_id: some_lock.device_id)
  puts updated_lock.properties.locked # false
  ```
</CodeGroup>

### 5 — Setting Access Code on Schlage Lock

All Schlage wifi locks come with a keypad built-in to program access codes. These codes can then be entered to unlock a Schlage lock.

The Seam API makes it easy to program both `ongoing` codes and `timebound` codes on a Schlage lock. You can find out more about Schlage lock access code in our [core concept section on access codes.](/low-level-apis/smart-locks/access-codes)

<CodeGroup>
  ```javascript JavaScript theme={null}
  // create an ongoing code
  await seam.accessCodes.create({
    device_id: someLock.device_id,
    code: '123456',
    name: 'Personal Access Code',
  })

  // create a timebound code
  await seam.accessCodes.create({
    device_id: someLock.device_id,
    code: '888888',
    name: 'My Temp Access Code',
    starts_at: '2028-11-12T19:23:42+0000',
    ends_at: '2028-11-13T19:23:42+0000',
  })

  // use a device_id as the "device_id" parameter
  await seam.accessCodes.list({
    device_id: someLock.device_id,
  })

  /*
  [
    {
      code: '1988',
      type: 'ongoing',
      status: 'setting',
      created_at: '2022-08-26T12:50:17.858Z',
      access_code_id: '26d6138c-6524-4f3c-ac96-43cc3bea0a8d'
    },
    {
      type: 'timebound',
      code: '888888',
      starts_at: '2028-08-12T19:24:00.000Z',
      ends_at: '2028-08-13T19:24:00.000Z',
      access_code_id: '8c2db4da-b137-4c08-a2c3-d611e6ff91b3',
    }
  ]
  */
  ```

  ```python Python theme={null}
  # create an ongoing code
  seam.access_codes.create(
      device=some_lock, code="123456", name="Personal Access Code"
  )

  # create a timebound code
  seam.access_codes.create(
      device=some_lock,
      code="888888",
      name="My Temp Access Code",
      starts_at="2028-08-12T19:23:42+0000",
      ends_at="2028-08-13T19:23:42+0000"
  )

  # you can use a device or a device_id as the "device" parameter
  seam.access_codes.list(device=some_lock)
  # [
  #   AccessCode(
  #     access_code_id='af5272b1-2a49-4eb5-9388-2447fc7b5bd1',
  #     type='ongoing',
  #     code='123459'
  #   ),
  #   AccessCode(
  #     access_code_id='8c2db4da-b137-4c08-a2c3-d611e6ff91b3',
  #     type='timebound',
  #     code='888888',
  #     starts_at='2028-08-12T19:24:00.000Z',
  #     ends_at='2028-08-13T19:24:00.000Z',
  #   )
  # ]

  ```

  ```ruby Ruby theme={null}
  # create an ongoing code
  seam.access_codes.create(
    device_id: some_lock.device_id, code: '123456', name: 'Personal Access Code'
  )

  # create a timebound code
  seam.access_codes.create(
    device_id: some_lock.device_id,
    code: '888888',
    name: 'My Temp Access Code',
    starts_at: '2028-08-12T19:23:42+0000',
    ends_at: '2028-08-13T19:23:42+0000'
  )

  seam.access_codes.list(device_id: some_lock.device_id)

  # [<Seam::AccessCode:0x00730
  #   code="888888"
  #   name="My Temp Access Code"
  #   type="time_bound"
  #   errors=[]
  #   warnings=[]
  #   access_code_id="ce2c298c-364f-4b13-aa12-712f3976288e"
  #   ends_at=2028-08-13 19:24:00 UTC
  #   starts_at=2028-08-12 19:24:00 UTC>, <Seam::AccessCode:0x00758
  #   code="123456"
  #   name="Personal Access Code"
  #   type="ongoing"
  #   errors=[]
  #   warnings=[]
  #   access_code_id="75f49550-fc9b-481a-a158-5bc53ac9bb34">, <Seam::AccessCode:0x00780
  #   code="086355"
  #   name="some-code2"
  #   type="ongoing"
  #   errors=[]
  #   warnings=[]
  #   access_code_id="5243e5f3-528a-4378-ba3c-21447bf844a8">, <Seam::AccessCode:0x007a8
  #   code="376525"
  #   name="some-code"
  #   type="ongoing"
  #   errors=[]
  #   warnings=[]
  #   access_code_id="91a08a3d-a0bb-4ff0-bfb4-ced164353988">]
  ```
</CodeGroup>

###

## Next Steps

Now that you've completed this guide, you can try to connect a real Schlage device. To do so, make sure to switch to a non-sandbox workspace and API key as real devices cannot be connected to sandbox workspaces.

In addition, if you'd like to explore other aspects of Seam, here is a list of helpful resources:

* [Yale Getting Started Guide](../yale-locks/get-started-with-yale-locks)
* [August Getting Started Guide](../august-locks/get-started-with-august-locks)
* [SmartThings Getting Started Guide](../smartthings-hubs-+-devices/get-started-with-smartthings-hubs-+-smart-locks)
* [Receiving webhook](/developer-tools/webhooks) for [device events](/api/events/list)
* [Core Concepts](/core-concepts/overview)

If you have any questions or want to report an issue, email us at [support@seam.co](mailto:support@seam.co).


# Schlage Locks
Source: https://docs.seam.co/device-and-system-integration-guides/schlage-locks/index

Guide for using Schlage locks with Seam

<img alt="Schlage logo" />

## Overview

Schlage produces [smart locks](https://www.schlage.com/en/home/products/products-smart-locks.html) for the residential market. With a focus on security, durability, and resilience, Schlage provides smart deadbolt locks in a variety of models and styles. Seam integrates with some Schlage locks through the [Schlage Home App](https://www.schlage.com/en/home/smart-locks/schlage-app.html), while other Schlage locks require a compatible Z-Wave hub for integration.

***

## Supported Devices

<DeviceList />

This integration supports Schlage Encode™ and Connect™ locks, as well as Connected Keypad locks. Seam does not support integration with Schlage Sense™ locks.

The following table details the requirements for compatibility with this Seam integration:

<table>
  <thead>
    <tr>
      <th>Product Models</th>
      <th>Compatibility</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        Schlage

        <a href="https://www.schlage.com/en/home/products/products-smart-locks/schlage-encode/wifi-smart-lock-listing.html">
          Encode
        </a>

        and

        <a href="https://www.schlage.com/en/home/products/products-smart-locks/schlage-encode-plus/homekit-smart-lock-listing.html">
          Encode Plus
        </a>

        Smart Wi-Fi Deadbolt
      </td>

      <td>
        Compatible only with the

        <a href="https://www.schlage.com/en/home/smart-locks/schlage-app.html">
          Schlage Home App
        </a>

        .
      </td>
    </tr>

    <tr>
      <td>
        Schlage

        <a href="https://www.schlage.com/en/home/products/products-smart-locks/schlage-connect/schlage-connect-listing.html">
          Connect
        </a>

        Smart Deadbolt
      </td>

      <td>
        Compatible only with a compatible Z-Wave hub. Seam supports integration
        with the SmartThings hub.
      </td>
    </tr>

    <tr>
      <td>Schlage Connected Keypad</td>

      <td>
        Compatible only with a compatible Z-Wave hub. Seam supports integration
        with the SmartThings hub.
      </td>
    </tr>

    <tr>
      <td>
        Schlage

        <a href="https://www.schlage.com/en/home/products/products-smart-locks/schlage-sense-smart-deadbolt/schlage-sense-smart-deadbolt-listing.html">
          Sense
        </a>

        lock
      </td>

      <td>Not compatible.</td>
    </tr>
  </tbody>
</table>

For detailed information about the Schlage devices that Seam supports, see our [Schlage Supported Devices page](https://www.seam.co/manufacturers/schlage).

***

## Supported Features

We support the following features:

* [Triggering web lock and unlock actions](/low-level-apis/smart-locks/lock-and-unlock)
* [Programming online access codes](/low-level-apis/smart-locks/access-codes) on locks that have a connected keypad

***

### Device Provider Key

Seam identifies these devices with the `schlage` device provider key. By default, a [Connect Webview](/core-concepts/connect-webviews) displays all of the stable providers that Seam supports, so your users can connect their Schlage devices without you specifying a provider list. To narrow what a Connect Webview displays, see [Customize the Brands to Display in Your Connect Webviews](/core-concepts/connect-webviews/customizing-connect-webviews#customize-the-brands-to-display-in-your-connect-webviews).

***

## Troubleshooting

If you receive an "unauthorized" error, confirm that you've verified the email address associated with the Schlage account that you've connected to Seam.

***

## Where to Order

Order Schlage locks by finding a retailer on the Schlage website or by purchasing from Amazon.

<table>
  <thead>
    <tr>
      <th />

      <th />

      <th />

      <th />

      <th />
    </tr>
  </thead>

  <tbody>
    <tr>
      <td />

      <td>
        <strong>Schlage</strong>
      </td>

      <td />

      <td>
        <a href="https://www.schlage.com/en/home/products/smart-deadbolts-levers.html">
          [https://www.schlage.com/en/home/products/smart-deadbolts-levers.html](https://www.schlage.com/en/home/products/smart-deadbolts-levers.html)
        </a>
      </td>

      <td>
        <a href="/images/schlage-logo.png">schlage-logo.png</a>
      </td>
    </tr>

    <tr>
      <td />

      <td>
        <strong>Schlage Products on Amazon</strong>
      </td>

      <td />

      <td>
        <a href="https://amzn.to/3ZlSDWS">[https://amzn.to/3ZlSDWS](https://amzn.to/3ZlSDWS)</a>
      </td>

      <td>
        <a href="/images/schlage-on-amazon.png">schlage-on-amazon.png</a>
      </td>
    </tr>
  </tbody>
</table>

***


# Sandbox Schlage Encode Locks
Source: https://docs.seam.co/device-and-system-integration-guides/schlage-locks/schlage-encode-sample-data

Add virtual Schlage Encode locks to your Seam sandbox workspace using these sample credentials to test your integration without real hardware.

Use any of the following sets of credentials to add virtual Schlage Encode locks to your Seam [sandbox workspace](/core-concepts/workspaces#sandbox-workspaces):

<table>
  <thead>
    <tr>
      <th>Email Address</th>
      <th>Password</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>[jane@example.com](mailto:jane@example.com)</td>
      <td>1234</td>
    </tr>

    <tr>
      <td>[john@example.com](mailto:john@example.com)</td>
      <td>1234</td>
    </tr>

    <tr>
      <td>[andrew@example.com](mailto:andrew@example.com)</td>
      <td>1234</td>
    </tr>

    <tr>
      <td>[sam@example.com](mailto:sam@example.com)</td>
      <td>1234</td>
    </tr>

    <tr>
      <td>[frodo@example.com](mailto:frodo@example.com)</td>
      <td>1234</td>
    </tr>
  </tbody>
</table>


# Schlage Locks - Daylight Savings time adjustments
Source: https://docs.seam.co/device-and-system-integration-guides/schlage-locks/schlage-locks-daylight-savings-time-adjustments

Handling Schlage lock DST (Daylight Saving Time) schedule adjustments

Schlage locks have a known Daylight Saving Time (DST) issue that can shift access schedules by one hour during time changes. This can cause access codes to expire early or stay active longer than intended.

Because Seam does not receive timezone information from Schlage, we can’t identify which locks are in regions that observe DST. To ensure uninterrupted access, Seam has applied a preventative fix for the **November 2025 fall-back transition** to **all Schlage locks that might be in DST-observing time zones.**

During this transition, Seam automatically extends the end time of any access codes that overlap the DST change by one hour, ensuring they remain active for their intended duration.

<Info>
  **Note:** Software developers may see an “externally modified” warning on some
  codes — this is expected and indicates that Seam applied the adjustment.
</Info>

**Time zones affected by DST:**

* **North America:** Eastern, Central, Mountain, Pacific, Alaska, Newfoundland
* **Europe:** Western, Central, Eastern
* **Oceania:** Australian Eastern/Central, New Zealand

Schlage is developing a firmware update to permanently resolve this issue. Seam will maintain this workaround through the March 2026 spring-forward period.


# Schlage Locks Setup Instructions
Source: https://docs.seam.co/device-and-system-integration-guides/schlage-locks/schlage-locks-setup-instructions

Learn how to connect various types of Schlage locks to Seam.

Seam integrates with several types of Schlage locks, including Schlage Encode locks, Schlage Connect locks, and Schlage Connected Keypad locks. This topic provides instructions for connecting these types of Schlage locks to Seam.

## Schlage Encode Locks

To control Schlage Encode locks using Seam, you must prompt owners of these devices to perform the following steps:

1. Create an account in the [Schlage Home App](https://www.schlage.com/en/home/smart-locks/schlage-app.html) if you have not done so already.
2. In the Schlage Home App, add your Schlage Encode devices.
3. Note your login credentials for the Schlage Home App, and use these credentials to log in to the [Seam Connect Webview](/core-concepts/connect-webviews) to add your devices to Seam.

***

## Schlage Connect and Connected Keypad Locks

To control Schlage Connect or Connected Keypad locks with Z-Wave technology using Seam, you must prompt owners of these devices to perform the following steps:

1. Purchase a compatible Z-Wave hub.

   Currently, Seam integrates with the SmartThings Z-Wave hub.

2. Connect your lock to a Z-Wave hub.\
   Before connecting your Schlage locks to the internet, you must first connect them to a Z-Wave hub. Follow the hub's setup process to link your locks to it.

3. Note your login credentials for SmartThings, that is, the hub to which you have connected your lock.

4. In the Seam Connect Webview, select SmartThings.

5. In the Connect Webview, type the appropriate SmartThings credentials to add your devices to Seam.


# Get Started with Sensi Thermostats
Source: https://docs.seam.co/device-and-system-integration-guides/sensi-thermostats/get-started-with-sensi-thermostats

Learn how to connect and control Sensi thermostats with the Seam API.

## Overview

Seam provides a universal API to connect and control many brands of IoT devices and systems, including thermostats, smart locks, access control systems (ACSs), and noise sensors.

This guide gives you a rapid introduction to connecting and controlling your [Sensi](https://www.seam.co/manufacturers/sensi) thermostats using the Seam API. For application developers, you can use the Seam API in your app, and your users can authorize your app to control their devices using Seam.

For detailed information about the Sensi devices that Seam supports, see our [Sensi Supported Devices page](https://www.seam.co/manufacturers/sensi).

To learn more about other IoT device and system brands that Seam supports—such as ecobee, Honeywell Resideo, Google Nest, Yale, Schlage, and many more—visit our [integration page](https://www.seam.co/supported-devices-and-systems).

<Check>
  This guide shows you how to install a Seam SDK and then control your Sensi thermostat using the Seam API.

  Another easy way to learn about what you can do with the Seam API is to explore the [interactive Seam CLI](/core-concepts/seam-console/seam-online-cli), which you can access from directly within the [Seam Console](/core-concepts/seam-console).

  :arrow\_forward: [Go to the Seam Console!](https://console.seam.co/)
</Check>

***

## Step 1: Install a Seam SDK

Seam provides client libraries for many languages, including JavaScript, Python, Ruby, PHP, and others, as well as a Postman collection and an [OpenAPI](https://connect.getseam.com/openapi.json) spec.

* JavaScript / TypeScript ([npm](https://www.npmjs.com/package/seam), [GitHub](https://github.com/seamapi/javascript))
* Python ([pip](https://pypi.org/project/seam/), [GitHub](https://github.com/seamapi/python))
* Ruby Gem ([rubygem](https://rubygems.org/gems/seam), [GitHub](https://github.com/seamapi/ruby))
* PHP ([packagist](https://packagist.org/packages/seamapi/seam), [GitHub](https://github.com/seamapi/php))
* C# ([nuget](https://www.nuget.org/packages/Seam), [GitHub](https://github.com/seamapi/csharp))

First, install a Seam SDK, as follows:

<Tabs>
  <Tab title="JavaScript">
    ```bash theme={null}
    npm i seam
    ```
  </Tab>

  <Tab title="Python">
    ```bash theme={null}
    pip install seam
    # For some development environments, use pip3 in this command instead of pip.
    ```
  </Tab>

  <Tab title="Ruby">
    ```bash theme={null}
    bundle add seam
    ```
  </Tab>

  <Tab title="PHP">
    ```bash theme={null}
    composer require seamapi/seam
    ```
  </Tab>

  <Tab title="C#">
    Install using [nuget](https://www.nuget.org/packages/Seam).
  </Tab>
</Tabs>

Next, go to [https://console.seam.co/](https://console.seam.co/) and [sign up for Seam](/core-concepts/seam-console#create-a-seam-account) to get your [API key](/core-concepts/authentication/api-keys).

Then, export your API key as an environment variable.

```bash theme={null}
$ export SEAM_API_KEY=seam_test2bMS_94SrGUXuNR2JmJkjtvBQDg5c
```

<Info>
  This guide uses a [sandbox
  workspace](/core-concepts/workspaces#sandbox-workspaces).
  You can only connect virtual devices and systems in this type of workspace. If
  you want to connect a real Sensi thermostat, use a [non-sandbox
  workspace](/core-concepts/workspaces#production-workspaces)
  and API key.
</Info>

***

## Step 2: Link your Sensi account with Seam

To control your Sensi thermostat using the Seam API, you must first authorize your Seam workspace to connect to your Sensi account. If your application needs to connect to your users' Sensi accounts, Seam provides fully-embedded, [customizable](/core-concepts/connect-webviews/customizing-connect-webviews) client-side [Connect Webviews](/core-concepts/connect-webviews) to collect their authorization securely. These user-friendly pre-built authorization flows walk your users through the process of granting your Seam workspace permission to control their Sensi thermostats. The Connect Webview presents a flow that prompts your users to enter their credentials for their Sensi account.

In this guide, you create a Connect Webview object. Then, you display the graphical component of the created Connect Webview and enter a set of sample credentials to connect a sandbox Sensi account.

<Check>
  This guide shows you how to create a Connect Webview programmatically using the Seam API.

  The [Seam Console](/core-concepts/seam-console) provides another easy way to connect devices to your Seam workspace.

  Go to [https://console.seam.co/](https://console.seam.co/). On the **Devices** page, click **+ Add Devices**. Then, see [Authorize your workspace](#authorize-your-workspace) in this guide to complete the Connect Webview authorization flow.
</Check>

### Create a Connect Webview

Create a `connect_webview` object and then note the returned URL.

**Code:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  import { Seam } from 'seam'

  const seam = new Seam() // Seam automatically uses your exported SEAM_API_KEY.

  const connectWebview = await seam.connectWebviews.create()

  console.log(connectWebview.login_successful) // false

  // Use the returned Connect Webview URL to display
  // the Connect Webview authorization flow to your user.
  console.log(connectWebview.url)
  ```

  ```bash cURL theme={null}
  curl -X 'POST' \
    'https://connect.getseam.com/connect_webviews/create' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d '{}' | jq -r '"Login Successful (false): " + (.connect_webview.login_successful | tostring),
    "URL: " + .connect_webview.url'
    # Use the returned Connect Webview URL to display
    # the Connect Webview authorization flow to your user.
  ```

  ```python Python theme={null}
  from seam import Seam

  seam = Seam()  # Seam automatically uses your exported SEAM_API_KEY.

  connect_webview = seam.connect_webviews.create()

  assert connect_webview.login_successful is False

  # Use the returned Connect Webview URL to display
  # the Connect Webview authorization flow to your user.
  print(connect_webview.url)
  ```

  ```ruby Ruby theme={null}
  require "seam"

  seam = Seam.new() # Seam automatically uses your exported SEAM_API_KEY.

  connect_webview = seam.connect_webviews.create()

  puts connect_webview.login_successful # false

  # Use the returned Connect Webview URL to display
  # the Connect Webview authorization flow to your user.
  puts connect_webview.url
  ```

  ```php PHP theme={null}
  <?php
  require 'vendor/autoload.php';

  $seam = new Seam\SeamClient(); // Seam automatically uses your exported SEAM_API_KEY.

  $connect_webview = $seam->connect_webviews->create();

  echo $connect_webview->login_successful ? 'true' : 'false', "\n"; // false

  // Use the returned Connect Webview URL to display
  // the Connect Webview authorization flow to your user.
  echo $connect_webview->url;
  ```

  ```csharp C# theme={null}
  using Seam.Client;

  var seam = new SeamClient(apiToken: SEAM_API_KEY);

  var connectWebview = seam.ConnectWebviews.Create();

  Console.WriteLine(connectWebview.LoginSuccessful); // False

  // Use the returned Connect Webview URL to display
  // the Connect Webview authorization flow to your user.
  Console.WriteLine(connectWebview.Url);
  ```
</CodeGroup>

**Output:**

<CodeGroup>
  ```json JavaScript theme={null}
  false
  https://connect.getseam.com/connect_webviews/view?connect_webview_id=12345678-1234-1234-1234-123456789012&auth_token=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
  ```

  ```json cURL theme={null}
  Login Successful (false): false
  https://connect.getseam.com/connect_webviews/view?connect_webview_id=12345678-1234-1234-1234-123456789012&auth_token=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
  ```

  ```json Python theme={null}
  https://connect.getseam.com/connect_webviews/view?connect_webview_id=12345678-1234-1234-1234-123456789012&auth_token=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
  ```

  ```json Ruby theme={null}
  false
  https://connect.getseam.com/connect_webviews/view?connect_webview_id=12345678-1234-1234-1234-123456789012&auth_token=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
  ```

  ```json PHP theme={null}
  false
  https://connect.getseam.com/connect_webviews/view?connect_webview_id=12345678-1234-1234-1234-123456789012&auth_token=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
  ```

  ```json C# theme={null}
  False
  https://connect.getseam.com/connect_webviews/view?connect_webview_id=12345678-1234-1234-1234-123456789012&auth_token=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
  ```
</CodeGroup>

***

### Authorize Your Workspace

In a web browser, go to the URL that the Connect Webview object returned.

For application developers, you can redirect your user to this Connect Webview URL so that they can authorize your app to control their devices using Seam. We even provide a prebuilt [Connect Account Button](/ui-components/overview/react-components/connect-account-button) within our suite of [Seam Components](/ui-components/overview) that help you build your device management flow.

<Check>
  Because you're using a sandbox workspace, you can connect Seam's test Sensi
  account. We provide [virtual devices](./sandbox-sensi-thermostats) for each
  of the brands that we support. These sandbox devices and systems enable you to
  test your app with devices from multiple brands without the need to own all
  the corresponding physical devices.
</Check>

Complete the Connect Webview authorization flow by entering the following [Sensi sandbox account](./sandbox-sensi-thermostats) credentials:

* **Email:** [jane@example.com](mailto:jane@example.com)
* **Password:** 1234

Confirm that authorization through the Connect Webview was successful by querying its status.

**Code:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  const updatedConnectWebview = await seam.connectWebviews.get({
    connect_webview_id: connectWebview.connect_webview_id,
  })

  console.log(updatedConnectWebview.login_successful) // true
  ```

  ```bash cURL theme={null}
  curl -X 'GET' \
    'https://connect.getseam.com/connect_webviews/get' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d "{
    \"connect_webview_id\": \"${connect_webview_id}\"
  }" | jq -r '"Login Successful (true): " + (.connect_webview.login_successful | tostring)'
  ```

  ```python Python theme={null}
  updated_connect_webview = seam.connect_webviews.get(connect_webview.connect_webview_id)

  assert updated_connect_webview.login_successful is True # True
  ```

  ```ruby Ruby theme={null}
  updated_connect_webview = seam.connect_webviews.get(
    connect_webview_id: connect_webview.connect_webview_id
  )

  puts updated_connect_webview.login_successful # true
  ```

  ```php PHP theme={null}
  $updated_connect_webview = $seam->connect_webviews->get(
    connect_webview_id: $connect_webview->connect_webview_id
  );

  echo $updated_connect_webview->login_successful ? 'true' : 'false', "\n"; // true
  ```

  ```csharp C# theme={null}
  var updatedConnectWebview = seam.ConnectWebviews.Get(
    connectWebviewId: connectWebview.connectWebviewId
  );

  Console.WriteLine(updatedConnectWebview.LoginSuccessful); // True
  ```
</CodeGroup>

**Output:**

<CodeGroup>
  ```json JavaScript theme={null}
  true
  ```

  ```json cURL theme={null}
  Login Successful (true): true
  ```

  ```json Python theme={null}
  True
  ```

  ```json Ruby theme={null}
  true
  ```

  ```json PHP theme={null}
  true
  ```

  ```json C# theme={null}
  True
  ```
</CodeGroup>

***

## Step 3: Retrieve Sensi thermostat devices

When you link a Sensi account with Seam, we create a `device` object to represent each Sensi thermostat in your account. You can then retrieve these Sensi devices using the [List Devices](/api/devices/list) and [Get Device](/api/devices/get) endpoints.

The Seam API exposes each device's properties, such as the current temperature reading in Fahrenheit and Celsius, current HVAC and fan modes, available climate presets, thermostat-specific constraints, and much more.

**Code:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  // Retrieve all devices, filtered by manufacturer,
  // which is one of several filters that list() supports.
  const allSensiThermostats = await seam.devices.list({ manufacturer: 'sensi' })

  // Select the first device as an example.
  const livingRoomThermostat = allSensiThermostats[0]

  // Inspect specific properties.
  console.log(
    'Current temperature: ' +
      livingRoomThermostat.properties.temperature_fahrenheit,
  )
  console.log('Fan running: ' + livingRoomThermostat.properties.is_fan_running)

  // View the entire returned device object.
  console.log(livingRoomThermostat)
  ```

  ```bash cURL theme={null}
  # Retrieve all devices, filtered by manufacturer, which is
  # one of several filters that the list endpoint supports.
  all_sensi_thermostats=$(
    # Use GET or POST.
    curl -X 'GET' \
      'https://connect.getseam.com/devices/list' \
      -H 'accept: application/json' \
      -H "Authorization: Bearer ${SEAM_API_KEY}" \
      -H 'Content-Type: application/json' \
      -d '{
      "manufacturer": "sensi"
    }')

  # Select the first device as an example.
  living_room_thermostat=$(jq -r '.devices[0]' <<< ${all_sensi_thermostats})

  # Inspect specific properties.
  echo $(jq -r '"Current temperature: " + (.properties.temperature_fahrenheit | tostring)' <<< ${living_room_thermostat})
  echo $(jq -r '"Fan running: " + (.properties.is_fan_running | tostring)' <<< ${living_room_thermostat})

  # View the entire returned device object.
  echo ${living_room_thermostat}
  ```

  ```python Python theme={null}
  # Retrieve all devices, filtered by manufacturer,
  # which is one of several filters that list() supports.
  all_sensi_thermostats = seam.devices.list(manufacturer="sensi")

  # Select the first device as an example.
  living_room_thermostat = all_sensi_thermostats[0]

  # Inspect specific properties.
  pprint("Current temperature: " + str(living_room_thermostat.properties["temperature_fahrenheit"]))
  pprint("Fan running: " + str(living_room_thermostat.properties["is_fan_running"]))

  # View the entire returned device object.
  pprint(living_room_thermostat)
  ```

  ```ruby Ruby theme={null}
  # Retrieve all devices, filtered by manufacturer,
  # which is one of several filters that list() supports.
  all_sensi_thermostats = seam.devices.list(manufacturer: "sensi")

  # Select the first device as an example.
  living_room_thermostat = all_sensi_thermostats[0]

  # Inspect specific properties.
  puts "Current temperature: " + living_room_thermostat.properties.temperature_fahrenheit.to_s
  puts "Fan running: " + living_room_thermostat.properties.is_fan_running.to_s

  # View the entire returned device object.
  puts living_room_thermostat.inspect
  ```

  ```php PHP theme={null}
  // Retrieve all devices, filtered by manufacturer,
  // which is one of several filters that list() supports.
  $all_sensi_thermostats = $seam->devices->list(manufacturer: "sensi");

  // Select the first device as an example.
  $living_room_thermostat = $all_sensi_thermostats[0];

  // Inspect specific properties.
  echo "Current temperature: ", $living_room_thermostat->properties->temperature_fahrenheit, "\n";
  echo "Fan running: ", $living_room_thermostat->properties->is_fan_running ? 'true' : 'false', "\n";

  // View the entire returned device object.
  echo json_encode($living_room_thermostat, JSON_PRETTY_PRINT);
  ```

  ```csharp C# theme={null}
  // Coming soon!
  ```
</CodeGroup>

**Output:**

<CodeGroup>
  ```json JavaScript theme={null}
  Current temperature: 70
  Fan running: false
  {
    device_id: '11111111-1111-1111-2222-444444444444',
    workspace_id: '00000000-0000-0000-0000-000000000000',
    connected_account_id: '11111111-1111-1111-1111-222222222222',
    created_at: '2024-10-03T22:12:15.666Z',
    properties: {
      manufacturer: 'sensi',
      online: true,
      temperature_celsius: 21.11111111111111,
      temperature_fahrenheit: 70,
      relative_humidity: 0.36,
      is_cooling: false,
      is_heating: false,
      is_fan_running: false,
      current_climate_setting: {
        display_name: 'Manual Setting',
        fan_mode_setting: 'auto',
        hvac_mode_setting: 'heat',
        manual_override_allowed: true,
        heating_set_point_celsius: 21.11111111111111,
        heating_set_point_fahrenheit: 70
      },
      ...
    },
    can_hvac_cool: true,
    can_hvac_heat: true,
    can_turn_off_hvac: true,
    ...
  }
  ```

  ```json cURL theme={null}
  Current temperature: 70
  Fan running: false
  {
    "device_id": "11111111-1111-1111-2222-444444444444",
    "workspace_id": "00000000-0000-0000-0000-000000000000",
    "connected_account_id": "11111111-1111-1111-1111-222222222222",
    "created_at": "2024-10-03T22:12:15.666Z",
    "properties": {
      "manufacturer": "sensi",
      "online": true,
      "temperature_celsius": 21.11111111111111,
      "temperature_fahrenheit": 70,
      "relative_humidity": 0.36,
      "is_cooling": false,
      "is_heating": false,
      "is_fan_running": false,
      "current_climate_setting": {
        "display_name": "Manual Setting",
        "fan_mode_setting": "auto",
        "hvac_mode_setting": "heat",
        "manual_override_allowed": true,
        "heating_set_point_celsius": 21.11111111111111,
        "heating_set_point_fahrenheit": 70
      },
      ...
    },
    "can_hvac_cool": true,
    "can_hvac_heat": true,
    "can_turn_off_hvac": true,
    ...
  }
  ```

  ```json Python theme={null}
  'Current temperature: 70'
  'Fan running: False'
  Device(
    device_id='11111111-1111-1111-2222-444444444444',
    workspace_id='00000000-0000-0000-0000-000000000000',
    connected_account_id='11111111-1111-1111-1111-222222222222',
    created_at='2024-10-03T22:12:15.666Z',
    properties={
      'manufacturer': 'sensi',
      'online': True,
      'temperature_celsius': 21.11111111111111,
      'temperature_fahrenheit': 70,
      'relative_humidity': 0.36,
      'is_cooling': False,
      'is_heating': False,
      'is_fan_running': False,
      'current_climate_setting': {
        'display_name': 'Manual Setting',
        'fan_mode_setting': 'auto',
        'heating_set_point_celsius': 21.11111111111111,
        'heating_set_point_fahrenheit': 70,
        'hvac_mode_setting': 'heat',
        'manual_override_allowed': True
      },
      ...
    },
    can_hvac_cool=True,
    can_hvac_heat=True,
    can_turn_off_hvac=True,
    ...
  )
  ```

  ```json Ruby theme={null}
  Current temperature: 70
  Fan running: false
  <Seam::Resources::Device:0x005f0
    device_id="11111111-1111-1111-2222-444444444444"
    workspace_id="00000000-0000-0000-0000-000000000000"
    connected_account_id="11111111-1111-1111-1111-222222222222"
    created_at=2024-10-03 22:12:15.666 UTC
    properties=#<Seam::DeepHashAccessor:0x0000016b1791f068 @data={
      "manufacturer"=>"sensi",
      "online"=>true,
      "temperature_celsius"=>21.11111111111111,
      "temperature_fahrenheit"=>70,
      "relative_humidity"=>0.36,
      "is_cooling"=>false,
      "is_heating"=>false,
      "is_fan_running"=>false,
      "current_climate_setting"=>{
        "display_name"=>"Manual Setting",
        "fan_mode_setting"=>"auto",
        "hvac_mode_setting"=>"heat",
        "manual_override_allowed"=>true,
        "heating_set_point_celsius"=>21.11111111111111,
        "heating_set_point_fahrenheit"=>70
      },
      ...
    }>
    can_hvac_cool=true
    can_hvac_heat=true
    can_turn_off_hvac=true
    ...
  >
  ```

  ```json PHP theme={null}
  Current temperature: 70
  Fan running: false
  {
    "device_id": "11111111-1111-1111-2222-444444444444",
    "workspace_id": "00000000-0000-0000-0000-000000000000",
    "connected_account_id": "11111111-1111-1111-1111-222222222222",
    "created_at": "2024-10-03T22:12:15.666Z",
    "properties": {
      "manufacturer": "sensi",
      "online": true,
      "temperature_celsius": 21.11111111111111,
      "temperature_fahrenheit": 70,
      "relative_humidity": 0.36,
      "is_cooling": false,
      "is_heating": false,
      "is_fan_running": false,
      "current_climate_setting": {
        "display_name": "Manual Setting",
        "fan_mode_setting": "auto",
        "heating_set_point_celsius": 21.11111111111111,
        "heating_set_point_fahrenheit": 70,
        "hvac_mode_setting": "heat",
        "manual_override_allowed": true,
        ...
      },
      ...
    },
    "can_hvac_cool": true,
    "can_hvac_heat": true,
    "can_turn_off_hvac": true,
    ...
  }
  ```

  ```json C# theme={null}
  // Coming soon!
  ```
</CodeGroup>

***

## Step 4: Control your Sensi thermostat

Next, you can use the Seam API to control your Sensi thermostat.

Each device that you connect to Seam has a specific set of capabilities. These capabilities define the Seam API actions that you can use. For thermostats, device-specific capabilities include whether you can [set the HVAC mode](/capability-guides/thermostats/configure-current-climate-settings) to `heat`, `cool`, or `heat_cool`. Seam's intuitive and granular [capability flags](/capability-guides/device-and-system-capabilities#capability-flags) inform your application about what features and behaviors each device supports. Notice the capability flags within the code samples in this guide.

Seam provides additional actions for thermostats, such as setting the fan mode, creating and scheduling climate presets, setting temperature thresholds, and configuring weekly thermostat programs. You can also monitor for Seam thermostat-related events, such as reported temperatures outside your set thresholds.

Try out the following actions on your Sensi thermostat:

* [ ] [Set the HVAC mode](#set-the-hvac-mode)
* [ ] [Create and schedule climate presets](#create-and-schedule-climate-presets)
* [ ] [Configure a weekly thermostat program](#configure-a-weekly-thermostat-program)

### Set the HVAC mode

To set the HVAC mode, use any of the following endpoints or their equivalents in the Seam SDKs:

* `/thermostats/heat`
* `/thermostats/cool`
* `/thermostats/heat_cool` (for devices that support this mode)
* `/thermostats/off`
* `/thermostats/set_hvac_mode`

  This endpoint is a consolidated version of the other four endpoints.

Specify the thermostat that you want to control by including the `device_id` in the request body. Also, include the desired temperature [set point](/capability-guides/thermostats/understanding-thermostat-concepts/set-points).

In this example, set the HVAC mode to `heat` and the desired heating set point to 68 °F.

Each of these HVAC mode endpoints returns an [action attempt](/core-concepts/action-attempts) to track the progress of the operation.

**Code:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  // Confirm that the device supports heat mode.
  // You're using a capability flag here!
  if (livingRoomThermostat.can_hvac_heat) {
    // Set the HVAC mode
    // and return an action attempt.
    const actionAttempt = await seam.thermostats.heat({
      device_id: livingRoomThermostat.device_id,
      heating_set_point_fahrenheit: 68,
    })
  }
  ```

  ```bash cURL theme={null}
  # Confirm that the device supports heat mode.
  # You're using a capability flag here!
  if  $(jq -r '.can_hvac_heat' <<< ${living_room_thermostat}); then \
    # Set the HVAC mode
    # and return an action attempt.
    curl -X 'POST' \
      'https://connect.getseam.com/thermostats/heat' \
      -H 'accept: application/json' \
      -H "Authorization: Bearer ${SEAM_API_KEY}" \
      -H 'Content-Type: application/json' \
      -d "{
        \"device_id\": \"$(jq -r '.device_id' <<< ${living_room_thermostat})\",
        \"heating_set_point_fahrenheit\": 68
    }";
  fi
  ```

  ```python Python theme={null}
  # Confirm that the device supports heat mode.
  # You're using a capability flag here!
  if living_room_thermostat.can_hvac_heat:
    # Set the HVAC mode
    # and return an action attempt.
    action_attempt = seam.thermostats.heat(
      device_id = living_room_thermostat.device_id,
      heating_set_point_fahrenheit = 68
    )
  ```

  ```ruby Ruby theme={null}
  # Confirm that the device supports heat mode.
  # You're using a capability flag here!
  if (living_room_thermostat.can_hvac_heat)
    # Set the HVAC mode
    # and return an action attempt.
    action_attempt = seam.thermostats.heat(
      device_id: living_room_thermostat.device_id,
      heating_set_point_fahrenheit: 68
    )
  end
  ```

  ```php PHP theme={null}
  // Confirm that the device supports heat mode.
  // You're using a capability flag here!
  if ($living_room_thermostat->can_hvac_heat) {
    // Set the HVAC mode
    // and return an action attempt.
    $action_attempt = $seam->thermostats->heat(
      device_id: $living_room_thermostat->device_id,
      heating_set_point_fahrenheit: 68
    );
  }
  ```

  ```csharp C# theme={null}
  // Coming soon!
  ```
</CodeGroup>

**Output:**

<CodeGroup>
  ```json JavaScript theme={null}
  {
    "actionAttempt": {
      "status": "success",
      "action_attempt_id": "11111111-2222-3333-4444-555555555555",
      "action_type": "SET_HVAC_MODE",
      "result": {},
      "error": null
    }
  }
  ```

  ```json cURL theme={null}
  {
    "action_attempt": {
      "status": "pending",
      "action_type": "SET_HVAC_MODE",
      "action_attempt_id": "11111111-2222-3333-4444-555555555555",
      "result": null,
      "error": null
    },
    "ok": true
  }
  ```

  ```json Python theme={null}
  ActionAttempt(
    action_attempt_id='11111111-2222-3333-4444-555555555555',
    action_type='SET_HVAC_MODE',
    status='success',
    result={},
    error=None
  )
  ```

  ```json Ruby theme={null}
  <Seam::Resources::ActionAttempt:0x005f0
    status="success"
    action_type="SET_HVAC_MODE"
    action_attempt_id="11111111-2222-3333-4444-555555555555"
    result={}
    error=nil>
  ```

  ```json PHP theme={null}
  {
    "action_attempt_id": "11111111-2222-3333-4444-555555555555",
    "action_type": "SET_HVAC_MODE",
    "error": null,
    "result": {},
    "status": "success"
  }
  ```

  ```json C# theme={null}
  // Coming soon!
  ```
</CodeGroup>

You can track the status of the operation to confirm that the device was set to heat mode successfully. Query `properties.current_climate_setting.hvac_mode_setting` for the device, [retrieve the action attempt](/api/action_attempts/get) by ID, or look for a [`thermostat.manually_adjusted` event](/api/thermostats/events#thermostat-manually_adjusted). Further, if you wanted to find out whether the HVAC system was currently heating, you could inspect `properties.is_heating` for the device.

To query `properties.current_climate_setting.hvac_mode_setting` for the device:

**Code:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  // Get the device by ID.
  const updatedLivingRoomThermostat = await seam.devices.get({
    device_id: livingRoomThermostat.device_id,
  })

  // Inspect properties.current_climate_setting.hvac_mode_setting
  // to confirm that setting the HVAC mode to heat was successful.
  console.log(
    updatedLivingRoomThermostat.properties.current_climate_setting
      .hvac_mode_setting,
  )
  ```

  ```bash cURL theme={null}
  # Get the device by ID.
  updated_living_room_thermostat=$(
    # Use GET or POST.
    curl -X 'GET' \
      'https://connect.getseam.com/devices/get' \
      -H 'accept: application/json' \
      -H "Authorization: Bearer ${SEAM_API_KEY}" \
      -H 'Content-Type: application/json' \
      -d "{
        \"device_id\": \"$(jq -r '.device_id' <<< ${living_room_thermostat})\"
    }")

  # Inspect properties.current_climate_setting.hvac_mode_setting
  # to confirm that setting the HVAC mode to heat was successful.
  echo $(jq -r '(.device.properties.current_climate_setting.hvac_mode_setting)' <<< ${updated_living_room_thermostat})
  ```

  ```python Python theme={null}
  # Get the device by ID.
  updated_living_room_thermostat = seam.devices.get(
    device_id = living_room_thermostat.device_id
  )

  # Inspect properties.current_climate_setting.hvac_mode_setting
  # to confirm that setting the HVAC mode to heat was successful.
  pprint(
    updated_living_room_thermostat.
    properties["current_climate_setting"]["hvac_mode_setting"]
  )
  ```

  ```ruby Ruby theme={null}
  # Get the device by ID.
  updated_living_room_thermostat = seam.devices.get(
    device_id: living_room_thermostat.device_id
  )

  # Inspect properties.current_climate_setting.hvac_mode_setting
  # to confirm that setting the HVAC mode to heat was successful.
  puts updated_living_room_thermostat.
    properties.current_climate_setting.hvac_mode_setting
  ```

  ```php PHP theme={null}
  // Get the device by ID.
  $updated_living_room_thermostat = $seam->devices->get(
    device_id: $living_room_thermostat->device_id
  );

  // Inspect properties.current_climate_setting.hvac_mode_setting
  // to confirm that setting the HVAC mode to heat was successful.
  echo $updated_living_room_thermostat->properties->
    current_climate_setting->hvac_mode_setting;
  ```

  ```csharp C# theme={null}
  // Coming soon!
  ```
</CodeGroup>

**Output:**

<CodeGroup>
  ```json JavaScript theme={null}
  heat
  ```

  ```json cURL theme={null}
  heat
  ```

  ```json Python theme={null}
  'heat'
  ```

  ```json Ruby theme={null}
  heat
  ```

  ```json PHP theme={null}
  heat
  ```

  ```json C# theme={null}
  // Coming soon!
  ```
</CodeGroup>

***

### Create and schedule climate presets

You can use the Seam API to create climate presets for Sensi thermostats. Each climate preset is a saved group of settings, such as HVAC mode, fan mode, and temperature set points. Climate presets make it quick and easy to apply consistent climate settings for different scenarios. For example, you could create two climate presets: a comfort preset for when a vacation rental is occupied and an eco preset for when the vacation rental is empty.

You can schedule climate presets to start and stop whenever you'd like. You can even set a fallback climate preset, such as eco.

In this example, create comfort and eco climate presets, set eco as the fallback, and schedule the comfort climate preset to coincide with two vacation rental reservations.

**Code:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  // Confirm that the thermostat supports cool mode
  // so that the climate presets can use this mode.
  if (updatedLivingRoomThermostat.can_hvac_cool) {
    // Create the climate presets.
    await seam.thermostats.createClimatePreset({
      device_id: updatedLivingRoomThermostat.device_id,
      climate_preset_key: 'comfort',
      name: 'Comfort',
      fan_mode_setting: 'auto',
      hvac_mode_setting: 'cool',
      cooling_set_point_celsius: 25,
    })

    await seam.thermostats.createClimatePreset({
      device_id: updatedLivingRoomThermostat.device_id,
      climate_preset_key: 'eco',
      name: 'Eco',
      fan_mode_setting: 'auto',
      hvac_mode_setting: 'cool',
      cooling_set_point_celsius: 30,
    })

    // Then, set eco as the fallback climate setting.
    await seam.thermostats.setFallbackClimatePreset({
      device_id: updatedLivingRoomThermostat.device_id,
      climate_preset_key: 'eco',
    })

    // Now, schedule the comfort preset to coincide with two reservations.
    await seam.thermostats.schedules.create({
      device_id: updatedLivingRoomThermostat.device_id,
      name: "Jim's stay",
      climate_preset_key: 'comfort',
      starts_at: '2025-03-10T15:00:00Z',
      ends_at: '2025-03-15T12:00:00Z',
      is_override_allowed: true,
      max_override_period_minutes: 90,
    })

    await seam.thermostats.schedules.create({
      device_id: updatedLivingRoomThermostat.device_id,
      name: "Jane's stay",
      climate_preset_key: 'comfort',
      starts_at: '2025-03-17T15:00:00Z',
      ends_at: '2025-03-20T12:00:00Z',
      is_override_allowed: true,
      max_override_period_minutes: 90,
    })
  }
  ```

  ```bash cURL theme={null}
  # Confirm that the thermostat supports cool mode
  # so that the climate presets can use this mode.
  if  $(jq -r '.device.can_hvac_cool' <<< ${updated_living_room_thermostat}); then \
    # Create the climate presets.
    curl -X 'POST' \
      'https://connect.getseam.com/thermostats/create_climate_preset' \
      -H 'accept: application/json' \
      -H "Authorization: Bearer ${SEAM_API_KEY}" \
      -H 'Content-Type: application/json' \
      -d "{
        \"device_id\": \"$(jq -r '.device.device_id' <<< ${updated_living_room_thermostat})\",
        \"climate_preset_key\": \"comfort\",
        \"name\": \"Comfort\",
        \"fan_mode_setting\": \"auto\",
        \"hvac_mode_setting\": \"cool\",
        \"cooling_set_point_celsius\": 25
    }";

    curl -X 'POST' \
      'https://connect.getseam.com/thermostats/create_climate_preset' \
      -H 'accept: application/json' \
      -H "Authorization: Bearer ${SEAM_API_KEY}" \
      -H 'Content-Type: application/json' \
      -d "{
        \"device_id\": \"$(jq -r '.device.device_id' <<< ${updated_living_room_thermostat})\",
        \"climate_preset_key\": \"eco\",
        \"name\": \"Eco\",
        \"fan_mode_setting\": \"auto\",
        \"hvac_mode_setting\": \"cool\",
        \"cooling_set_point_celsius\": 30
    }";

    # Then, set eco as the fallback climate setting.
    curl -X 'POST' \
      'https://connect.getseam.com/thermostats/set_fallback_climate_preset' \
      -H 'accept: application/json' \
      -H "Authorization: Bearer ${SEAM_API_KEY}" \
      -H 'Content-Type: application/json' \
      -d "{
        \"device_id\": \"$(jq -r '.device.device_id' <<< ${updated_living_room_thermostat})\",
        \"climate_preset_key\": \"eco\"
    }";

    # Now, schedule the comfort preset to coincide with two reservations.
    curl -X 'POST' \
    'https://connect.getseam.com/thermostats/schedules/create' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d "{
      \"device_id\": \"$(jq -r '.device.device_id' <<< ${updated_living_room_thermostat})\",
      \"name\":  \"Jim's stay\",
      \"climate_preset_key\": \"comfort\",
      \"starts_at\": \"2025-03-10T15:00:00Z\",
      \"ends_at\": \"2025-03-15T12:00:00Z\",
      \"is_override_allowed\": true,
      \"max_override_period_minutes\": 90
    }";

    curl -X 'POST' \
    'https://connect.getseam.com/thermostats/schedules/create' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d "{
      \"device_id\": \"$(jq -r '.device.device_id' <<< ${updated_living_room_thermostat})\",
      \"name\":  \"Jane's stay\",
      \"climate_preset_key\": \"comfort\",
      \"starts_at\": \"2025-03-17T15:00:00Z\",
      \"ends_at\": \"2025-03-20T12:00:00Z\",
      \"is_override_allowed\": true,
      \"max_override_period_minutes\": 90
    }";
  fi
  ```

  ```python Python theme={null}
  # Confirm that the thermostat supports cool mode
  # so that the climate presets can use this mode.
  if updated_living_room_thermostat.can_hvac_cool:
    # Create the climate presets.
    seam.thermostats.create_climate_preset(
      device_id = updated_living_room_thermostat.device_id,
      climate_preset_key = "comfort",
      name = "Comfort",
      fan_mode_setting = "auto",
      hvac_mode_setting = "cool",
      cooling_set_point_celsius = 25
    )

    seam.thermostats.create_climate_preset(
      device_id: updated_living_room_thermostat.device_id,
      climate_preset_key = "eco",
      name = "Eco",
      fan_mode_setting = "auto",
      hvac_mode_setting = "cool",
      cooling_set_point_celsius = 30
    )

    # Then, set eco as the fallback climate setting.
    seam.thermostats.set_fallback_climate_preset(
      device_id = updated_living_room_thermostat.device_id,
      climate_preset_key = "eco"
    )

    # Now, schedule the comfort preset to coincide with two reservations.
    seam.thermostats.schedules.create(
      device_id = updated_living_room_thermostat.device_id,
      name = "Jim's stay",
      climate_preset_key = "comfort",
      starts_at = "2025-03-10T15:00:00Z",
      ends_at = "2025-03-15T12:00:00Z",
      is_override_allowed = True,
      max_override_period_minutes = 90
    )

    seam.thermostats.schedules.create(
      device_id = updated_living_room_thermostat.device_id,
      name = "Jane's stay",
      climate_preset_key = "comfort",
      starts_at = "2025-03-17T15:00:00Z",
      ends_at = "2025-03-20T12:00:00Z",
      is_override_allowed = True,
      max_override_period_minutes = 90
    )
  ```

  ```ruby Ruby theme={null}
  # Confirm that the thermostat supports cool mode
  # so that the climate presets can use this mode.
  if (updated_living_room_thermostat.can_hvac_cool)
    # Create the climate presets.
    seam.thermostats.create_climate_preset(
      device_id: updated_living_room_thermostat.device_id,
      climate_preset_key: "comfort",
      name: "Comfort",
      fan_mode_setting: "auto",
      hvac_mode_setting: "cool",
      cooling_set_point_celsius: 25
    )

    seam.thermostats.create_climate_preset(
      device_id: updated_living_room_thermostat.device_id,
      climate_preset_key: "eco",
      name: "Eco",
      fan_mode_setting: "auto",
      hvac_mode_setting: "cool",
      cooling_set_point_celsius: 30
    )

    # Then, set eco as the fallback climate setting.
    seam.thermostats.set_fallback_climate_preset(
      device_id: updated_living_room_thermostat.device_id,
      climate_preset_key: "eco"
    )

    # Now, schedule the comfort preset to coincide with two reservations.
    seam.thermostats.schedules.create(
      device_id: updated_living_room_thermostat.device_id,
      name: "Jim's stay",
      climate_preset_key: "comfort",
      starts_at: "2025-03-10T15:00:00Z",
      ends_at: "2025-03-15T12:00:00Z",
      is_override_allowed: true,
      max_override_period_minutes: 90
    )

    await seam.thermostats.schedules.create(
      device_id: updated_living_room_thermostat.device_id,
      name: "Jane's stay",
      climate_preset_key: "comfort",
      starts_at: "2025-03-17T15:00:00Z",
      ends_at: "2025-03-20T12:00:00Z",
      is_override_allowed: true,
      max_override_period_minutes: 90
    )
  end
  ```

  ```php PHP theme={null}
  // Confirm that the thermostat supports cool mode
  // so that the climate presets can use this mode.
  if ($updated_living_room_thermostat->can_hvac_cool) {
    // Create the climate presets.
    $seam->thermostats->create_climate_preset(
      device_id: $updated_living_room_thermostat->device_id,
      climate_preset_key: "comfort",
      name: "Comfort",
      fan_mode_setting: "auto",
      hvac_mode_setting: "cool",
      cooling_set_point_celsius: 25
    );

    $seam->thermostats->create_climate_preset(
      device_id: $updated_living_room_thermostat->device_id,
      climate_preset_key: "eco",
      name: "Eco",
      fan_mode_setting: "auto",
      hvac_mode_setting: "cool",
      cooling_set_point_celsius: 30
    );

    // Then, set eco as the fallback climate setting.
    $seam->thermostats->set_fallback_climate_preset(
      device_id: $updated_living_room_thermostat->device_id,
      climate_preset_key: "eco"
    );

    // Now, schedule the comfort preset to coincide with two reservations.
    $seam->thermostats->schedules->create(
      device_id: $updated_living_room_thermostat->device_id,
      name: "Jim's stay",
      climate_preset_key: "comfort",
      starts_at: "2025-03-10T15:00:00Z",
      ends_at: "2025-03-15T12:00:00Z",
      is_override_allowed: true,
      max_override_period_minutes: 90
    );

    $seam->thermostats->schedules->create(
      device_id: updated_living_room_thermostat.device_id,
      name: "Jane's stay",
      climate_preset_key: "comfort",
      starts_at: "2025-03-17T15:00:00Z",
      ends_at: "2025-03-20T12:00:00Z",
      is_override_allowed: true,
      max_override_period_minutes: 90
    );
  }
  ```

  ```csharp C# theme={null}
  // Coming soon!
  ```
</CodeGroup>

**Output:**

<CodeGroup>
  ```json JavaScript theme={null}
  {
    thermostat_schedule_id: '88888888-1111-1111-1111-111111111111',
    name: "Jim's stay",
    device_id: '11111111-1111-1111-2222-444444444444',
    climate_preset_key: 'comfort',
    starts_at: '2025-03-10T15:00:00.000Z',
    ends_at: '2025-03-15T12:00:00.000Z',
    is_override_allowed: true,
    max_override_period_minutes: 90,
    ...
  }
  {
    thermostat_schedule_id: '88888888-1111-1111-1111-222222222222',
    name: "Jane's stay",
    device_id: '11111111-1111-1111-2222-444444444444',
    climate_preset_key: 'comfort',
    starts_at: '2025-03-17T15:00:00.000Z',
    ends_at: '2025-03-20T12:00:00.000Z',
    is_override_allowed: true,
    max_override_period_minutes: 90,
    ...
  }
  ```

  ```json cURL theme={null}
  {
    "thermostat_schedule":{
      "thermostat_schedule_id":"88888888-1111-1111-1111-111111111111",
      "name":"Jim's stay",
      "device_id":"11111111-1111-1111-2222-444444444444",
      "climate_preset_key":"comfort",
      "starts_at":"2025-03-10T15:00:00.000Z",
      "ends_at":"2025-03-15T12:00:00.000Z",
      "is_override_allowed":true,
      "max_override_period_minutes":90,
      ...
    },
    "ok":true
  }
  {
    "thermostat_schedule":{
      "thermostat_schedule_id":"88888888-1111-1111-1111-222222222222",
      "name":"Jane's stay",
      "device_id":"11111111-1111-1111-2222-444444444444",
      "climate_preset_key":"comfort",
      "starts_at":"2025-03-17T15:00:00.000Z",
      "ends_at":"2025-03-20T12:00:00.000Z",
      "is_override_allowed":true,
      "max_override_period_minutes":90,
      ...
    },
    "ok":true
  }
  ```

  ```json Python theme={null}
  ThermostatSchedule(
    thermostat_schedule_id='88888888-1111-1111-1111-111111111111',
    name="Jim's stay",
    device_id='11111111-1111-1111-2222-444444444444',
    climate_preset_key='comfort',
    starts_at='2025-03-10T15:00:00.000Z',
    ends_at='2025-03-15T12:00:00.000Z',
    is_override_allowed=True,
    max_override_period_minutes=90,
    ...
  )
  ThermostatSchedule(
    thermostat_schedule_id='88888888-1111-1111-1111-222222222222',
    name="Jane's stay",
    device_id='11111111-1111-1111-2222-444444444444',
    climate_preset_key='comfort',
    starts_at='2025-03-17T15:00:00.000Z',
    ends_at='2025-03-20T12:00:00.000Z',
    is_override_allowed=True,
    max_override_period_minutes=90,
    ...
  )
  ```

  ```json Ruby theme={null}
  <Seam::Resources::ThermostatSchedule:0x005f0
    thermostat_schedule_id="88888888-1111-1111-1111-111111111111"
    name="Jim's stay"
    device_id="11111111-1111-1111-2222-444444444444"
    climate_preset_key="comfort"
    starts_at=2025-03-10 15:00:00 UTC
    ends_at=2025-03-15 12:00:00 UTC
    is_override_allowed=true
    max_override_period_minutes=90
    ...
  >
  <Seam::Resources::ThermostatSchedule:0x005f0
    thermostat_schedule_id="88888888-1111-1111-1111-222222222222"
    name="Jane's stay"
    device_id="11111111-1111-1111-2222-444444444444"
    climate_preset_key="comfort"
    starts_at=2025-03-17 15:00:00 UTC
    ends_at=2025-03-20 12:00:00 UTC
    is_override_allowed=true
    max_override_period_minutes=90
    ...
  >
  ```

  ```json PHP theme={null}
  {
    "thermostat_schedule_id":"88888888-1111-1111-1111-111111111111",
    "name":"Jim's stay",
    "device_id":"11111111-1111-1111-2222-444444444444",
    "climate_preset_key":"comfort",
    "starts_at":"2025-03-10T15:00:00.000Z",
    "ends_at":"2025-03-15T12:00:00.000Z",
    "is_override_allowed":true,
    "max_override_period_minutes":90,
    ...
  }
  {
    "thermostat_schedule_id":"88888888-1111-1111-1111-222222222222",
    "name":"Jane's stay",
    "device_id":"11111111-1111-1111-2222-444444444444",
    "climate_preset_key":"comfort",
    "starts_at":"2025-03-17T15:00:00.000Z",
    "ends_at":"2025-03-20T12:00:00.000Z",
    "is_override_allowed":true,
    "max_override_period_minutes":90,
    ...
  }
  ```

  ```json C# theme={null}
  // Coming soon!
  ```
</CodeGroup>

***

### Configure a weekly thermostat program

You can use the Seam API to create a thermostat weekly program for your Sensi thermostat. This standard feature of smart thermostats enables you to define full-week programs that are made up of reusable daily programs. Each daily program consists of a set of thermostat daily program periods, that is, time blocks with associated climate presets.

In this example, create a weekday daily program and a weekend daily program. Then, combine these daily programs into a weekly program by assigning a daily program to each day of the week.

**Code:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  // Create the daily programs.
  const weekdayProgram = await seam.thermostats.dailyPrograms.create({
    device_id: updatedLivingRoomThermostat.device_id,
    name: 'Weekday Program',
    periods: [
      { starts_at_time: '07:00:00', climate_preset_key: 'Home' },
      { starts_at_time: '09:00:00', climate_preset_key: 'Away' },
      { starts_at_time: '18:00:00', climate_preset_key: 'Home' },
      { starts_at_time: '22:00:00', climate_preset_key: 'Sleep' },
    ],
  })

  const weekendProgram = await seam.thermostats.dailyPrograms.create({
    device_id: updatedLivingRoomThermostat.device_id,
    name: 'Weekend Program',
    periods: [
      { starts_at_time: '08:00:00', climate_preset_key: 'Home' },
      { starts_at_time: '23:00:00', climate_preset_key: 'Sleep' },
    ],
  })

  // Use the daily programs to set the weekly program.
  await seam.thermostats.updateWeeklyProgram({
    device_id: updatedLivingRoomThermostat.device_id,
    monday_program_id: weekdayProgram.thermostat_daily_program_id,
    tuesday_program_id: weekdayProgram.thermostat_daily_program_id,
    wednesday_program_id: weekdayProgram.thermostat_daily_program_id,
    thursday_program_id: weekdayProgram.thermostat_daily_program_id,
    friday_program_id: weekdayProgram.thermostat_daily_program_id,
    saturday_program_id: weekendProgram.thermostat_daily_program_id,
    sunday_program_id: weekendProgram.thermostat_daily_program_id,
  })
  ```

  ```bash cURL theme={null}
  # Create the daily programs.
  weekday_program=$(curl -X 'POST' \
    'https://connect.getseam.com/thermostats/daily_programs/create' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d "{
      \"device_id\": \"$(jq -r '.device.device_id' <<< ${updated_living_room_thermostat})\",
      \"name\":  \"Weekday Program\",
      \"periods\": [
      { \"starts_at_time\": \"07:00:00\", \"climate_preset_key\": \"Home\" },
      { \"starts_at_time\": \"09:00:00\", \"climate_preset_key\": \"Away\" },
      { \"starts_at_time\": \"18:00:00\", \"climate_preset_key\": \"Home\" },
      { \"starts_at_time\": \"22:00:00\", \"climate_preset_key\": \"Sleep\" }
    ]
  }")
  weekday_program_id=$(jq -r '.thermostat_daily_program_id' <<< ${weekday_program})

  weekend_program=$(curl -X 'POST' \
    'https://connect.getseam.com/thermostats/daily_programs/create' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d "{
      \"device_id\": \"$(jq -r '.device.device_id' <<< ${updated_living_room_thermostat})\",
      \"name\":  \"Weekend Program\",
      \"periods\": [
      { \"starts_at_time\": \"08:00:00\", \"climate_preset_key\": \"Home\" },
      { \"starts_at_time\": \"23:00:00\", \"climate_preset_key\": \"Sleep\" }
    ]
  }")
  weekend_program_id=$(jq -r '.thermostat_daily_program_id' <<< ${weekend_program})

  # Use the daily programs to set the weekly program.
  curl -X 'POST' \
    'https://connect.getseam.com/thermostats/update_weekly_program' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d "{
      \"device_id\": \"$(jq -r '.device.device_id' <<< ${updated_living_room_thermostat})\",
      \"monday_program_id\": \"${weekday_program_id}\",
      \"tuesday_program_id\": \"${weekday_program_id}\",
      \"wednesday_program_id\": \"${weekday_program_id}\",
      \"thursday_program_id\": \"${weekday_program_id}\",
      \"friday_program_id\": \"${weekday_program_id}\",
      \"saturday_program_id\": \"${weekend_program_id}\",
      \"sunday_program_id\": \"${weekend_program_id}\"
  }"
  ```

  ```python Python theme={null}
  # Create the daily programs.
  weekday_program = seam.thermostats.daily_programs.create(
    device_id = updated_living_room_thermostat.device_id,
    name = "Weekday Program",
    periods = [
      { "starts_at_time": "07:00:00", "climate_preset_key": "Home" },
      { "starts_at_time": "09:00:00", "climate_preset_key": "Away" },
      { "starts_at_time": "18:00:00", "climate_preset_key": "Home" },
      { "starts_at_time": "22:00:00", "climate_preset_key": "Sleep" }
    ]
  )

  weekend_program = seam.thermostats.daily_programs.create(
    device_id = updated_living_room_thermostat.device_id,
    name = "Weekend Program",
    periods = [
      { "starts_at_time": "08:00:00", "climate_preset_key": "Home" },
      { "starts_at_time": "23:00:00", "climate_preset_key": "Sleep" }
    ]
  )

  # Use the daily programs to set the weekly program.
  seam.thermostats.update_weekly_program(
    device_id = updated_living_room_thermostat.device_id,
    monday_program_id = weekday_program.thermostat_daily_program_id,
    tuesday_program_id = weekday_program.thermostat_daily_program_id,
    wednesday_program_id = weekday_program.thermostat_daily_program_id,
    thursday_program_id = weekday_program.thermostat_daily_program_id,
    friday_program_id = weekday_program.thermostat_daily_program_id,
    saturday_program_id = weekend_program.thermostat_daily_program_id,
    sunday_program_id = weekend_program.thermostat_daily_program_id
  )
  ```

  ```ruby Ruby theme={null}
  # Create the daily programs.
  weekday_program = seam.thermostats.daily_programs.create(
    device_id: updated_living_room_thermostat.device_id,
    name: "Weekday Program",
    periods: [
      { "starts_at_time": "07:00:00", "climate_preset_key": "Home" },
      { "starts_at_time": "09:00:00", "climate_preset_key": "Away" },
      { "starts_at_time": "18:00:00", "climate_preset_key": "Home" },
      { "starts_at_time": "22:00:00", "climate_preset_key": "Sleep" }
    ]
  )

  weekend_program = seam.thermostats.daily_programs.create(
    device_id: updated_living_room_thermostat.device_id,
    name: "Weekend Program",
    periods: [
      { "starts_at_time": "08:00:00", "climate_preset_key": "Home" },
      { "starts_at_time": "23:00:00", "climate_preset_key": "Sleep" }
    ]
  )

  # Use the daily programs to set the weekly program.
  seam.thermostats.update_weekly_program(
    device_id: updated_living_room_thermostat.device_id,
    monday_program_id: weekday_program.thermostat_daily_program_id,
    tuesday_program_id: weekday_program.thermostat_daily_program_id,
    wednesday_program_id: weekday_program.thermostat_daily_program_id,
    thursday_program_id: weekday_program.thermostat_daily_program_id,
    friday_program_id: weekday_program.thermostat_daily_program_id,
    saturday_program_id: weekend_program.thermostat_daily_program_id,
    sunday_program_id: weekend_program.thermostat_daily_program_id
  )
  ```

  ```php PHP theme={null}
  // Create the daily programs.
  $weekday_program = $seam->thermostats->daily_programs->create(
    device_id: $updated_living_room_thermostat->device_id,
    name: "Weekday Program",
    periods: [
      { "starts_at_time": "07:00:00", "climate_preset_key": "Home" },
      { "starts_at_time": "09:00:00", "climate_preset_key": "Away" },
      { "starts_at_time": "18:00:00", "climate_preset_key": "Home" },
      { "starts_at_time": "22:00:00", "climate_preset_key": "Sleep" }
    ]
  );

  $weekend_program = $seam->thermostats->daily_programs->create(
    device_id: $updated_living_room_thermostat->device_id,
    name: "Weekend Program",
    periods: [
      { "starts_at_time": "08:00:00", "climate_preset_key": "Home" },
      { "starts_at_time": "23:00:00", "climate_preset_key": "Sleep" }
    ]
  );

  // Use the daily programs to set the weekly program.
  $seam->thermostats->update_weekly_program(
    device_id: $updated_living_room_thermostat->device_id,
    monday_program_id: $weekday_program->thermostat_daily_program_id,
    tuesday_program_id: $weekday_program->thermostat_daily_program_id,
    wednesday_program_id: $weekday_program->thermostat_daily_program_id,
    thursday_program_id: $weekday_program->thermostat_daily_program_id,
    friday_program_id: $weekday_program->thermostat_daily_program_id,
    saturday_program_id: $weekend_program->thermostat_daily_program_id,
    sunday_program_id: $weekend_program->thermostat_daily_program_id
  );
  ```

  ```csharp C# theme={null}
  // Coming soon!
  ```
</CodeGroup>

**Output:**

<CodeGroup>
  ```json JavaScript theme={null}
  {
    "status": "success",
    "action_attempt_id": "11111111-2222-3333-4444-666666666666",
    "action_type": "PUSH_THERMOSTAT_PROGRAMS",
    "result": {},
    "error": null
  }
  ```

  ```json cURL theme={null}
  {
    "action_attempt": {
      "status": "pending",
      "action_type": "PUSH_THERMOSTAT_PROGRAMS",
      "action_attempt_id": "11111111-2222-3333-4444-666666666666",
      "result": null,
      "error": null
    },
    "ok": true
  }
  ```

  ```json Python theme={null}
  ActionAttempt(
    action_attempt_id='11111111-2222-3333-4444-666666666666',
    action_type='PUSH_THERMOSTAT_PROGRAMS',
    status='success',
    result={},
    error=None
  )
  ```

  ```json Ruby theme={null}
  <Seam::Resources::ActionAttempt:0x005f0
    status="success"
    action_type="PUSH_THERMOSTAT_PROGRAMS"
    action_attempt_id="11111111-2222-3333-4444-666666666666"
    result={}
    error=nil>
  ```

  ```json PHP theme={null}
  {
    "status": "success",
    "action_attempt_id": "11111111-2222-3333-4444-666666666666",
    "action_type": "PUSH_THERMOSTAT_PROGRAMS",
    "result": {},
    "error": null
  }
  ```

  ```json C# theme={null}
  // Coming soon!
  ```
</CodeGroup>

***

## Step 5: Connect a real Sensi thermostat

Now that you have learned the basics of using the Seam API, you can connect and control a real Sensi device. To do so, make sure to switch to a [non-sandbox workspace](/core-concepts/workspaces#production-workspaces) and [API key](/core-concepts/authentication/api-keys).

For more details about setting up your real Sensi thermostat, see the [Sensi thermostats integration guide](./).

***

## Step 6: Build your application!

Seam makes it easy to develop your application. The robust Seam API and Seam SDKs in a wide variety of programming languages provide robust, up-to-date information about your thermostats. We also provide helpful thermostat-related events that enable you to monitor the status of your thermostats and the connected HVAC systems. Further, our simulation endpoints make it easy for you to test your thermostat app against events that can be difficult to orchestrate in your quality assurance (QA) environment using real devices.

***

## Next steps

Now that you've completed this getting started guide for Sensi devices, you can learn more about what you can do with the Seam API.

* [ ] **Explore**\
  See the [other devices and system integrations](/device-and-system-integration-guides) that Seam supports.
* [ ] **Learn**\
  Read about Seam [concepts](/core-concepts/overview) and the [device and system capabilities ](/capability-guides/device-and-system-capabilities)that Seam supports.
* [ ] **Expand your abilities**\
  Find out what other [thermostat actions](/capability-guides/thermostats) you can perform using the Seam API.
* [ ] **Use webhooks**\
  Learn how to use [webhooks](/developer-tools/webhooks) as an efficient way to receive device events.
* [ ] **Find out more**\
  Explore the other types of devices and systems that you can control with Seam, including [smart locks](/low-level-apis/smart-locks), [access control systems](/low-level-apis/access-systems), and [noise sensors](/capability-guides/noise-sensors).
* [ ] **Develop for mobile access**\
  Learn about Seam's [mobile access solution](/capability-guides/mobile-access).

<Info>
  If you have any questions or want to report an issue, email us at
  [support@seam.co](mailto:support@seam.co).
</Info>

***

## Quick links

<CardGroup>
  <Card title="Get an API Key (free)" href="https://console.seam.co/">
    Sign up for the Seam Console and get your API keys. →
  </Card>

  <Card title="Contact Sales" href="https://www.seam.co/contact-us">
    Got a project or a specific question? Contact our team to get answers. →
  </Card>
</CardGroup>


# Sensi Thermostats
Source: https://docs.seam.co/device-and-system-integration-guides/sensi-thermostats/index

Guide for using Sensi thermostats with Seam

<img alt="Sensi logo" />

## Overview

Sensi produces smart thermostats for home and light commercial climate control. Focusing on convenience and sustainability, Sensi thermostats provide comfort and energy efficiency features. Sensi thermostats are designed for ease of use and offer features like scheduling, energy usage reports, and geofencing to optimize home temperature management.

***

## Supported Devices

<DeviceList />

This integration supports all [Sensi thermostats](https://sensi.copeland.com/en-us/products).

For detailed information about the Sensi devices that Seam supports, see our [Sensi Supported Devices page](https://www.seam.co/manufacturers/sensi).

***

## Supported Features

We support the following features:

* [Configuring current thermostat settings](/capability-guides/thermostats/configure-current-climate-settings)
* [Creating and managing climate presets](/capability-guides/thermostats/creating-and-managing-climate-presets)
* [Creating and managing thermostat schedules](/capability-guides/thermostats/creating-and-managing-thermostat-schedules)
* [Creating and managing thermostat weekly programs](/capability-guides/thermostats/creating-and-managing-thermostat-programs)
* [Setting and monitoring temperature thresholds](/capability-guides/thermostats/setting-and-monitoring-temperature-thresholds)

***

### Device Provider Key

Seam identifies these devices with the `sensi` device provider key. By default, a [Connect Webview](/core-concepts/connect-webviews) displays all of the stable providers that Seam supports, so your users can connect their Sensi devices without you specifying a provider list. To narrow what a Connect Webview displays, see [Customize the Brands to Display in Your Connect Webviews](/core-concepts/connect-webviews/customizing-connect-webviews#customize-the-brands-to-display-in-your-connect-webviews).

***

## Setup Instructions

For instructions on connecting Sensi thermostats to Seam, see the [Sensi Setup Guide](./sensi-setup-guide).

***

## Brand-Specific Restrictions

Note the following Sensi-specific restrictions:

### Battery State

The Sensi API does not communicate the battery state of Sensi devices, so Seam cannot report the battery state for these devices. However, most Sensi thermostats are hard-wired.

### Heat-Cool Mode

Some Sensi models do not support heat-cool mode, such as the Sensi Classic and Sensi One Touch thermostats. To check whether a thermostat supports heat-cool mode, [get the device](/capability-guides/thermostats/retrieving-thermostats) and look for a `device.can_hvac_heat_cool` capability flag. For more information about thermostat-related capability flags, see [Thermostat Capabilities](/capability-guides/thermostats#thermostat-capabilities).

***

## Where to Order

To purchase Sensi thermostats, visit the Sensi online store.

<table>
  <thead>
    <tr>
      <th />

      <th />

      <th />

      <th />

      <th />
    </tr>
  </thead>

  <tbody>
    <tr>
      <td />

      <td>
        <strong>Sensi Online Store</strong>
      </td>

      <td />

      <td>
        <a href="https://sensi.copeland.com/en-us/products">
          [https://sensi.copeland.com/en-us/products](https://sensi.copeland.com/en-us/products)
        </a>
      </td>

      <td>
        <a href="/images/sensi-logo.png">sensi-logo.png</a>
      </td>
    </tr>
  </tbody>
</table>


# Sandbox Sensi Thermostats
Source: https://docs.seam.co/device-and-system-integration-guides/sensi-thermostats/sandbox-sensi-thermostats

Add virtual Sensi thermostats to your Seam sandbox workspace using these sample credentials to test your integration without real hardware.

Use the following set of credentials to add virtual [Sensi thermostats](/device-and-system-integration-guides/sensi-thermostats) to your Seam [sandbox workspace](/core-concepts/workspaces#sandbox-workspaces):

| Email Address                                 | Password |
| --------------------------------------------- | -------- |
| [jane@example.com](mailto:jane@example.com)   | 1234     |
| [john@example.com](mailto:john@example.com)   | 1234     |
| [frodo@example.com](mailto:frodo@example.com) | 1234     |
| [sam@example.com](mailto:sam@example.com)     | 1234     |


# Sensi Setup Guide
Source: https://docs.seam.co/device-and-system-integration-guides/sensi-thermostats/sensi-setup-guide

Connect your Sensi thermostats to Seam.

To use Seam with Sensi thermostats, ask the device owner to complete the steps below. Thermostats must already be installed and connected to Wi-Fi before proceeding.

### 1. Set up the Sensi mobile app

1. Download and install the Sensi app for [iOS](https://apps.apple.com/us/app/sensi/id792612452) or [Android](https://play.google.com/store/apps/details?id=com.asynchrony.emerson.sensi) and create an account if you don't have one.
2. In the Sensi app, add your Sensi thermostats. The app walks you through connecting each thermostat to Wi-Fi. For details, see the [Sensi installation manual](https://sensi.copeland.com/en-us/support/sensi-manuals) for your thermostat.

### 2. Connect Sensi to Seam

1. Note your login credentials for the Sensi app.
2. In the form to connect Sensi to Seam, enter those credentials and click **Submit** to complete.

<Info>
  Sensi devices can only be registered to a single user. Make sure you're
  authenticating with the user to whom the devices are registered.
</Info>

***

### Troubleshooting

If devices don't appear after connecting your account:

* Verify that each thermostat is online in the Sensi app.
* Confirm you're logging in with the account to which the thermostats are registered. Sensi devices can only belong to one user.


# Sifely Locks
Source: https://docs.seam.co/device-and-system-integration-guides/sifely-locks/index

Guide for using Sifely smart locks with Seam

## Overview

Sifely produces smart locks and keyless entry systems built on the Sifely platform. Their product line includes deadbolts, lever locks, padlocks, and locker locks designed for residential and light commercial use. Sifely locks support keypad entry, Bluetooth, and Wi-Fi connectivity through the Sifely app and a compatible gateway.

Seam integrates with Sifely locks to provide remote lock and unlock actions and access code programming through a unified API.

***

## Supported Devices

<DeviceList />

This integration supports Sifely smart locks that are paired with a compatible Sifely gateway.

For detailed information about the Sifely devices that Seam supports, see our [Sifely Supported Devices page](https://www.seam.co/manufacturers/sifely).

***

## Supported Features

We support the following features:

* [Triggering web lock and unlock actions](/low-level-apis/smart-locks/lock-and-unlock)
* [Programming access codes](/low-level-apis/smart-locks/access-codes) on locks that have a keypad

***

## Device Provider Key

Seam identifies these devices with the `sifely` device provider key. By default, a [Connect Webview](/core-concepts/connect-webviews) displays all of the stable providers that Seam supports, so your users can connect their Sifely devices without you specifying a provider list. To narrow what a Connect Webview displays, see [Customize the Brands to Display in Your Connect Webviews](/core-concepts/connect-webviews/customizing-connect-webviews#customize-the-brands-to-display-in-your-connect-webviews).

***

## Setup Instructions

For instructions on connecting Sifely locks to Seam, see the [Sifely Setup Guide](./sifely-setup-guide).

***

## Where to Order

<CardGroup>
  <Card title="Sifely - Smart Locks" href="https://www.sifely.com/" />
</CardGroup>


# Sifely Setup Guide
Source: https://docs.seam.co/device-and-system-integration-guides/sifely-locks/sifely-setup-guide

Connect your Sifely locks to Seam.

## Overview

This guide walks you through connecting your Sifely locks to Seam. Your Sifely locks must already be set up in the Sifely app and paired with a compatible gateway before proceeding.

***

## Step 1: Connect to Seam via Connect Webview

1. Open the [Connect Webview](/core-concepts/connect-webviews) provided by your application.
2. Select **Sifely** as the provider.
3. Log in with your Sifely account credentials.
4. Once authorized, your Sifely locks appear as devices in Seam.

***

## Step 2: Verify the Connection

After connecting, verify that your Sifely locks appear as devices and show as online with lock and unlock capabilities.

***

## Troubleshooting

### Locks not appearing after authorization

Ensure your Sifely locks are set up and paired with a gateway in the Sifely app. Only locks that are online and connected to a gateway appear in Seam. You must also be the top administrator for each lock you want to connect.

### Remote unlock not working

In the Sifely app, go to your lock settings and confirm that the **Remote Unlock** feature is enabled. Seam requires this setting to control the lock remotely.

### Gateway pairing issues

Sifely locks require a compatible Sifely gateway for remote access. Confirm the gateway is online and paired to the lock in the Sifely app.


# Get Started with SmartThings Hubs + Smart Locks
Source: https://docs.seam.co/device-and-system-integration-guides/smartthings-hubs-+-devices/get-started-with-smartthings-hubs-+-smart-locks

Learn how to connect and control SmartThings-connected locks with the Seam API.

## Overview

Seam provides a universal API to connect and control many brands of IoT devices and systems, including smart locks, access control systems (ACSs), thermostats, and noise sensors.

This guide gives you a rapid introduction to connecting and controlling your [SmartThings](https://www.seam.co/manufacturers/smartthings)-connected locks using the Seam API. For application developers, you can use the Seam API in your app, and your users can authorize your app to control their devices using Seam.

You connect your locks to Seam through a SmartThings Hub. These hubs use Zigbee or Z-Wave to communicate with your locks. SmartThings Hubs are connected to your local network using Wi-Fi or Ethernet. For detailed information about the SmatThings Hubs that Seam supports, see our [SmartThings Supported Devices page](https://www.seam.co/manufacturers/smartthings).

To learn more about other IoT device and system brands that Seam supports—such as Yale, Schlage, Google Nest, and many more—visit our [integration page](https://www.seam.co/supported-devices-and-systems).

<Check>
  This guide shows you how to install a Seam SDK and then control your SmartThings-connected lock using the Seam API.

  Another easy way to learn about what you can do with the Seam API is to explore the [interactive Seam CLI](/core-concepts/seam-console/seam-online-cli), which you can access from directly within the [Seam Console](/core-concepts/seam-console).

  :arrow\_forward: [Go to the Seam Console!](https://console.seam.co/)
</Check>

***

## Step 1: Install a Seam SDK

Seam provides client libraries for many languages, including JavaScript, Python, Ruby, PHP, and others, as well as a Postman collection and an [OpenAPI](https://connect.getseam.com/openapi.json) spec.

* JavaScript / TypeScript ([npm](https://www.npmjs.com/package/seam), [GitHub](https://github.com/seamapi/javascript))
* Python ([pip](https://pypi.org/project/seam/), [GitHub](https://github.com/seamapi/python))
* Ruby Gem ([rubygem](https://rubygems.org/gems/seam), [GitHub](https://github.com/seamapi/ruby))
* PHP ([packagist](https://packagist.org/packages/seamapi/seam), [GitHub](https://github.com/seamapi/php))
* C# ([nuget](https://www.nuget.org/packages/Seam), [GitHub](https://github.com/seamapi/csharp))

First, install a Seam SDK, as follows:

<Tabs>
  <Tab title="JavaScript">
    ```bash theme={null}
    npm i seam
    ```
  </Tab>

  <Tab title="Python">
    ```bash theme={null}
    pip install seam
    # For some development environments, use pip3 in this command instead of pip.
    ```
  </Tab>

  <Tab title="Ruby">
    ```bash theme={null}
    bundle add seam
    ```
  </Tab>

  <Tab title="PHP">
    ```bash theme={null}
    composer require seamapi/seam
    ```
  </Tab>

  <Tab title="C#">
    Install using [nuget](https://www.nuget.org/packages/Seam).
  </Tab>
</Tabs>

Next, go to [https://console.seam.co/](https://console.seam.co/) and [sign up for Seam](/core-concepts/seam-console#create-a-seam-account) to get your [API key](/core-concepts/authentication/api-keys).

Then, export your API key as an environment variable.

```bash theme={null}
$ export SEAM_API_KEY=seam_test2bMS_94SrGUXuNR2JmJkjtvBQDg5c
```

<Info>
  This guide uses a [sandbox
  workspace](/core-concepts/workspaces#sandbox-workspaces).
  You can only connect virtual devices and systems in this type of workspace. If
  you want to connect a real SmartThings-connected lock, use a [non-sandbox
  workspace](/core-concepts/workspaces#production-workspaces)
  and API key.
</Info>

***

## Step 2: Link your SmartThings account with Seam

To control your SmartThings-connected lock using the Seam API, you must first authorize your Seam workspace to connect to your SmartThings account. If your application needs to connect to your users' SmartThings accounts, Seam provides fully-embedded, [customizable](/core-concepts/connect-webviews/customizing-connect-webviews) client-side [Connect Webviews](/core-concepts/connect-webviews) to collect their authorization securely. These user-friendly pre-built authorization flows walk your users through the process of granting your Seam workspace permission to control their SmartThings-connected locks. The Connect Webview presents a flow that prompts your users to enter their credentials for their SmartThings account.

In this guide, you create a Connect Webview object. Then, you display the graphical component of the created Connect Webview and enter a set of sample credentials to connect a sandbox SmartThings account.

<Check>
  This guide shows you how to create a Connect Webview programmatically using the Seam API.

  The [Seam Console](/core-concepts/seam-console) provides another easy way to connect devices to your Seam workspace.

  Go to [https://console.seam.co/](https://console.seam.co/). On the **Devices** page, click **+ Add Devices**. Then, see [Authorize your workspace](#authorize-your-workspace) in this guide to complete the Connect Webview authorization flow.
</Check>

### Create a Connect Webview

Create a `connect_webview` object and then note the returned URL.

**Code:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  import { Seam } from 'seam'

  const seam = new Seam() // Seam automatically uses your exported SEAM_API_KEY.

  const connectWebview = await seam.connectWebviews.create()

  console.log(connectWebview.login_successful) // false

  // Use the returned Connect Webview URL to display
  // the Connect Webview authorization flow to your user.
  console.log(connectWebview.url)
  ```

  ```bash cURL theme={null}
  curl -X 'POST' \
    'https://connect.getseam.com/connect_webviews/create' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d '{}' | jq -r '"Login Successful (false): " + (.connect_webview.login_successful | tostring),
    "URL: " + .connect_webview.url'
    # Use the returned Connect Webview URL to display
    # the Connect Webview authorization flow to your user.
  ```

  ```python Python theme={null}
  from seam import Seam

  seam = Seam()  # Seam automatically uses your exported SEAM_API_KEY.

  connect_webview = seam.connect_webviews.create()

  assert connect_webview.login_successful is False

  # Use the returned Connect Webview URL to display
  # the Connect Webview authorization flow to your user.
  print(connect_webview.url)
  ```

  ```ruby Ruby theme={null}
  require "seam"

  seam = Seam.new() # Seam automatically uses your exported SEAM_API_KEY.

  connect_webview = seam.connect_webviews.create()

  puts connect_webview.login_successful # false

  # Use the returned Connect Webview URL to display
  # the Connect Webview authorization flow to your user.
  puts connect_webview.url
  ```

  ```php PHP theme={null}
  <?php
  require 'vendor/autoload.php';

  $seam = new Seam\SeamClient(); // Seam automatically uses your exported SEAM_API_KEY.

  $connect_webview = $seam->connect_webviews->create();

  echo $connect_webview->login_successful ? 'true' : 'false', "\n"; // false

  // Use the returned Connect Webview URL to display
  // the Connect Webview authorization flow to your user.
  echo $connect_webview->url;
  ```

  ```csharp C# theme={null}
  using Seam.Client;

  var seam = new SeamClient(apiToken: SEAM_API_KEY);

  var connectWebview = seam.ConnectWebviews.Create();

  Console.WriteLine(connectWebview.LoginSuccessful); // False

  // Use the returned Connect Webview URL to display
  // the Connect Webview authorization flow to your user.
  Console.WriteLine(connectWebview.Url);
  ```
</CodeGroup>

**Output:**

<CodeGroup>
  ```json JavaScript theme={null}
  false
  https://connect.getseam.com/connect_webviews/view?connect_webview_id=12345678-1234-1234-1234-123456789012&auth_token=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
  ```

  ```json cURL theme={null}
  Login Successful (false): false
  https://connect.getseam.com/connect_webviews/view?connect_webview_id=12345678-1234-1234-1234-123456789012&auth_token=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
  ```

  ```json Python theme={null}
  https://connect.getseam.com/connect_webviews/view?connect_webview_id=12345678-1234-1234-1234-123456789012&auth_token=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
  ```

  ```json Ruby theme={null}
  false
  https://connect.getseam.com/connect_webviews/view?connect_webview_id=12345678-1234-1234-1234-123456789012&auth_token=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
  ```

  ```json PHP theme={null}
  false
  https://connect.getseam.com/connect_webviews/view?connect_webview_id=12345678-1234-1234-1234-123456789012&auth_token=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
  ```

  ```json C# theme={null}
  False
  https://connect.getseam.com/connect_webviews/view?connect_webview_id=12345678-1234-1234-1234-123456789012&auth_token=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
  ```
</CodeGroup>

***

### Authorize your workspace

In a web browser, go to the URL that the Connect Webview object returned.

For application developers, you can redirect your user to this Connect Webview URL so that they can authorize your app to control their devices using Seam. We even provide a prebuilt [Connect Account Button](/ui-components/overview/react-components/connect-account-button) within our suite of [Seam Components](/ui-components/overview) that help you build your device management flow.

<Check>
  Because you're using a sandbox workspace, you can connect Seam's test
  SmartThings account. We provide [virtual devices](./smartthings-sample-data)
  for each of the brands that we support. These sandbox devices and systems
  enable you to test your app with devices from multiple brands without the need
  to own all the corresponding physical devices.
</Check>

Complete the Connect Webview authorization flow by entering the following [SmartThings sandbox account](./smartthings-sample-data) credentials:

* **Email:** [jane@example.com](mailto:jane@example.com)
* **Password:** 1234

Confirm that authorization through the Connect Webview was successful by querying its status.

**Code:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  const updatedConnectWebview = await seam.connectWebviews.get({
    connect_webview_id: connectWebview.connect_webview_id,
  })

  console.log(updatedConnectWebview.login_successful) // true
  ```

  ```bash cURL theme={null}
  curl -X 'GET' \
    'https://connect.getseam.com/connect_webviews/get' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d "{
    \"connect_webview_id\": \"${connect_webview_id}\"
  }" | jq -r '"Login Successful (true): " + (.connect_webview.login_successful | tostring)'
  ```

  ```python Python theme={null}
  updated_connect_webview = seam.connect_webviews.get(connect_webview.connect_webview_id)

  assert updated_connect_webview.login_successful is True # True
  ```

  ```ruby Ruby theme={null}
  updated_connect_webview = seam.connect_webviews.get(
    connect_webview_id: connect_webview.connect_webview_id
  )

  puts updated_connect_webview.login_successful # true
  ```

  ```php PHP theme={null}
  $updated_connect_webview = $seam->connect_webviews->get(
    connect_webview_id: $connect_webview->connect_webview_id
  );

  echo $updated_connect_webview->login_successful ? 'true' : 'false', "\n"; // true
  ```

  ```csharp C# theme={null}
  var updatedConnectWebview = seam.ConnectWebviews.Get(
    connectWebviewId: connectWebview.connectWebviewId
  );

  Console.WriteLine(updatedConnectWebview.LoginSuccessful); // True
  ```
</CodeGroup>

**Output:**

<CodeGroup>
  ```json JavaScript theme={null}
  true
  ```

  ```json cURL theme={null}
  Login Successful (true): true
  ```

  ```json Python theme={null}
  True
  ```

  ```json Ruby theme={null}
  true
  ```

  ```json PHP theme={null}
  true
  ```

  ```json C# theme={null}
  True
  ```
</CodeGroup>

***

## Step 3: Retrieve SmartThings-connected lock devices

When you link an SmartThings account with Seam, we create a `device` object to represent each SmartThings-connected lock in your account. You can then retrieve these SmartThings devices using the [List Devices](/api/devices/list) and [Get Device](/api/devices/get) endpoints.

The Seam API exposes each device's properties, such as the door lock status, power status, capabilities, and so on.

**Code:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  // Retrieve all devices, filtered by manufacturer,
  // which is one of several filters that list() supports.
  const allSmartThingsLocks = await seam.devices.list({
    manufacturer: 'smartthings',
  })

  // Select the first device as an example.
  const frontDoor = allSmartThingsLocks[0]

  // Inspect specific properties.
  console.log(frontDoor.properties.online) // true
  console.log(frontDoor.properties.locked) // true

  // View the entire returned device object.
  console.log(frontDoor)
  ```

  ```bash cURL theme={null}
  # Retrieve all devices, filtered by manufacturer, which is
  # one of several filters that the list endpoint supports.
  all_smartthings_locks=$(
    # Use GET or POST.
    curl -X 'GET' \
      'https://connect.getseam.com/devices/list' \
      -H 'accept: application/json' \
      -H "Authorization: Bearer ${SEAM_API_KEY}" \
      -H 'Content-Type: application/json' \
      -d '{
      "manufacturer": "smartthings"
    }')

  # Select the first device as an example.
  front_door=$(jq -r '.devices[0]' <<< ${all_smartthings_locks})

  # Inspect specific properties.
  echo $(jq -r '"Online (true): " + (.properties.online | tostring)' <<< ${front_door})
  echo $(jq -r '"Locked (true): " + (.properties.locked | tostring)' <<< ${front_door})

  # View the entire returned device object.
  echo ${front_door}
  ```

  ```python Python theme={null}
  # Retrieve all devices, filtered by manufacturer,
  # which is one of several filters that list() supports.
  all_smartthings_locks = seam.devices.list(manufacturer="smartthings")

  # Select the first device as an example.
  front_door = all_smartthings_locks[0]

  # Inspect specific properties.
  assert front_door.properties["online"] is True # True
  assert front_door.properties["locked"] is True # True

  # View the entire returned device object.
  pprint(front_door)
  ```

  ```ruby Ruby theme={null}
  # Retrieve all devices, filtered by manufacturer,
  # which is one of several filters that list() supports.
  all_smartthings_locks = seam.devices.list(manufacturer: "smartthings")

  # Select the first device as an example.
  front_door = all_smartthings_locks[0]

  # Inspect specific properties.
  puts front_door.properties.online # true
  puts front_door.properties.locked # true

  # View the entire returned device object.
  puts front_door.inspect
  ```

  ```php PHP theme={null}
  // Retrieve all devices, filtered by manufacturer,
  // which is one of several filters that list() supports.
  $all_smartthings_locks = $seam->devices->list(manufacturer: "smartthings");

  // Select the first device as an example.
  $front_door = $all_smartthings_locks[0];

  // Inspect specific properties.
  echo $front_door->properties->online ? 'true' : 'false', "\n"; // true
  echo $front_door->properties->locked ? 'true' : 'false', "\n"; // true

  // View the entire returned device object.
  echo json_encode($front_door, JSON_PRETTY_PRINT);
  ```

  ```csharp C# theme={null}
  // Retrieve all devices, filtered by manufacturer,
  // which is one of several filters that list() supports.
  var allSmartThingsLocks = seam.Devices.List(
    manufacturer: Seam.Api.Devices.ListRequest.ManufacturerEnum.Smartthings
  );

  // Select the first device as an example.
  Device frontDoor = allSmartThingsLocks[0];

  // Inspect specific properties.
  Console.WriteLine(frontDoor.Properties.Online); // true
  Console.WriteLine(frontDoor.Properties.Locked); // true

  // View the entire returned device object.
  Console.WriteLine(frontDoor);
  ```
</CodeGroup>

**Output:**

<CodeGroup>
  ```json JavaScript theme={null}
  true
  true
  {
    device_id: '11111111-1111-1111-1111-444444444444',
    display_name: 'Lock 1',
    workspace_id: '00000000-0000-0000-0000-000000000000',
    connected_account_id: '11111111-1111-1111-1111-222222222222',
    created_at: '2024-05-29T20:08:48.878Z',
    properties: {
      manufacturer: 'smartthings',
      online: true,
      locked: true,
      battery: {
        level: 0.9999532347993827,
        status: 'full'
      },
      ...
    },
    can_remotely_unlock: true,
    ...
  }
  ```

  ```json cURL theme={null}
  Online (true): true
  Locked (true): true
  {
    "device_id": "11111111-1111-1111-1111-444444444444",
    "display_name": "Lock 1",
    "workspace_id": "00000000-0000-0000-0000-000000000000",
    "connected_account_id": "11111111-1111-1111-1111-222222222222",
    "created_at": "2024-05-29T20:08:48.878Z",
    "properties": {
      "manufacturer": "smartthings",
      "locked": true,
      "online": true,
      "battery": {
        "level": 0.9999532347993827,
        "status": "full"
      },
      ...
    },
    "can_remotely_unlock": true,
    ...
  }
  ```

  ```json Python theme={null}
  Device(
    device_id='11111111-1111-1111-1111-444444444444',
    display_name='Lock 1',
    workspace_id='00000000-0000-0000-0000-000000000000'
    connected_account_id='11111111-1111-1111-1111-222222222222',
    created_at='2024-05-29T20:08:48.878Z',
    properties={
      'manufacturer': 'smartthings',
      'online': True,
      'locked': True,
      'battery': {
        'level': 0.9999532347993827,
        'status': 'full'
      },
      ...
    }
    can_remotely_unlock=True,
    ...
  )
  ```

  ```json Ruby theme={null}
  true
  true
  <
    Seam::Device:0x00438
      device_id="11111111-1111-1111-1111-444444444444"
      display_name="Lock 1"
      workspace_id="00000000-0000-0000-0000-000000000000"
      connected_account_id="11111111-1111-1111-1111-222222222222"
      created_at=2024-05-29 20:08:48.878 UTC
      properties={
        "manufacturer"=>"smartthings",
        "online"=>true,
        "locked"=>true,
        "battery"=>{
          "level"=>0.9999532347993827,
          "status"=>"full"
        },
        ...
      }
      can_remotely_unlock=true
      ...
  >
  ```

  ```json PHP theme={null}
  true
  true
  {
    "device_id": "11111111-1111-1111-1111-444444444444",
    "display_name": "Lock 1",
    "workspace_id": "00000000-0000-0000-0000-000000000000"
    "connected_account_id": "11111111-1111-1111-1111-222222222222",
    "created_at": "2024-05-29T20:08:48.878Z",
    "properties": {
      "manufacturer": "smartthings",
      "online": true,
      "locked": true,
      "battery": {
        "level": 0.9999532347993827,
        "status": "full"
      },
      ...
    },
    "can_remotely_unlock": true,
    ...
  }
  ```

  ```json C# theme={null}
  True
  True
  {
    "device_id": "11111111-1111-1111-1111-444444444444",
    "display_name": "Lock 1",
    "workspace_id": "00000000-0000-0000-0000-000000000000",
    "connected_account_id": "11111111-1111-1111-1111-222222222222",
    "created_at": "2024-05-29T20:08:48.878Z",
    "properties": {
      "manufacturer": "smartthings",
      "online": true,
      "locked": true,
      "battery": {
        "level": 0.9999532,
        "status": "full"
      },
      ...
    },
    "can_remotely_unlock": true,
    ...
  }
  ```
</CodeGroup>

***

## Step 4: Control your SmartThings-connected lock

Next, you can use the Seam API to control your lock.

Each device that you connect to Seam has a specific set of capabilities. These capabilities define the Seam API actions that you can use, such as [remote unlock actions](/low-level-apis/smart-locks/lock-and-unlock), [programming access codes](/low-level-apis/smart-locks/access-codes), and so on. Seam's intuitive and granular [capability flags](/capability-guides/device-and-system-capabilities#capability-flags) inform your application about what features and behaviors each device supports. Notice the capability flags within the code samples in this guide.

Try out the following actions on your SmartThings-connected lock:

* [ ] [Unlock your lock](#unlock-your-lock)
* [ ] [Program access codes on your lock](#program-access-codes-on-your-lock)

### Unlock your lock

To unlock a door, use the [Unlock Door](/api/locks/unlock_door) endpoint. Specify the device that you want to unlock by including the `device_id` in the request body. This endpoint returns an [action attempt](/core-concepts/action-attempts) to track the progress of the unlock operation.

**Code:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  // Confirm that the device can remotely unlock.
  // You're using a capability flag here!
  if (frontDoor.can_remotely_unlock) {
    // Perform the unlock operation
    // and return an action attempt.
    const actionAttempt = await seam.locks.unlockDoor({
      device_id: frontDoor.device_id,
    })
  }
  ```

  ```bash cURL theme={null}
  # Confirm that the device can remotely unlock.
  # You're using a capability flag here!
  if  $(jq -r '.can_remotely_lock' <<< ${front_door}); then \
    # Perform the unlock operation
    # and return an action attempt.
    curl -X 'POST' \
      'https://connect.getseam.com/locks/unlock_door' \
      -H 'accept: application/json' \
      -H "Authorization: Bearer ${SEAM_API_KEY}" \
      -H 'Content-Type: application/json' \
      -d "{
        \"device_id\": \"$(jq -r '.device_id' <<< ${front_door})\"
    }";
  fi
  ```

  ```python Python theme={null}
  # Confirm that the device can remotely unlock.
  # You're using a capability flag here!
  if front_door.can_remotely_unlock:
    # Perform the unlock operation
    # and return an action attempt.
    action_attempt=seam.locks.unlock_door(device_id=front_door.device_id)
  ```

  ```ruby Ruby theme={null}
  # Confirm that the device can remotely unlock.
  # You're using a capability flag here!
  if (front_door.can_remotely_unlock)
    # Perform the unlock operation
    # and return an action attempt.
    action_attempt = seam.locks.unlock_door(device_id: front_door.device_id)
  end
  ```

  ```php PHP theme={null}
  // Confirm that the device can remotely unlock.
  // You're using a capability flag here!
  if ($front_door->can_remotely_unlock) {
    // Perform the unlock operation
    // and return an action attempt.
    $action_attempt = $seam->locks->unlock_door(device_id: $front_door->device_id);
  }
  ```

  ```csharp C# theme={null}
  // Confirm that the device can remotely unlock.
  // You're using a capability flag here!
  if (frontDoor.CanRemotelyUnlock == true) {
    // Perform the unlock operation
    // and return an action attempt.
    ActionAttempt actionAttempt = seam.Locks.UnlockDoor(deviceId: frontDoor.DeviceId);
  }
  ```
</CodeGroup>

**Output:**

<CodeGroup>
  ```json JavaScript theme={null}
  {
    "actionAttempt": {
      "status": "success",
      "action_attempt_id": "11111111-2222-3333-4444-555555555555",
      "action_type": "UNLOCK_DOOR",
      "result": {},
      "error": null
    }
  }
  ```

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

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

  ```json Ruby theme={null}
  <Seam::ActionAttempt:0x00438
    status="pending"
    action_type="UNLOCK_DOOR"
    action_attempt_id="11111111-2222-3333-4444-555555555555"
    result=nil>
  ```

  ```json PHP theme={null}
  {
    "action_attempt_id": "11111111-2222-3333-4444-555555555555",
    "action_type": "UNLOCK_DOOR",
    "error": null,
    "result": {},
    "status": "success"
  }
  ```

  ```json C# theme={null}
  {
    "status": "pending",
    "action_type": "UNLOCK_DOOR",
    "action_attempt_id": "11111111-2222-3333-4444-555555555555"
  }
  ```
</CodeGroup>

You can track the status of the unlock operation to confirm that the device unlocked successfully. Query the `locked` status of the device, [retrieve the action attempt](/api/action_attempts/get) by ID, or look for a [`lock.unlocked` event](/api/locks/events#lock-unlocked).

To query the `locked` status of the device:

**Code:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  // Get the device by ID.
  const updatedFrontDoor = await seam.devices.get({device_id: frontDoor.device_id});

  // Inspect the locked property to confirm
  // that the unlock operation was successful.
  console.log(updatedFrontDoor.properties.locked) // false
  ```

  ```bash cURL theme={null}
  # Get the device by ID.
  updated_front_door=$(
    # Use GET or POST.
    curl -X 'GET' \
      'https://connect.getseam.com/devices/get' \
      -H 'accept: application/json' \
      -H "Authorization: Bearer ${SEAM_API_KEY}" \
      -H 'Content-Type: application/json' \
      -d "{
        \"device_id\": \"$(jq -r '.device_id' <<< ${front_door})\"
    }")

  # Inspect the locked property to confirm
  # that the unlock operation was successful.
  echo $(jq -r '"Locked (false): " + (.device.properties.locked | tostring)' <<< ${updated_front_door})
  ```

  ```python Python theme={null}
  # Get the device by ID.
  updated_front_door = seam.devices.get(device_id=front_door.device_id)

  # Inspect the locked property to confirm
  # that the unlock operation was successful.
  assert updated_front_door.properties["locked"] is False # False
  ```

  ```ruby Ruby theme={null}
  # Get the device by ID.
  updated_front_door = seam.devices.get(device_id: front_door.device_id)

  # Inspect the locked property to confirm
  # that the unlock operation was successful.
  puts updated_front_door.properties.locked # false
  ```

  ```php PHP theme={null}
  // Get the device by ID.
  $updated_front_door = $seam->devices->get(device_id: $front_door->device_id);

  // Inspect the locked property to confirm
  // that the unlock operation was successful.
  echo $updated_front_door->properties->locked ? 'true' : 'false', "\n"; // false
  ```

  ```csharp C# theme={null}
  // Get the device by ID.
  Device updatedFrontDoor = seam.Devices.Get(
    deviceId: frontDoor.DeviceId
  );

  // Inspect the locked property to confirm
  // that the unlock operation was successful.
  Console.WriteLine(updatedFrontDoor.Properties.Locked); // false
  ```
</CodeGroup>

**Output:**

<CodeGroup>
  ```json JavaScript theme={null}
  false
  ```

  ```json cURL theme={null}
  Locked (false): false
  ```

  ```json Python theme={null}
  False
  ```

  ```json Ruby theme={null}
  false
  ```

  ```json PHP theme={null}
  false
  ```

  ```json C# theme={null}
  False
  ```
</CodeGroup>

<Check>
  Now that you have successfully unlocked your lock, you can use the [Lock
  Door](/api/locks/lock_door) endpoint to lock it
  again.
</Check>

***

### Program access codes on your lock

You can use the Seam API to program [online access codes](/low-level-apis/smart-locks/access-codes) on SmartThings-connected locks that have an integrated or accessory keypad. Lock users can then enter these access codes using the keypad to unlock the lock.

The Seam API makes it easy to program both [ongoing](/low-level-apis/smart-locks/access-codes#ongoing-access-codes) and [time-bound](/low-level-apis/smart-locks/access-codes#time-bound-access-codes) online access codes.

**Code:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  // Confirm that the device supports online access codes.
  // Here's another capability flag!
  if (updatedFrontDoor.can_program_online_access_codes) {
    // Create an ongoing online access code.
    await seam.accessCodes.create({
      device_id: updatedFrontDoor.device_id,
      name: 'my ongoing code',
      code: '1234',
    })
    // Create a time-bound online access code.
    await seam.accessCodes.create({
      device_id: updatedFrontDoor.device_id,
      name: 'my time-bound code',
      starts_at: '2025-01-01T16:00:00Z',
      ends_at: '2025-01-22T12:00:00Z',
      code: '2345',
    })
    // List all access codes for this device.
    const accessCodes = await seam.accessCodes.list({
      device_id: updatedFrontDoor.device_id,
    })
    console.log(accessCodes)
  }
  ```

  ```bash cURL theme={null}
  # Confirm that the device supports online access codes.
  # Here's another capability flag!
  if  $(jq -r '.device.can_program_online_access_codes' <<< ${updated_front_door}); then \
    # Create an ongoing online access code.
    curl -X 'POST' \
      'https://connect.getseam.com/access_codes/create' \
      -H 'accept: application/json' \
      -H "Authorization: Bearer ${SEAM_API_KEY}" \
      -H 'Content-Type: application/json' \
      -d "{
        \"device_id\": \"$(jq -r '.device.device_id' <<< ${updated_front_door})\",
        \"name\": \"my ongoing code\",
        \"code\": \"1234\"
    }"
    # Create a time-bound online access code.
    curl -X 'POST' \
      'https://connect.getseam.com/access_codes/create' \
      -H 'accept: application/json' \
      -H "Authorization: Bearer ${SEAM_API_KEY}" \
      -H 'Content-Type: application/json' \
      -d "{
        \"device_id\": \"$(jq -r '.device.device_id' <<< ${updated_front_door})\",
        \"name\": \"my time-bound code\",
        \"starts_at\": \"2025-01-01T16:00:00Z\",
        \"ends_at\": \"2025-01-22T12:00:00Z\",
        \"code\": \"2345\"
    }"
    # List all access codes for this device.
    access_codes=$(
    # Use GET or POST.
    curl -X 'GET' \
      'https://connect.getseam.com/access_codes/list' \
      -H 'accept: application/json' \
      -H "Authorization: Bearer ${SEAM_API_KEY}" \
      -H 'Content-Type: application/json' \
      -d "{
        \"device_id\": \"$(jq -r '.device.device_id' <<< ${updated_front_door})\"
    }")
    echo ${access_codes};
  fi
  ```

  ```python Python theme={null}
  # Confirm that the device supports online access codes.
  # Here's another capability flag!
  if updated_front_door.can_program_online_access_codes:
    # Create an ongoing online access code.
    seam.access_codes.create(
      device_id = updated_front_door.device_id,
      name = "my ongoing code",
      code = "1234"
    )
    # Create a time-bound online access code.
    seam.access_codes.create(
      device_id = updated_front_door.device_id,
      name = "my time-bound code",
      starts_at = "2025-01-01T16:00:00Z",
      ends_at = "2025-01-22T12:00:00Z",
      code = "2345"
    )
    # List all access codes for this device.
    access_codes = seam.access_codes.list(
      device_id = updated_front_door.device_id
    )
    pprint(access_codes)
  ```

  ```ruby Ruby theme={null}
  # Confirm that the device supports online access codes.
  # Here's another capability flag!
  if (updated_front_door.can_program_online_access_codes)
    # Create an ongoing online access code.
    seam.access_codes.create(
      device_id: updated_front_door.device_id,
      name: "my ongoing code",
      code: "1234"
    )
    # Create a time-bound online access code.
    seam.access_codes.create(
      device_id: updated_front_door.device_id,
      name: "my time-bound code",
      starts_at: "2025-01-01T16:00:00Z",
      ends_at: "2025-01-22T12:00:00Z",
      code: "2345"
    )
    # List all access codes for this device.
    access_codes = seam.access_codes.list(
      device_id: updated_front_door.device_id
    )
    puts access_codes.inspect
  end
  ```

  ```php PHP theme={null}
  // Confirm that the device supports online access codes.
  // Here's another capability flag!
  if ($updated_front_door->can_program_online_access_codes) {
    // Create an ongoing online access code.
    $seam->access_codes->create(
      device_id: $updated_front_door->device_id,
      name: "my ongoing code",
      code: "1234"
    );
    // Create a time-bound online access code.
    $seam->access_codes->create(
      device_id: $updated_front_door->device_id,
      name: "my time-bound code",
      starts_at:  "2025-01-01T16:00:00Z",
      ends_at: "2025-01-22T12:00:00Z",
      code: "2345"
    );
    // List all access codes for this device.
    $access_codes = $seam->access_codes->list(
      device_id: $updated_front_door->device_id
    );
    echo json_encode($access_codes, JSON_PRETTY_PRINT);
  }
  ```

  ```csharp C# theme={null}
  // Confirm that the device supports online access codes.
  // Here's another capability flag!
  if (updatedFrontDoor.CanProgramOnlineAccessCodes == true) {
    // Create an ongoing online access code.
    seam.AccessCodes.Create(
      deviceId: updatedFrontDoor.DeviceId,
      name: "my ongoing code",
      code: "1234"
    );
    // Create a time-bound online access code.
    seam.AccessCodes.Create(
      deviceId: updatedFrontDoor.DeviceId,
      name: "my time-bound code",
      startsAt: "2025-01-01T16:00:00Z",
      endsAt: "2025-01-22T12:00:00Z",
      code: "2345"
    );
    // List all access codes for this device.
    var accessCodes = seam.AccessCodes.List(
      deviceId: updatedFrontDoor.DeviceId
    );
    foreach (var accessCode in accessCodes)
    {
      Console.WriteLine(accessCode);
    }
  }
  ```
</CodeGroup>

**Output:**

<CodeGroup>
  ```json JavaScript theme={null}
  [
    {
      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-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',
      ...
    }
  ]
  ```

  ```json cURL theme={null}
  {
    "access_codes": [
      {
        "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-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
  }
  ```

  ```json Python theme={null}
  [
    AccessCode(
      access_code_id='11111111-1111-1111-1111-555555555555',
      device_id='11111111-1111-1111-1111-444444444444',
      type='ongoing',
      code='1234',
      name='my ongoing code',
      ...
    )
    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',
      ...
    )
  ]
  ```

  ```json Ruby theme={null}
  [
    <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"
      ...
    >,
    <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
      ...
    >
  ]
  ```

  ```json PHP theme={null}
  [
    {
      "access_code_id": "11111111-1111-1111-1111-555555555555",
      "device_id": "11111111-1111-1111-1111-444444444444",
      "name": "my ongoing code",
      "type": "ongoing",
      "code": "1234",
      ...
    },
    {
      "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",
    }
  ]
  ```

  ```json C# theme={null}
  {
    "type": "ongoing",
    "access_code_id": "11111111-1111-1111-1111-555555555555",
    "device_id": "11111111-1111-1111-1111-444444444444",
    "name": "my ongoing code",
    "code": "1234",
    ...
  }
  {
    "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",
    ...
  }
  ```
</CodeGroup>

***

## Step 5: Connect a real SmartThings-connected lock

Now that you have learned the basics of using the Seam API, you can connect and control a real SmartThings-connected device. To do so, make sure to switch to a [non-sandbox workspace](/core-concepts/workspaces#production-workspaces) and [API key](/core-concepts/authentication/api-keys).

For more details about setting up your real SmartThings-connected lock, see the [SmartThings Hubs + devices integration guide](./).

***

## Step 6: Build your application!

Seam makes it easy to develop your application. In addition to the robust Seam API and the wide variety of programming languages that our SDKs support, we also provide a suite of [Seam Components](/ui-components/overview). These prebuilt UI components help you to build your device management flow.

For example, you can use the [Device Table Seam Component](/ui-components/overview/react-components/device-table) to display a list of devices and to identify all devices with issues. You can use the [Device Details Seam Component](/ui-components/overview/react-components/device-details) to display a device's properties, settings, and issues, as well as to enable your users to perform actions based on each device's capabilities. The [Access Code Details Seam Component](/ui-components/overview/react-components/access-code-details) provides a similar display and actions for access codes.

Seam Components use a responsive design to fit seamlessly on any screen size. They also provide device debugging flows to help your users.

To learn about all the Seam Components that we provide, see [Seam Components](/ui-components/overview).

***

## Next steps

Now that you've completed this getting started guide for SmartThings-connected devices, you can learn more about what you can do with the Seam API.

* [ ] **Explore**\
  See the [other devices and system integrations](/device-and-system-integration-guides) that Seam supports.
* [ ] **Learn**\
  Read about Seam [concepts](/core-concepts/overview) and the [device and system capabilities ](/capability-guides/device-and-system-capabilities)that Seam supports.
* [ ] **Use Seam Components**\
  Find out about [Seam Components](/ui-components/overview), which are prebuilt UI components for building your device management flow.
* [ ] **Use webhooks**\
  Learn how to use [webhooks](/developer-tools/webhooks) as an efficient way to receive device events.
* [ ] **Find out more**\
  Explore the other types of devices and systems that you can control with Seam, including [access control systems](/low-level-apis/access-systems), [thermostats](/capability-guides/thermostats), and [noise sensors](/capability-guides/noise-sensors).
* [ ] **Develop for mobile access**\
  Learn about Seam's [mobile access solution](/capability-guides/mobile-access).

<Info>
  If you have any questions or want to report an issue, email us at
  [support@seam.co](mailto:support@seam.co).
</Info>

***

## Quick links

<CardGroup>
  <Card title="Get an API Key (free)" href="https://console.seam.co/">
    Sign up for the Seam Console and get your API keys. →
  </Card>

  <Card title="Contact Sales" href="https://www.seam.co/contact-us">
    Got a project or a specific question? Contact our team to get answers. →
  </Card>
</CardGroup>


# Get Started with SmartThings Hubs + Thermostats
Source: https://docs.seam.co/device-and-system-integration-guides/smartthings-hubs-+-devices/get-started-with-smartthings-hubs-+-thermostats

Learn how to connect and control SmartThings-connected thermostats with the Seam API.

## Overview

Seam provides a universal API to connect and control many brands of IoT devices and systems, including thermostats, smart locks, access control systems (ACSs), and noise sensors.

This guide gives you a rapid introduction to connecting and controlling your [SmartThings](https://www.seam.co/manufacturers/smartthings)-connected thermostats using the Seam API. For application developers, you can use the Seam API in your app, and your users can authorize your app to control their devices using Seam.

You connect your thermostats to Seam through a SmartThings Hub. These hubs use Zigbee or Z-Wave to communicate with your thermostats. SmartThings Hubs are connected to your local network using Wi-Fi or Ethernet. For detailed information about the SmatThings Hubs that Seam supports, see our [SmartThings Supported Devices page](https://www.seam.co/manufacturers/smartthings).

To learn more about other IoT device and system brands that Seam supports—such as ecobee, Honeywell Resideo, Google Nest, Yale, Schlage, and many more—visit our [integration page](https://www.seam.co/supported-devices-and-systems).

<Check>
  This guide shows you how to install a Seam SDK and then control your SmartThings-connected thermostat using the Seam API.

  Another easy way to learn about what you can do with the Seam API is to explore the [interactive Seam CLI](/core-concepts/seam-console/seam-online-cli), which you can access from directly within the [Seam Console](/core-concepts/seam-console).

  :arrow\_forward: [Go to the Seam Console!](https://console.seam.co/)
</Check>

***

## Step 1: Install a Seam SDK

Seam provides client libraries for many languages, including JavaScript, Python, Ruby, PHP, and others, as well as a Postman collection and an [OpenAPI](https://connect.getseam.com/openapi.json) spec.

* JavaScript / TypeScript ([npm](https://www.npmjs.com/package/seam), [GitHub](https://github.com/seamapi/javascript))
* Python ([pip](https://pypi.org/project/seam/), [GitHub](https://github.com/seamapi/python))
* Ruby Gem ([rubygem](https://rubygems.org/gems/seam), [GitHub](https://github.com/seamapi/ruby))
* PHP ([packagist](https://packagist.org/packages/seamapi/seam), [GitHub](https://github.com/seamapi/php))
* C# ([nuget](https://www.nuget.org/packages/Seam), [GitHub](https://github.com/seamapi/csharp))

First, install a Seam SDK, as follows:

<Tabs>
  <Tab title="JavaScript">
    ```bash theme={null}
    npm i seam
    ```
  </Tab>

  <Tab title="Python">
    ```bash theme={null}
    pip install seam
    # For some development environments, use pip3 in this command instead of pip.
    ```
  </Tab>

  <Tab title="Ruby">
    ```bash theme={null}
    bundle add seam
    ```
  </Tab>

  <Tab title="PHP">
    ```bash theme={null}
    composer require seamapi/seam
    ```
  </Tab>

  <Tab title="C#">
    Install using [nuget](https://www.nuget.org/packages/Seam).
  </Tab>
</Tabs>

Next, go to [https://console.seam.co/](https://console.seam.co/) and [sign up for Seam](/core-concepts/seam-console#create-a-seam-account) to get your [API key](/core-concepts/authentication/api-keys).

Then, export your API key as an environment variable.

```bash theme={null}
$ export SEAM_API_KEY=seam_test2bMS_94SrGUXuNR2JmJkjtvBQDg5c
```

<Info>
  This guide uses a [sandbox
  workspace](/core-concepts/workspaces#sandbox-workspaces).
  You can only connect virtual devices and systems in this type of workspace. If
  you want to connect a real SmartThings-connected thermostat, use a
  [non-sandbox
  workspace](/core-concepts/workspaces#production-workspaces)
  and API key.
</Info>

***

## Step 2: Link your SmartThings account with Seam

To control your SmartThings-connected thermostat using the Seam API, you must first authorize your Seam workspace to connect to your SmartThings account. If your application needs to connect to your users' SmartThings accounts, Seam provides fully-embedded, [customizable](/core-concepts/connect-webviews/customizing-connect-webviews) client-side [Connect Webviews](/core-concepts/connect-webviews) to collect their authorization securely. These user-friendly pre-built authorization flows walk your users through the process of granting your Seam workspace permission to control their SmartThings-connected thermostats. The Connect Webview presents a flow that prompts your users to enter their credentials for their SmartThings account.

In this guide, you create a Connect Webview object. Then, you display the graphical component of the created Connect Webview and enter a set of sample credentials to connect a sandbox SmartThings account.

<Check>
  This guide shows you how to create a Connect Webview programmatically using the Seam API.

  The [Seam Console](/core-concepts/seam-console) provides another easy way to connect devices to your Seam workspace.

  Go to [https://console.seam.co/](https://console.seam.co/). On the **Devices** page, click **+ Add Devices**. Then, see [Authorize your workspace](#authorize-your-workspace) in this guide to complete the Connect Webview authorization flow.
</Check>

### Create a Connect Webview

Create a `connect_webview` object and then note the returned URL.

**Code:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  import { Seam } from 'seam'

  const seam = new Seam() // Seam automatically uses your exported SEAM_API_KEY.

  const connectWebview = await seam.connectWebviews.create({
    accepted_capabilities: ['thermostat'],
  })

  console.log(connectWebview.login_successful) // false

  // Use the returned Connect Webview URL to display
  // the Connect Webview authorization flow to your user.
  console.log(connectWebview.url)
  ```

  ```bash cURL theme={null}
  curl -X 'POST' \
    'https://connect.getseam.com/connect_webviews/create' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d '{
    "accepted_capabilities": ["thermostat"]
  }' | jq -r '"Login Successful (false): " + (.connect_webview.login_successful | tostring),
    "URL: " + .connect_webview.url'
    # Use the returned Connect Webview URL to display
    # the Connect Webview authorization flow to your user.
  ```

  ```python Python theme={null}
  from seam import Seam

  seam = Seam()  # Seam automatically uses your exported SEAM_API_KEY.

  connect_webview = seam.connect_webviews.create(
    accepted_capabilities=["thermostat"]
  )

  assert connect_webview.login_successful is False

  # Use the returned Connect Webview URL to display
  # the Connect Webview authorization flow to your user.
  print(connect_webview.url)
  ```

  ```ruby Ruby theme={null}
  require "seam"

  seam = Seam.new() # Seam automatically uses your exported SEAM_API_KEY.

  connect_webview = seam.connect_webviews.create(
    accepted_capabilities: ["thermostat"]
  )

  puts connect_webview.login_successful # false

  # Use the returned Connect Webview URL to display
  # the Connect Webview authorization flow to your user.
  puts connect_webview.url
  ```

  ```php PHP theme={null}
  <?php
  require 'vendor/autoload.php';

  $seam = new Seam\SeamClient(); // Seam automatically uses your exported SEAM_API_KEY.

  $connect_webview = $seam->connect_webviews->create(
    accepted_capabilities: ["thermostat"]
  );

  echo $connect_webview->login_successful ? 'true' : 'false', "\n"; // false

  // Use the returned Connect Webview URL to display
  // the Connect Webview authorization flow to your user.
  echo $connect_webview->url;
  ```

  ```csharp C# theme={null}
  using Seam.Client;

  var seam = new SeamClient(apiToken: SEAM_API_KEY);

  var connectWebview = seam.ConnectWebviews.Create(
    acceptedCapabilities: new() {Seam.Api.ConnectWebviews.CreateRequest.AcceptedCapabilitiesEnum.Thermostat}
  );

  Console.WriteLine(connectWebview.LoginSuccessful); // False

  // Use the returned Connect Webview URL to display
  // the Connect Webview authorization flow to your user.
  Console.WriteLine(connectWebview.Url);
  ```
</CodeGroup>

**Output:**

<CodeGroup>
  ```json JavaScript theme={null}
  false
  https://connect.getseam.com/connect_webviews/view?connect_webview_id=12345678-1234-1234-1234-123456789012&auth_token=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
  ```

  ```json cURL theme={null}
  Login Successful (false): false
  https://connect.getseam.com/connect_webviews/view?connect_webview_id=12345678-1234-1234-1234-123456789012&auth_token=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
  ```

  ```json Python theme={null}
  https://connect.getseam.com/connect_webviews/view?connect_webview_id=12345678-1234-1234-1234-123456789012&auth_token=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
  ```

  ```json Ruby theme={null}
  false
  https://connect.getseam.com/connect_webviews/view?connect_webview_id=12345678-1234-1234-1234-123456789012&auth_token=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
  ```

  ```json PHP theme={null}
  false
  https://connect.getseam.com/connect_webviews/view?connect_webview_id=12345678-1234-1234-1234-123456789012&auth_token=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
  ```

  ```json C# theme={null}
  False
  https://connect.getseam.com/connect_webviews/view?connect_webview_id=12345678-1234-1234-1234-123456789012&auth_token=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
  ```
</CodeGroup>

***

### Authorize Your Workspace

In a web browser, go to the URL that the Connect Webview object returned.

For application developers, you can redirect your user to this Connect Webview URL so that they can authorize your app to control their devices using Seam. We even provide a prebuilt [Connect Account Button](/ui-components/overview/react-components/connect-account-button) within our suite of [Seam Components](/ui-components/overview) that help you build your device management flow.

<Check>
  Because you're using a sandbox workspace, you can connect Seam's test
  SmartThings account. We provide [virtual devices](./smartthings-sample-data)
  for each of the brands that we support. These sandbox devices and systems
  enable you to test your app with devices from multiple brands without the need
  to own all the corresponding physical devices.
</Check>

Complete the Connect Webview authorization flow by entering the following [SmartThings sandbox account](./smartthings-sample-data) credentials:

* **Email:** [jane@example.com](mailto:jane@example.com)
* **Password:** 1234

Confirm that authorization through the Connect Webview was successful by querying its status.

**Code:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  const updatedConnectWebview = await seam.connectWebviews.get({
    connect_webview_id: connectWebview.connect_webview_id,
  })

  console.log(updatedConnectWebview.login_successful) // true
  ```

  ```bash cURL theme={null}
  curl -X 'GET' \
    'https://connect.getseam.com/connect_webviews/get' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d "{
    \"connect_webview_id\": \"${connect_webview_id}\"
  }" | jq -r '"Login Successful (true): " + (.connect_webview.login_successful | tostring)'
  ```

  ```python Python theme={null}
  updated_connect_webview = seam.connect_webviews.get(connect_webview.connect_webview_id)

  assert updated_connect_webview.login_successful is True # True
  ```

  ```ruby Ruby theme={null}
  updated_connect_webview = seam.connect_webviews.get(
    connect_webview_id: connect_webview.connect_webview_id
  )

  puts updated_connect_webview.login_successful # true
  ```

  ```php PHP theme={null}
  $updated_connect_webview = $seam->connect_webviews->get(
    connect_webview_id: $connect_webview->connect_webview_id
  );

  echo $updated_connect_webview->login_successful ? 'true' : 'false', "\n"; // true
  ```

  ```csharp C# theme={null}
  var updatedConnectWebview = seam.ConnectWebviews.Get(
    connectWebviewId: connectWebview.connectWebviewId
  );

  Console.WriteLine(updatedConnectWebview.LoginSuccessful); // True
  ```
</CodeGroup>

**Output:**

<CodeGroup>
  ```json JavaScript theme={null}
  true
  ```

  ```json cURL theme={null}
  Login Successful (true): true
  ```

  ```json Python theme={null}
  True
  ```

  ```json Ruby theme={null}
  true
  ```

  ```json PHP theme={null}
  true
  ```

  ```json C# theme={null}
  True
  ```
</CodeGroup>

***

## Step 3: Retrieve SmartThings-connected thermostat devices

When you link a SmartThings account with Seam, we create a `device` object to represent each SmartThings-connected thermostat in your account. You can then retrieve these SmartThings devices using the [List Devices](/api/devices/list) and [Get Device](/api/devices/get) endpoints.

The Seam API exposes each device's properties, such as the current temperature reading in Fahrenheit and Celsius, current HVAC and fan modes, available climate presets, thermostat-specific constraints, and much more.

**Code:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  // Retrieve all devices, filtered by manufacturer,
  // which is one of several filters that list() supports.
  const allSmartThingsThermostats = await seam.devices.list({
    manufacturer: 'smartthings',
  })

  // Select the first device as an example.
  const livingRoomThermostat = allSmartThingsThermostats[0]

  // Inspect specific properties.
  console.log(
    'Current temperature: ' +
      livingRoomThermostat.properties.temperature_fahrenheit,
  )
  console.log('Fan running: ' + livingRoomThermostat.properties.is_fan_running)

  // View the entire returned device object.
  console.log(livingRoomThermostat)
  ```

  ```bash cURL theme={null}
  # Retrieve all devices, filtered by manufacturer, which is
  # one of several filters that the list endpoint supports.
  all_smartthings_thermostats=$(
    # Use GET or POST.
    curl -X 'GET' \
      'https://connect.getseam.com/devices/list' \
      -H 'accept: application/json' \
      -H "Authorization: Bearer ${SEAM_API_KEY}" \
      -H 'Content-Type: application/json' \
      -d '{
      "manufacturer": "smartthings"
    }')

  # Select the first device as an example.
  living_room_thermostat=$(jq -r '.devices[0]' <<< ${all_smartthings_thermostats})

  # Inspect specific properties.
  echo $(jq -r '"Current temperature: " + (.properties.temperature_fahrenheit | tostring)' <<< ${living_room_thermostat})
  echo $(jq -r '"Fan running: " + (.properties.is_fan_running | tostring)' <<< ${living_room_thermostat})

  # View the entire returned device object.
  echo ${living_room_thermostat}
  ```

  ```python Python theme={null}
  # Retrieve all devices, filtered by manufacturer,
  # which is one of several filters that list() supports.
  all_smartthings_thermostats = seam.devices.list(manufacturer="smartthings")

  # Select the first device as an example.
  living_room_thermostat = all_smartthings_thermostats[0]

  # Inspect specific properties.
  pprint("Current temperature: " + str(living_room_thermostat.properties["temperature_fahrenheit"]))
  pprint("Fan running: " + str(living_room_thermostat.properties["is_fan_running"]))

  # View the entire returned device object.
  pprint(living_room_thermostat)
  ```

  ```ruby Ruby theme={null}
  # Retrieve all devices, filtered by manufacturer,
  # which is one of several filters that list() supports.
  all_smartthings_thermostats = seam.devices.list(manufacturer: "smartthings")

  # Select the first device as an example.
  living_room_thermostat = all_smartthings_thermostats[0]

  # Inspect specific properties.
  puts "Current temperature: " + living_room_thermostat.properties.temperature_fahrenheit.to_s
  puts "Fan running: " + living_room_thermostat.properties.is_fan_running.to_s

  # View the entire returned device object.
  puts living_room_thermostat.inspect
  ```

  ```php PHP theme={null}
  // Retrieve all devices, filtered by manufacturer,
  // which is one of several filters that list() supports.
  $all_smartthings_thermostats = $seam->devices->list(manufacturer: "smartthings");

  // Select the first device as an example.
  $living_room_thermostat = $all_smartthings_thermostats[0];

  // Inspect specific properties.
  echo "Current temperature: ", $living_room_thermostat->properties->temperature_fahrenheit, "\n";
  echo "Fan running: ", $living_room_thermostat->properties->is_fan_running ? 'true' : 'false', "\n";

  // View the entire returned device object.
  echo json_encode($living_room_thermostat, JSON_PRETTY_PRINT);
  ```

  ```csharp C# theme={null}
  // Coming soon!
  ```
</CodeGroup>

**Output:**

<CodeGroup>
  ```json JavaScript theme={null}
  Current temperature: 70
  Fan running: false
  {
    device_id: '11111111-1111-1111-2222-444444444444',
    workspace_id: '00000000-0000-0000-0000-000000000000',
    connected_account_id: '11111111-1111-1111-1111-222222222222',
    created_at: '2024-10-03T22:12:15.666Z',
    properties: {
      manufacturer: 'smartthings',
      online: true,
      temperature_celsius: 21.11111111111111,
      temperature_fahrenheit: 70,
      relative_humidity: 0.36,
      is_cooling: false,
      is_heating: false,
      is_fan_running: false,
      current_climate_setting: {
        display_name: 'Manual Setting',
        fan_mode_setting: 'auto',
        hvac_mode_setting: 'heat',
        manual_override_allowed: true,
        heating_set_point_celsius: 21.11111111111111,
        heating_set_point_fahrenheit: 70
      },
      ...
    },
    can_hvac_cool: true,
    can_hvac_heat: true,
    can_turn_off_hvac: true,
    ...
  }
  ```

  ```json cURL theme={null}
  Current temperature: 70
  Fan running: false
  {
    "device_id": "11111111-1111-1111-2222-444444444444",
    "workspace_id": "00000000-0000-0000-0000-000000000000",
    "connected_account_id": "11111111-1111-1111-1111-222222222222",
    "created_at": "2024-10-03T22:12:15.666Z",
    "properties": {
      "manufacturer": "smartthings",
      "online": true,
      "temperature_celsius": 21.11111111111111,
      "temperature_fahrenheit": 70,
      "relative_humidity": 0.36,
      "is_cooling": false,
      "is_heating": false,
      "is_fan_running": false,
      "current_climate_setting": {
        "display_name": "Manual Setting",
        "fan_mode_setting": "auto",
        "hvac_mode_setting": "heat",
        "manual_override_allowed": true,
        "heating_set_point_celsius": 21.11111111111111,
        "heating_set_point_fahrenheit": 70
      },
      ...
    },
    "can_hvac_cool": true,
    "can_hvac_heat": true,
    "can_turn_off_hvac": true,
    ...
  }
  ```

  ```json Python theme={null}
  'Current temperature: 70'
  'Fan running: False'
  Device(
    device_id='11111111-1111-1111-2222-444444444444',
    workspace_id='00000000-0000-0000-0000-000000000000',
    connected_account_id='11111111-1111-1111-1111-222222222222',
    created_at='2024-10-03T22:12:15.666Z',
    properties={
      'manufacturer': 'smartthings',
      'online': True,
      'temperature_celsius': 21.11111111111111,
      'temperature_fahrenheit': 70,
      'relative_humidity': 0.36,
      'is_cooling': False,
      'is_heating': False,
      'is_fan_running': False,
      'current_climate_setting': {
        'display_name': 'Manual Setting',
        'fan_mode_setting': 'auto',
        'heating_set_point_celsius': 21.11111111111111,
        'heating_set_point_fahrenheit': 70,
        'hvac_mode_setting': 'heat',
        'manual_override_allowed': True
      },
      ...
    },
    can_hvac_cool=True,
    can_hvac_heat=True,
    can_turn_off_hvac=True,
    ...
  )
  ```

  ```json Ruby theme={null}
  Current temperature: 70
  Fan running: false
  <Seam::Resources::Device:0x005f0
    device_id="11111111-1111-1111-2222-444444444444"
    workspace_id="00000000-0000-0000-0000-000000000000"
    connected_account_id="11111111-1111-1111-1111-222222222222"
    created_at=2024-10-03 22:12:15.666 UTC
    properties=#<Seam::DeepHashAccessor:0x0000016b1791f068 @data={
      "manufacturer"=>"smartthings",
      "online"=>true,
      "temperature_celsius"=>21.11111111111111,
      "temperature_fahrenheit"=>70,
      "relative_humidity"=>0.36,
      "is_cooling"=>false,
      "is_heating"=>false,
      "is_fan_running"=>false,
      "current_climate_setting"=>{
        "display_name"=>"Manual Setting",
        "fan_mode_setting"=>"auto",
        "hvac_mode_setting"=>"heat",
        "manual_override_allowed"=>true,
        "heating_set_point_celsius"=>21.11111111111111,
        "heating_set_point_fahrenheit"=>70
      },
      ...
    }>
    can_hvac_cool=true
    can_hvac_heat=true
    can_turn_off_hvac=true
    ...
  >
  ```

  ```json PHP theme={null}
  Current temperature: 70
  Fan running: false
  {
    "device_id": "11111111-1111-1111-2222-444444444444",
    "workspace_id": "00000000-0000-0000-0000-000000000000",
    "connected_account_id": "11111111-1111-1111-1111-222222222222",
    "created_at": "2024-10-03T22:12:15.666Z",
    "properties": {
      "manufacturer": "smartthings",
      "online": true,
      "temperature_celsius": 21.11111111111111,
      "temperature_fahrenheit": 70,
      "relative_humidity": 0.36,
      "is_cooling": false,
      "is_heating": false,
      "is_fan_running": false,
      "current_climate_setting": {
        "display_name": "Manual Setting",
        "fan_mode_setting": "auto",
        "heating_set_point_celsius": 21.11111111111111,
        "heating_set_point_fahrenheit": 70,
        "hvac_mode_setting": "heat",
        "manual_override_allowed": true,
        ...
      },
      ...
    },
    "can_hvac_cool": true,
    "can_hvac_heat": true,
    "can_turn_off_hvac": true,
    ...
  }
  ```

  ```json C# theme={null}
  // Coming soon!
  ```
</CodeGroup>

***

## Step 4: Control your SmartThings-connected thermostat

Next, you can use the Seam API to control your SmartThings-connected thermostat.

Each device that you connect to Seam has a specific set of capabilities. These capabilities define the Seam API actions that you can use. For thermostats, device-specific capabilities include whether you can [set the HVAC mode](/capability-guides/thermostats/configure-current-climate-settings) to `heat`, `cool`, or `heat_cool`. Seam's intuitive and granular [capability flags](/capability-guides/device-and-system-capabilities#capability-flags) inform your application about what features and behaviors each device supports. Notice the capability flags within the code samples in this guide.

Seam provides additional actions for thermostats, such as setting the fan mode, creating and scheduling climate presets, setting temperature thresholds, and configuring weekly thermostat programs. You can also monitor for Seam thermostat-related events, such as reported temperatures outside your set thresholds.

Try out the following actions on your SmartThings-connected thermostat:

* [ ] [Set the HVAC mode](#set-the-hvac-mode)
* [ ] [Create and schedule climate presets](#create-and-schedule-climate-presets)
* [ ] [Configure a weekly thermostat program](#configure-a-weekly-thermostat-program)

### Set the HVAC mode

To set the HVAC mode, use any of the following endpoints or their equivalents in the Seam SDKs:

* `/thermostats/heat`
* `/thermostats/cool`
* `/thermostats/heat_cool` (for devices that support this mode)
* `/thermostats/off`
* `/thermostats/set_hvac_mode`

  This endpoint is a consolidated version of the other four endpoints.

Specify the thermostat that you want to control by including the `device_id` in the request body. Also, include the desired temperature [set point](/capability-guides/thermostats/understanding-thermostat-concepts/set-points).

In this example, set the HVAC mode to `heat` and the desired heating set point to 68 °F.

Each of these HVAC mode endpoints returns an [action attempt](/core-concepts/action-attempts) to track the progress of the operation.

**Code:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  // Confirm that the device supports heat mode.
  // You're using a capability flag here!
  if (livingRoomThermostat.can_hvac_heat) {
    // Set the HVAC mode
    // and return an action attempt.
    const actionAttempt = await seam.thermostats.heat({
      device_id: livingRoomThermostat.device_id,
      heating_set_point_fahrenheit: 68,
    })
  }
  ```

  ```bash cURL theme={null}
  # Confirm that the device supports heat mode.
  # You're using a capability flag here!
  if  $(jq -r '.can_hvac_heat' <<< ${living_room_thermostat}); then \
    # Set the HVAC mode
    # and return an action attempt.
    curl -X 'POST' \
      'https://connect.getseam.com/thermostats/heat' \
      -H 'accept: application/json' \
      -H "Authorization: Bearer ${SEAM_API_KEY}" \
      -H 'Content-Type: application/json' \
      -d "{
        \"device_id\": \"$(jq -r '.device_id' <<< ${living_room_thermostat})\",
        \"heating_set_point_fahrenheit\": 68
    }";
  fi
  ```

  ```python Python theme={null}
  # Confirm that the device supports heat mode.
  # You're using a capability flag here!
  if living_room_thermostat.can_hvac_heat:
    # Set the HVAC mode
    # and return an action attempt.
    action_attempt = seam.thermostats.heat(
      device_id = living_room_thermostat.device_id,
      heating_set_point_fahrenheit = 68
    )
  ```

  ```ruby Ruby theme={null}
  # Confirm that the device supports heat mode.
  # You're using a capability flag here!
  if (living_room_thermostat.can_hvac_heat)
    # Set the HVAC mode
    # and return an action attempt.
    action_attempt = seam.thermostats.heat(
      device_id: living_room_thermostat.device_id,
      heating_set_point_fahrenheit: 68
    )
  end
  ```

  ```php PHP theme={null}
  // Confirm that the device supports heat mode.
  // You're using a capability flag here!
  if ($living_room_thermostat->can_hvac_heat) {
    // Set the HVAC mode
    // and return an action attempt.
    $action_attempt = $seam->thermostats->heat(
      device_id: $living_room_thermostat->device_id,
      heating_set_point_fahrenheit: 68
    );
  }
  ```

  ```csharp C# theme={null}
  // Coming soon!
  ```
</CodeGroup>

**Output:**

<CodeGroup>
  ```json JavaScript theme={null}
  {
    "actionAttempt": {
      "status": "success",
      "action_attempt_id": "11111111-2222-3333-4444-555555555555",
      "action_type": "SET_HVAC_MODE",
      "result": {},
      "error": null
    }
  }
  ```

  ```json cURL theme={null}
  {
    "action_attempt": {
      "status": "pending",
      "action_type": "SET_HVAC_MODE",
      "action_attempt_id": "11111111-2222-3333-4444-555555555555",
      "result": null,
      "error": null
    },
    "ok": true
  }
  ```

  ```json Python theme={null}
  ActionAttempt(
    action_attempt_id='11111111-2222-3333-4444-555555555555',
    action_type='SET_HVAC_MODE',
    status='success',
    result={},
    error=None
  )
  ```

  ```json Ruby theme={null}
  <Seam::Resources::ActionAttempt:0x005f0
    status="success"
    action_type="SET_HVAC_MODE"
    action_attempt_id="11111111-2222-3333-4444-555555555555"
    result={}
    error=nil>
  ```

  ```json PHP theme={null}
  {
    "action_attempt_id": "11111111-2222-3333-4444-555555555555",
    "action_type": "SET_HVAC_MODE",
    "error": null,
    "result": {},
    "status": "success"
  }
  ```

  ```json C# theme={null}
  // Coming soon!
  ```
</CodeGroup>

You can track the status of the operation to confirm that the device was set to heat mode successfully. Query `properties.current_climate_setting.hvac_mode_setting` for the device, [retrieve the action attempt](/api/action_attempts/get) by ID, or look for a [`thermostat.manually_adjusted` event](/api/thermostats/events#thermostat-manually_adjusted). Further, if you wanted to find out whether the HVAC system was currently heating, you could inspect `properties.is_heating` for the device.

To query `properties.current_climate_setting.hvac_mode_setting` for the device:

**Code:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  // Get the device by ID.
  const updatedLivingRoomThermostat = await seam.devices.get({
    device_id: livingRoomThermostat.device_id,
  })

  // Inspect properties.current_climate_setting.hvac_mode_setting
  // to confirm that setting the HVAC mode to heat was successful.
  console.log(
    updatedLivingRoomThermostat.properties.current_climate_setting
      .hvac_mode_setting,
  )
  ```

  ```bash cURL theme={null}
  # Get the device by ID.
  updated_living_room_thermostat=$(
    # Use GET or POST.
    curl -X 'GET' \
      'https://connect.getseam.com/devices/get' \
      -H 'accept: application/json' \
      -H "Authorization: Bearer ${SEAM_API_KEY}" \
      -H 'Content-Type: application/json' \
      -d "{
        \"device_id\": \"$(jq -r '.device_id' <<< ${living_room_thermostat})\"
    }")

  # Inspect properties.current_climate_setting.hvac_mode_setting
  # to confirm that setting the HVAC mode to heat was successful.
  echo $(jq -r '(.device.properties.current_climate_setting.hvac_mode_setting)' <<< ${updated_living_room_thermostat})
  ```

  ```python Python theme={null}
  # Get the device by ID.
  updated_living_room_thermostat = seam.devices.get(
    device_id = living_room_thermostat.device_id
  )

  # Inspect properties.current_climate_setting.hvac_mode_setting
  # to confirm that setting the HVAC mode to heat was successful.
  pprint(
    updated_living_room_thermostat.
    properties["current_climate_setting"]["hvac_mode_setting"]
  )
  ```

  ```ruby Ruby theme={null}
  # Get the device by ID.
  updated_living_room_thermostat = seam.devices.get(
    device_id: living_room_thermostat.device_id
  )

  # Inspect properties.current_climate_setting.hvac_mode_setting
  # to confirm that setting the HVAC mode to heat was successful.
  puts updated_living_room_thermostat.
    properties.current_climate_setting.hvac_mode_setting
  ```

  ```php PHP theme={null}
  // Get the device by ID.
  $updated_living_room_thermostat = $seam->devices->get(
    device_id: $living_room_thermostat->device_id
  );

  // Inspect properties.current_climate_setting.hvac_mode_setting
  // to confirm that setting the HVAC mode to heat was successful.
  echo $updated_living_room_thermostat->properties->
    current_climate_setting->hvac_mode_setting;
  ```

  ```csharp C# theme={null}
  // Coming soon!
  ```
</CodeGroup>

**Output:**

<CodeGroup>
  ```json JavaScript theme={null}
  heat
  ```

  ```json cURL theme={null}
  heat
  ```

  ```json Python theme={null}
  'heat'
  ```

  ```json Ruby theme={null}
  heat
  ```

  ```json PHP theme={null}
  heat
  ```

  ```json C# theme={null}
  // Coming soon!
  ```
</CodeGroup>

***

### Create and schedule climate presets

You can use the Seam API to create climate presets for SmartThings thermostats. Each climate preset is a saved group of settings, such as HVAC mode, fan mode, and temperature set points. Climate presets make it quick and easy to apply consistent climate settings for different scenarios. For example, you could create two climate presets: a comfort preset for when a vacation rental is occupied and an eco preset for when the vacation rental is empty.

You can schedule climate presets to start and stop whenever you'd like. You can even set a fallback climate preset, such as eco.

In this example, create comfort and eco climate presets, set eco as the fallback, and schedule the comfort climate preset to coincide with two vacation rental reservations.

**Code:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  // Confirm that the thermostat supports cool mode
  // so that the climate presets can use this mode.
  if (updatedLivingRoomThermostat.can_hvac_cool) {
    // Create the climate presets.
    await seam.thermostats.createClimatePreset({
      device_id: updatedLivingRoomThermostat.device_id,
      climate_preset_key: 'comfort',
      name: 'Comfort',
      fan_mode_setting: 'auto',
      hvac_mode_setting: 'cool',
      cooling_set_point_celsius: 25,
    })

    await seam.thermostats.createClimatePreset({
      device_id: updatedLivingRoomThermostat.device_id,
      climate_preset_key: 'eco',
      name: 'Eco',
      fan_mode_setting: 'auto',
      hvac_mode_setting: 'cool',
      cooling_set_point_celsius: 30,
    })

    // Then, set eco as the fallback climate setting.
    await seam.thermostats.setFallbackClimatePreset({
      device_id: updatedLivingRoomThermostat.device_id,
      climate_preset_key: 'eco',
    })

    // Now, schedule the comfort preset to coincide with two reservations.
    await seam.thermostats.schedules.create({
      device_id: updatedLivingRoomThermostat.device_id,
      name: "Jim's stay",
      climate_preset_key: 'comfort',
      starts_at: '2025-03-10T15:00:00Z',
      ends_at: '2025-03-15T12:00:00Z',
      is_override_allowed: true,
      max_override_period_minutes: 90,
    })

    await seam.thermostats.schedules.create({
      device_id: updatedLivingRoomThermostat.device_id,
      name: "Jane's stay",
      climate_preset_key: 'comfort',
      starts_at: '2025-03-17T15:00:00Z',
      ends_at: '2025-03-20T12:00:00Z',
      is_override_allowed: true,
      max_override_period_minutes: 90,
    })
  }
  ```

  ```bash cURL theme={null}
  # Confirm that the thermostat supports cool mode
  # so that the climate presets can use this mode.
  if  $(jq -r '.device.can_hvac_cool' <<< ${updated_living_room_thermostat}); then \
    # Create the climate presets.
    curl -X 'POST' \
      'https://connect.getseam.com/thermostats/create_climate_preset' \
      -H 'accept: application/json' \
      -H "Authorization: Bearer ${SEAM_API_KEY}" \
      -H 'Content-Type: application/json' \
      -d "{
        \"device_id\": \"$(jq -r '.device.device_id' <<< ${updated_living_room_thermostat})\",
        \"climate_preset_key\": \"comfort\",
        \"name\": \"Comfort\",
        \"fan_mode_setting\": \"auto\",
        \"hvac_mode_setting\": \"cool\",
        \"cooling_set_point_celsius\": 25
    }";

    curl -X 'POST' \
      'https://connect.getseam.com/thermostats/create_climate_preset' \
      -H 'accept: application/json' \
      -H "Authorization: Bearer ${SEAM_API_KEY}" \
      -H 'Content-Type: application/json' \
      -d "{
        \"device_id\": \"$(jq -r '.device.device_id' <<< ${updated_living_room_thermostat})\",
        \"climate_preset_key\": \"eco\",
        \"name\": \"Eco\",
        \"fan_mode_setting\": \"auto\",
        \"hvac_mode_setting\": \"cool\",
        \"cooling_set_point_celsius\": 30
    }";

    # Then, set eco as the fallback climate setting.
    curl -X 'POST' \
      'https://connect.getseam.com/thermostats/set_fallback_climate_preset' \
      -H 'accept: application/json' \
      -H "Authorization: Bearer ${SEAM_API_KEY}" \
      -H 'Content-Type: application/json' \
      -d "{
        \"device_id\": \"$(jq -r '.device.device_id' <<< ${updated_living_room_thermostat})\",
        \"climate_preset_key\": \"eco\"
    }";

    # Now, schedule the comfort preset to coincide with two reservations.
    curl -X 'POST' \
    'https://connect.getseam.com/thermostats/schedules/create' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d "{
      \"device_id\": \"$(jq -r '.device.device_id' <<< ${updated_living_room_thermostat})\",
      \"name\":  \"Jim's stay\",
      \"climate_preset_key\": \"comfort\",
      \"starts_at\": \"2025-03-10T15:00:00Z\",
      \"ends_at\": \"2025-03-15T12:00:00Z\",
      \"is_override_allowed\": true,
      \"max_override_period_minutes\": 90
    }";

    curl -X 'POST' \
    'https://connect.getseam.com/thermostats/schedules/create' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d "{
      \"device_id\": \"$(jq -r '.device.device_id' <<< ${updated_living_room_thermostat})\",
      \"name\":  \"Jane's stay\",
      \"climate_preset_key\": \"comfort\",
      \"starts_at\": \"2025-03-17T15:00:00Z\",
      \"ends_at\": \"2025-03-20T12:00:00Z\",
      \"is_override_allowed\": true,
      \"max_override_period_minutes\": 90
    }";
  fi
  ```

  ```python Python theme={null}
  # Confirm that the thermostat supports cool mode
  # so that the climate presets can use this mode.
  if updated_living_room_thermostat.can_hvac_cool:
    # Create the climate presets.
    seam.thermostats.create_climate_preset(
      device_id = updated_living_room_thermostat.device_id,
      climate_preset_key = "comfort",
      name = "Comfort",
      fan_mode_setting = "auto",
      hvac_mode_setting = "cool",
      cooling_set_point_celsius = 25
    )

    seam.thermostats.create_climate_preset(
      device_id: updated_living_room_thermostat.device_id,
      climate_preset_key = "eco",
      name = "Eco",
      fan_mode_setting = "auto",
      hvac_mode_setting = "cool",
      cooling_set_point_celsius = 30
    )

    # Then, set eco as the fallback climate setting.
    seam.thermostats.set_fallback_climate_preset(
      device_id = updated_living_room_thermostat.device_id,
      climate_preset_key = "eco"
    )

    # Now, schedule the comfort preset to coincide with two reservations.
    seam.thermostats.schedules.create(
      device_id = updated_living_room_thermostat.device_id,
      name = "Jim's stay",
      climate_preset_key = "comfort",
      starts_at = "2025-03-10T15:00:00Z",
      ends_at = "2025-03-15T12:00:00Z",
      is_override_allowed = True,
      max_override_period_minutes = 90
    )

    seam.thermostats.schedules.create(
      device_id = updated_living_room_thermostat.device_id,
      name = "Jane's stay",
      climate_preset_key = "comfort",
      starts_at = "2025-03-17T15:00:00Z",
      ends_at = "2025-03-20T12:00:00Z",
      is_override_allowed = True,
      max_override_period_minutes = 90
    )
  ```

  ```ruby Ruby theme={null}
  # Confirm that the thermostat supports cool mode
  # so that the climate presets can use this mode.
  if (updated_living_room_thermostat.can_hvac_cool)
    # Create the climate presets.
    seam.thermostats.create_climate_preset(
      device_id: updated_living_room_thermostat.device_id,
      climate_preset_key: "comfort",
      name: "Comfort",
      fan_mode_setting: "auto",
      hvac_mode_setting: "cool",
      cooling_set_point_celsius: 25
    )

    seam.thermostats.create_climate_preset(
      device_id: updated_living_room_thermostat.device_id,
      climate_preset_key: "eco",
      name: "Eco",
      fan_mode_setting: "auto",
      hvac_mode_setting: "cool",
      cooling_set_point_celsius: 30
    )

    # Then, set eco as the fallback climate setting.
    seam.thermostats.set_fallback_climate_preset(
      device_id: updated_living_room_thermostat.device_id,
      climate_preset_key: "eco"
    )

    # Now, schedule the comfort preset to coincide with two reservations.
    seam.thermostats.schedules.create(
      device_id: updated_living_room_thermostat.device_id,
      name: "Jim's stay",
      climate_preset_key: "comfort",
      starts_at: "2025-03-10T15:00:00Z",
      ends_at: "2025-03-15T12:00:00Z",
      is_override_allowed: true,
      max_override_period_minutes: 90
    )

    await seam.thermostats.schedules.create(
      device_id: updated_living_room_thermostat.device_id,
      name: "Jane's stay",
      climate_preset_key: "comfort",
      starts_at: "2025-03-17T15:00:00Z",
      ends_at: "2025-03-20T12:00:00Z",
      is_override_allowed: true,
      max_override_period_minutes: 90
    )
  end
  ```

  ```php PHP theme={null}
  // Confirm that the thermostat supports cool mode
  // so that the climate presets can use this mode.
  if ($updated_living_room_thermostat->can_hvac_cool) {
    // Create the climate presets.
    $seam->thermostats->create_climate_preset(
      device_id: $updated_living_room_thermostat->device_id,
      climate_preset_key: "comfort",
      name: "Comfort",
      fan_mode_setting: "auto",
      hvac_mode_setting: "cool",
      cooling_set_point_celsius: 25
    );

    $seam->thermostats->create_climate_preset(
      device_id: $updated_living_room_thermostat->device_id,
      climate_preset_key: "eco",
      name: "Eco",
      fan_mode_setting: "auto",
      hvac_mode_setting: "cool",
      cooling_set_point_celsius: 30
    );

    // Then, set eco as the fallback climate setting.
    $seam->thermostats->set_fallback_climate_preset(
      device_id: $updated_living_room_thermostat->device_id,
      climate_preset_key: "eco"
    );

    // Now, schedule the comfort preset to coincide with two reservations.
    $seam->thermostats->schedules->create(
      device_id: $updated_living_room_thermostat->device_id,
      name: "Jim's stay",
      climate_preset_key: "comfort",
      starts_at: "2025-03-10T15:00:00Z",
      ends_at: "2025-03-15T12:00:00Z",
      is_override_allowed: true,
      max_override_period_minutes: 90
    );

    $seam->thermostats->schedules->create(
      device_id: updated_living_room_thermostat.device_id,
      name: "Jane's stay",
      climate_preset_key: "comfort",
      starts_at: "2025-03-17T15:00:00Z",
      ends_at: "2025-03-20T12:00:00Z",
      is_override_allowed: true,
      max_override_period_minutes: 90
    );
  }
  ```

  ```csharp C# theme={null}
  // Coming soon!
  ```
</CodeGroup>

**Output:**

<CodeGroup>
  ```json JavaScript theme={null}
  {
    thermostat_schedule_id: '88888888-1111-1111-1111-111111111111',
    name: "Jim's stay",
    device_id: '11111111-1111-1111-2222-444444444444',
    climate_preset_key: 'comfort',
    starts_at: '2025-03-10T15:00:00.000Z',
    ends_at: '2025-03-15T12:00:00.000Z',
    is_override_allowed: true,
    max_override_period_minutes: 90,
    ...
  }
  {
    thermostat_schedule_id: '88888888-1111-1111-1111-222222222222',
    name: "Jane's stay",
    device_id: '11111111-1111-1111-2222-444444444444',
    climate_preset_key: 'comfort',
    starts_at: '2025-03-17T15:00:00.000Z',
    ends_at: '2025-03-20T12:00:00.000Z',
    is_override_allowed: true,
    max_override_period_minutes: 90,
    ...
  }
  ```

  ```json cURL theme={null}
  {
    "thermostat_schedule":{
      "thermostat_schedule_id":"88888888-1111-1111-1111-111111111111",
      "name":"Jim's stay",
      "device_id":"11111111-1111-1111-2222-444444444444",
      "climate_preset_key":"comfort",
      "starts_at":"2025-03-10T15:00:00.000Z",
      "ends_at":"2025-03-15T12:00:00.000Z",
      "is_override_allowed":true,
      "max_override_period_minutes":90,
      ...
    },
    "ok":true
  }
  {
    "thermostat_schedule":{
      "thermostat_schedule_id":"88888888-1111-1111-1111-222222222222",
      "name":"Jane's stay",
      "device_id":"11111111-1111-1111-2222-444444444444",
      "climate_preset_key":"comfort",
      "starts_at":"2025-03-17T15:00:00.000Z",
      "ends_at":"2025-03-20T12:00:00.000Z",
      "is_override_allowed":true,
      "max_override_period_minutes":90,
      ...
    },
    "ok":true
  }
  ```

  ```json Python theme={null}
  ThermostatSchedule(
    thermostat_schedule_id='88888888-1111-1111-1111-111111111111',
    name="Jim's stay",
    device_id='11111111-1111-1111-2222-444444444444',
    climate_preset_key='comfort',
    starts_at='2025-03-10T15:00:00.000Z',
    ends_at='2025-03-15T12:00:00.000Z',
    is_override_allowed=True,
    max_override_period_minutes=90,
    ...
  )
  ThermostatSchedule(
    thermostat_schedule_id='88888888-1111-1111-1111-222222222222',
    name="Jane's stay",
    device_id='11111111-1111-1111-2222-444444444444',
    climate_preset_key='comfort',
    starts_at='2025-03-17T15:00:00.000Z',
    ends_at='2025-03-20T12:00:00.000Z',
    is_override_allowed=True,
    max_override_period_minutes=90,
    ...
  )
  ```

  ```json Ruby theme={null}
  <Seam::Resources::ThermostatSchedule:0x005f0
    thermostat_schedule_id="88888888-1111-1111-1111-111111111111"
    name="Jim's stay"
    device_id="11111111-1111-1111-2222-444444444444"
    climate_preset_key="comfort"
    starts_at=2025-03-10 15:00:00 UTC
    ends_at=2025-03-15 12:00:00 UTC
    is_override_allowed=true
    max_override_period_minutes=90
    ...
  >
  <Seam::Resources::ThermostatSchedule:0x005f0
    thermostat_schedule_id="88888888-1111-1111-1111-222222222222"
    name="Jane's stay"
    device_id="11111111-1111-1111-2222-444444444444"
    climate_preset_key="comfort"
    starts_at=2025-03-17 15:00:00 UTC
    ends_at=2025-03-20 12:00:00 UTC
    is_override_allowed=true
    max_override_period_minutes=90
    ...
  >
  ```

  ```json PHP theme={null}
  {
    "thermostat_schedule_id":"88888888-1111-1111-1111-111111111111",
    "name":"Jim's stay",
    "device_id":"11111111-1111-1111-2222-444444444444",
    "climate_preset_key":"comfort",
    "starts_at":"2025-03-10T15:00:00.000Z",
    "ends_at":"2025-03-15T12:00:00.000Z",
    "is_override_allowed":true,
    "max_override_period_minutes":90,
    ...
  }
  {
    "thermostat_schedule_id":"88888888-1111-1111-1111-222222222222",
    "name":"Jane's stay",
    "device_id":"11111111-1111-1111-2222-444444444444",
    "climate_preset_key":"comfort",
    "starts_at":"2025-03-17T15:00:00.000Z",
    "ends_at":"2025-03-20T12:00:00.000Z",
    "is_override_allowed":true,
    "max_override_period_minutes":90,
    ...
  }
  ```

  ```json C# theme={null}
  // Coming soon!
  ```
</CodeGroup>

***

### Configure a weekly thermostat program

You can use the Seam API to create a thermostat weekly program for your SmartThings-connected thermostat. This standard feature of smart thermostats enables you to define full-week programs that are made up of reusable daily programs. Each daily program consists of a set of thermostat daily program periods, that is, time blocks with associated climate presets.

In this example, create a weekday daily program and a weekend daily program. Then, combine these daily programs into a weekly program by assigning a daily program to each day of the week.

**Code:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  // Create the daily programs.
  const weekdayProgram = await seam.thermostats.dailyPrograms.create({
    device_id: updatedLivingRoomThermostat.device_id,
    name: 'Weekday Program',
    periods: [
      { starts_at_time: '07:00:00', climate_preset_key: 'Home' },
      { starts_at_time: '09:00:00', climate_preset_key: 'Away' },
      { starts_at_time: '18:00:00', climate_preset_key: 'Home' },
      { starts_at_time: '22:00:00', climate_preset_key: 'Sleep' },
    ],
  })

  const weekendProgram = await seam.thermostats.dailyPrograms.create({
    device_id: updatedLivingRoomThermostat.device_id,
    name: 'Weekend Program',
    periods: [
      { starts_at_time: '08:00:00', climate_preset_key: 'Home' },
      { starts_at_time: '23:00:00', climate_preset_key: 'Sleep' },
    ],
  })

  // Use the daily programs to set the weekly program.
  await seam.thermostats.updateWeeklyProgram({
    device_id: updatedLivingRoomThermostat.device_id,
    monday_program_id: weekdayProgram.thermostat_daily_program_id,
    tuesday_program_id: weekdayProgram.thermostat_daily_program_id,
    wednesday_program_id: weekdayProgram.thermostat_daily_program_id,
    thursday_program_id: weekdayProgram.thermostat_daily_program_id,
    friday_program_id: weekdayProgram.thermostat_daily_program_id,
    saturday_program_id: weekendProgram.thermostat_daily_program_id,
    sunday_program_id: weekendProgram.thermostat_daily_program_id,
  })
  ```

  ```bash cURL theme={null}
  # Create the daily programs.
  weekday_program=$(curl -X 'POST' \
    'https://connect.getseam.com/thermostats/daily_programs/create' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d "{
      \"device_id\": \"$(jq -r '.device.device_id' <<< ${updated_living_room_thermostat})\",
      \"name\":  \"Weekday Program\",
      \"periods\": [
      { \"starts_at_time\": \"07:00:00\", \"climate_preset_key\": \"Home\" },
      { \"starts_at_time\": \"09:00:00\", \"climate_preset_key\": \"Away\" },
      { \"starts_at_time\": \"18:00:00\", \"climate_preset_key\": \"Home\" },
      { \"starts_at_time\": \"22:00:00\", \"climate_preset_key\": \"Sleep\" }
    ]
  }")
  weekday_program_id=$(jq -r '.thermostat_daily_program_id' <<< ${weekday_program})

  weekend_program=$(curl -X 'POST' \
    'https://connect.getseam.com/thermostats/daily_programs/create' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d "{
      \"device_id\": \"$(jq -r '.device.device_id' <<< ${updated_living_room_thermostat})\",
      \"name\":  \"Weekend Program\",
      \"periods\": [
      { \"starts_at_time\": \"08:00:00\", \"climate_preset_key\": \"Home\" },
      { \"starts_at_time\": \"23:00:00\", \"climate_preset_key\": \"Sleep\" }
    ]
  }")
  weekend_program_id=$(jq -r '.thermostat_daily_program_id' <<< ${weekend_program})

  # Use the daily programs to set the weekly program.
  curl -X 'POST' \
    'https://connect.getseam.com/thermostats/update_weekly_program' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d "{
      \"device_id\": \"$(jq -r '.device.device_id' <<< ${updated_living_room_thermostat})\",
      \"monday_program_id\": \"${weekday_program_id}\",
      \"tuesday_program_id\": \"${weekday_program_id}\",
      \"wednesday_program_id\": \"${weekday_program_id}\",
      \"thursday_program_id\": \"${weekday_program_id}\",
      \"friday_program_id\": \"${weekday_program_id}\",
      \"saturday_program_id\": \"${weekend_program_id}\",
      \"sunday_program_id\": \"${weekend_program_id}\"
  }"
  ```

  ```python Python theme={null}
  # Create the daily programs.
  weekday_program = seam.thermostats.daily_programs.create(
    device_id = updated_living_room_thermostat.device_id,
    name = "Weekday Program",
    periods = [
      { "starts_at_time": "07:00:00", "climate_preset_key": "Home" },
      { "starts_at_time": "09:00:00", "climate_preset_key": "Away" },
      { "starts_at_time": "18:00:00", "climate_preset_key": "Home" },
      { "starts_at_time": "22:00:00", "climate_preset_key": "Sleep" }
    ]
  )

  weekend_program = seam.thermostats.daily_programs.create(
    device_id = updated_living_room_thermostat.device_id,
    name = "Weekend Program",
    periods = [
      { "starts_at_time": "08:00:00", "climate_preset_key": "Home" },
      { "starts_at_time": "23:00:00", "climate_preset_key": "Sleep" }
    ]
  )

  # Use the daily programs to set the weekly program.
  seam.thermostats.update_weekly_program(
    device_id = updated_living_room_thermostat.device_id,
    monday_program_id = weekday_program.thermostat_daily_program_id,
    tuesday_program_id = weekday_program.thermostat_daily_program_id,
    wednesday_program_id = weekday_program.thermostat_daily_program_id,
    thursday_program_id = weekday_program.thermostat_daily_program_id,
    friday_program_id = weekday_program.thermostat_daily_program_id,
    saturday_program_id = weekend_program.thermostat_daily_program_id,
    sunday_program_id = weekend_program.thermostat_daily_program_id
  )
  ```

  ```ruby Ruby theme={null}
  # Create the daily programs.
  weekday_program = seam.thermostats.daily_programs.create(
    device_id: updated_living_room_thermostat.device_id,
    name: "Weekday Program",
    periods: [
      { "starts_at_time": "07:00:00", "climate_preset_key": "Home" },
      { "starts_at_time": "09:00:00", "climate_preset_key": "Away" },
      { "starts_at_time": "18:00:00", "climate_preset_key": "Home" },
      { "starts_at_time": "22:00:00", "climate_preset_key": "Sleep" }
    ]
  )

  weekend_program = seam.thermostats.daily_programs.create(
    device_id: updated_living_room_thermostat.device_id,
    name: "Weekend Program",
    periods: [
      { "starts_at_time": "08:00:00", "climate_preset_key": "Home" },
      { "starts_at_time": "23:00:00", "climate_preset_key": "Sleep" }
    ]
  )

  # Use the daily programs to set the weekly program.
  seam.thermostats.update_weekly_program(
    device_id: updated_living_room_thermostat.device_id,
    monday_program_id: weekday_program.thermostat_daily_program_id,
    tuesday_program_id: weekday_program.thermostat_daily_program_id,
    wednesday_program_id: weekday_program.thermostat_daily_program_id,
    thursday_program_id: weekday_program.thermostat_daily_program_id,
    friday_program_id: weekday_program.thermostat_daily_program_id,
    saturday_program_id: weekend_program.thermostat_daily_program_id,
    sunday_program_id: weekend_program.thermostat_daily_program_id
  )
  ```

  ```php PHP theme={null}
  // Create the daily programs.
  $weekday_program = $seam->thermostats->daily_programs->create(
    device_id: $updated_living_room_thermostat->device_id,
    name: "Weekday Program",
    periods: [
      { "starts_at_time": "07:00:00", "climate_preset_key": "Home" },
      { "starts_at_time": "09:00:00", "climate_preset_key": "Away" },
      { "starts_at_time": "18:00:00", "climate_preset_key": "Home" },
      { "starts_at_time": "22:00:00", "climate_preset_key": "Sleep" }
    ]
  );

  $weekend_program = $seam->thermostats->daily_programs->create(
    device_id: $updated_living_room_thermostat->device_id,
    name: "Weekend Program",
    periods: [
      { "starts_at_time": "08:00:00", "climate_preset_key": "Home" },
      { "starts_at_time": "23:00:00", "climate_preset_key": "Sleep" }
    ]
  );

  // Use the daily programs to set the weekly program.
  $seam->thermostats->update_weekly_program(
    device_id: $updated_living_room_thermostat->device_id,
    monday_program_id: $weekday_program->thermostat_daily_program_id,
    tuesday_program_id: $weekday_program->thermostat_daily_program_id,
    wednesday_program_id: $weekday_program->thermostat_daily_program_id,
    thursday_program_id: $weekday_program->thermostat_daily_program_id,
    friday_program_id: $weekday_program->thermostat_daily_program_id,
    saturday_program_id: $weekend_program->thermostat_daily_program_id,
    sunday_program_id: $weekend_program->thermostat_daily_program_id
  );
  ```

  ```csharp C# theme={null}
  // Coming soon!
  ```
</CodeGroup>

**Output:**

<CodeGroup>
  ```json JavaScript theme={null}
  {
    "status": "success",
    "action_attempt_id": "11111111-2222-3333-4444-666666666666",
    "action_type": "PUSH_THERMOSTAT_PROGRAMS",
    "result": {},
    "error": null
  }
  ```

  ```json cURL theme={null}
  {
    "action_attempt": {
      "status": "pending",
      "action_type": "PUSH_THERMOSTAT_PROGRAMS",
      "action_attempt_id": "11111111-2222-3333-4444-666666666666",
      "result": null,
      "error": null
    },
    "ok": true
  }
  ```

  ```json Python theme={null}
  ActionAttempt(
    action_attempt_id='11111111-2222-3333-4444-666666666666',
    action_type='PUSH_THERMOSTAT_PROGRAMS',
    status='success',
    result={},
    error=None
  )
  ```

  ```json Ruby theme={null}
  <Seam::Resources::ActionAttempt:0x005f0
    status="success"
    action_type="PUSH_THERMOSTAT_PROGRAMS"
    action_attempt_id="11111111-2222-3333-4444-666666666666"
    result={}
    error=nil>
  ```

  ```json PHP theme={null}
  {
    "status": "success",
    "action_attempt_id": "11111111-2222-3333-4444-666666666666",
    "action_type": "PUSH_THERMOSTAT_PROGRAMS",
    "result": {},
    "error": null
  }
  ```

  ```json C# theme={null}
  // Coming soon!
  ```
</CodeGroup>

***

## Step 5: Connect a real SmartThings-connected thermostat

Now that you have learned the basics of using the Seam API, you can connect and control a real SmartThings-connected device. To do so, make sure to switch to a [non-sandbox workspace](/core-concepts/workspaces#production-workspaces) and [API key](/core-concepts/authentication/api-keys).

For more details about setting up your real SmartThings-connected thermostat, see the [SmartThings Hubs + devices integration guide](./).

***

## Step 6: Build your application!

Seam makes it easy to develop your application. The robust Seam API and Seam SDKs in a wide variety of programming languages provide robust, up-to-date information about your thermostats. We also provide helpful thermostat-related events that enable you to monitor the status of your thermostats and the connected HVAC systems. Further, our simulation endpoints make it easy for you to test your thermostat app against events that can be difficult to orchestrate in your quality assurance (QA) environment using real devices.

***

## Next steps

Now that you've completed this getting started guide for SmartThings-connected devices, you can learn more about what you can do with the Seam API.

* [ ] **Explore**\
  See the [other devices and system integrations](/device-and-system-integration-guides) that Seam supports.
* [ ] **Learn**\
  Read about Seam [concepts](/core-concepts/overview) and the [device and system capabilities ](/capability-guides/device-and-system-capabilities)that Seam supports.
* [ ] **Expand your abilities**\
  Find out what other [thermostat actions](/capability-guides/thermostats) you can perform using the Seam API.
* [ ] **Use webhooks**\
  Learn how to use [webhooks](/developer-tools/webhooks) as an efficient way to receive device events.
* [ ] **Find out more**\
  Explore the other types of devices and systems that you can control with Seam, including [smart locks](/low-level-apis/smart-locks), [access control systems](/low-level-apis/access-systems), and [noise sensors](/capability-guides/noise-sensors).
* [ ] **Develop for mobile access**\
  Learn about Seam's [mobile access solution](/capability-guides/mobile-access).

<Info>
  If you have any questions or want to report an issue, email us at
  [support@seam.co](mailto:support@seam.co).
</Info>

***

## Quick links

<CardGroup>
  <Card title="Get an API Key (free)" href="https://console.seam.co/">
    Sign up for the Seam Console and get your API keys. →
  </Card>

  <Card title="Contact Sales" href="https://www.seam.co/contact-us">
    Got a project or a specific question? Contact our team to get answers. →
  </Card>
</CardGroup>


# SmartThings Hubs + Devices
Source: https://docs.seam.co/device-and-system-integration-guides/smartthings-hubs-+-devices/index

Guide for using SmartThings-connected devices with Seam

<img alt="SmartThings logo" />

## Overview

Samsung SmartThings is a smart home platform that enables you to connect a variety of devices to a SmartThings Hub using Zigbee or Z-Wave. SmartThings Hubs are connected to your local network using Wi-Fi or Ethernet.

***

## Supported Devices

<DeviceList />

This integration supports smart locks and thermostats connected to a [SmartThings Hub](https://aeotec.com/where-to-buy/).

For detailed information about the SmartThings devices that Seam supports, see our [SmartThings Supported Devices page](https://www.seam.co/manufacturers/smartthings).

***

## Supported Features

We support the following features:

* [Triggering web lock and unlock actions](/low-level-apis/smart-locks/lock-and-unlock) on smart locks
* [Programming online access codes](/low-level-apis/smart-locks/access-codes) on smart locks that have a connected keypad
* [Configuring current thermostat settings](/capability-guides/thermostats/configure-current-climate-settings) on thermostats
* [Creating and managing climate presets](/capability-guides/thermostats/creating-and-managing-climate-presets) on thermostats
* [Creating and managing thermostat schedules](/capability-guides/thermostats/creating-and-managing-thermostat-schedules) on thermostats
* [Creating and managing thermostat weekly programs](/capability-guides/thermostats/creating-and-managing-thermostat-programs) on thermostats
* [Setting and monitoring temperature thresholds](/capability-guides/thermostats/setting-and-monitoring-temperature-thresholds) on thermostats

***

### Device Provider Key

Seam identifies these devices with the `smartthings` device provider key. By default, a [Connect Webview](/core-concepts/connect-webviews) displays all of the stable providers that Seam supports, so your users can connect their SmartThings-connected devices without you specifying a provider list. To narrow what a Connect Webview displays, see [Customize the Brands to Display in Your Connect Webviews](/core-concepts/connect-webviews/customizing-connect-webviews#customize-the-brands-to-display-in-your-connect-webviews).

***

## Setup Instructions

For instructions on connecting SmartThings devices to Seam, see the [SmartThings Setup Guide](./smartthings-setup-guide).

***

## Brand-Specific Restrictions

Note the following SmartThings-specific restrictions:

### Limiting Device Types to Connect

Because SmartThings supports multiple device types, you can choose which types of devices your users can connect to Seam. By default, Seam connects SmartThings locks. If you want your users to be able to connect SmartThings thermostats, use the `accepted_capabilities` parameter when creating a Connect Webview. Set this parameter to an array containing one or more of `thermostat` and `lock`. For details, see [Customize the Types of Devices to Connect](/core-concepts/connect-webviews/customizing-connect-webviews#customize-the-types-of-devices-to-connect).

### Device Status Reporting

Different devices connected to SmartThings Hubs may have different levels of support for reporting their online status and other related properties.

***

## Where to Order

To purchase SmartThings Hubs, visit the Aeotek **Where to Buy?** page.

<table>
  <thead>
    <tr>
      <th />

      <th />

      <th />

      <th />

      <th />
    </tr>
  </thead>

  <tbody>
    <tr>
      <td />

      <td>
        <strong>Aeotek Where to Buy? Page</strong>
      </td>

      <td />

      <td>
        <a href="https://aeotec.com/where-to-buy/">
          [https://aeotec.com/where-to-buy/](https://aeotec.com/where-to-buy/)
        </a>
      </td>

      <td>
        <a href="/images/smartthings-logo.png">smartthings-logo.png</a>
      </td>
    </tr>
  </tbody>
</table>


# Sandbox SmartThings Hub
Source: https://docs.seam.co/device-and-system-integration-guides/smartthings-hubs-+-devices/smartthings-sample-data

Add virtual SmartThings Hub-connected devices to your Seam sandbox workspace using these sample credentials to test your integration.

Use the following set of credentials to add virtual SmartThings Hub-connected devices to your Seam [sandbox workspace](/core-concepts/workspaces#sandbox-workspaces):

<table>
  <thead>
    <tr>
      <th>Email Address</th>
      <th>Password</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>[jane@example.com](mailto:jane@example.com)</td>
      <td>1234</td>
    </tr>

    <tr>
      <td>[sam@example.com](mailto:sam@example.com)</td>
      <td>1234</td>
    </tr>

    <tr>
      <td>[frodo@example.com](mailto:frodo@example.com)</td>
      <td>1234</td>
    </tr>
  </tbody>
</table>


# SmartThings Setup Guide
Source: https://docs.seam.co/device-and-system-integration-guides/smartthings-hubs-+-devices/smartthings-setup-guide

Connect your SmartThings hubs and devices to Seam.

To use Seam with SmartThings-connected devices, ask the device owner to complete the steps below. Devices must already be paired to a SmartThings Hub before proceeding.

### 1. Set up the SmartThings app

1. Download and install the [SmartThings app](https://www.samsung.com/us/support/owners/app/smartthings) and create an account if you don't have one.
2. In the SmartThings app, add your devices.
3. Follow [these instructions](https://www.samsung.com/ca/support/mobile-devices/smartthings-how-to-set-up-your-hub/) to pair your devices to the SmartThings Hub.

### 2. Connect SmartThings to Seam

1. Note your login credentials for the SmartThings app.
2. In the form to connect SmartThings to Seam, enter those credentials and click **Submit** to complete.

***

### Troubleshooting

If devices don't appear after connecting your account:

* Verify that each device is online and paired to the SmartThings Hub in the SmartThings app.
* Confirm you're logging in with the correct SmartThings account credentials.


# Get Started with Tedee Locks
Source: https://docs.seam.co/device-and-system-integration-guides/tedee-locks/get-started-with-tedee-locks

Learn how to connect and control your Tedee locks with the Seam API.

## Overview

Seam provides a universal API to connect and control many brands of locks, including Tedee. This guide provides a rapid introduction to connecting and controlling your [Tedee](https://www.seam.co/manufacturers/tedee) locks using the Seam API. To learn more about other device brands supported by the Seam API, such as Yale, Schlage, and August, head over to our [integration page](https://www.seam.co/supported-devices-and-systems).

For more details about the Seam Tedee integration, see the [Tedee locks device integration guide](./).

## 1 — Install Seam SDK

Seam provides client libraries for many languages, such as JavaScript, Python, Ruby, PHP, and others, as well as a Postman collection and [OpenAPI](https://connect.getseam.com/openapi.json) spec.

* JavaScript / TypeScript ([npm](https://www.npmjs.com/package/seam), [GitHub](https://github.com/seamapi/javascript))
* Python ([pip](https://pypi.org/project/seam/), [GitHub](https://github.com/seamapi/python))
* Ruby Gem ([rubygem](https://rubygems.org/gems/seam), [GitHub](https://github.com/seamapi/ruby))
* PHP ([packagist](https://packagist.org/packages/seamapi/seam), [GitHub](https://github.com/seamapi/php))
* C# ([nuget](https://www.nuget.org/packages/Seam), [GitHub](https://github.com/seamapi/csharp))

<Tabs>
  <Tab title="JavaScript">
    ```bash theme={null}
    npm i seam
    ```
  </Tab>

  <Tab title="Python">
    ```bash theme={null}
    pip install seam
    # For some development environments, use pip3 in this command instead of pip.
    ```
  </Tab>

  <Tab title="Ruby">
    ```bash theme={null}
    bundle add seam
    ```
  </Tab>

  <Tab title="PHP">
    ```bash theme={null}
    composer require seamapi/seam
    ```
  </Tab>

  <Tab title="C#">
    Install using [nuget](https://www.nuget.org/packages/Seam).
  </Tab>
</Tabs>

Once installed, [sign up for Seam](https://console.seam.co/) to get your [API key](/core-concepts/authentication/api-keys) and export it as an environment variable.

```
$ export SEAM_API_KEY=seam_test2ZTo_0mEYQW2TvNDCxG5Atpj85Ffw
```

<Info>
  This guide uses a [sandbox
  workspace](/core-concepts/workspaces#sandbox-workspaces).
  You can only connect virtual devices in a sandbox workspace. If you need to
  connect a real Tedee device, use a non-sandbox workspace and API key.
</Info>

## 2 — Link Your Tedee Account with Seam

To control your Tedee locks using the Seam API, you must first authorize your Seam workspace against your Tedee account. To do so, Seam provides[ Connect Webviews](/core-concepts/connect-webviews): pre-built UX flows that walk you through authorizing your application to control your Tedee sites.

### Request a Connect Webview

<CodeGroup>
  ```javascript JavaScript theme={null}
  // Use Seam SDK to create a Connect Webview with tedee as the provider
  const createdConnectWebview = await seam.connectWebviews.create();

  // Print the created webview URL
  console.log(createdConnectWebview.url);

  ```

  ```python Python theme={null}
  # Create a Connect Webview with tedee as the provider
  created_webview = seam.connect_webviews.create()

  # Assert that login is not yet successful
  assert created_webview.login_successful is False

  # Print the URL of the webview
  print(created_webview.url)
  ```

  ```ruby Ruby theme={null}
  # Create a Connect Webview with the tedee as the provider
  created_webview = seam.connect_webviews.create()

  # The webview will not be logged in, which can be confirmed

  raise 'Login should not be succesful' unless !created_webview.login_successful

  # Retrieve and print out the url of the webview

  puts created_webview.url

  ```

  ```php PHP theme={null}
  <?php
  // initiate the SDK client, you should replace this with your SDK client init portion
  $seam = new SeamSeamClient("YOUR_API_KEY");

  // create a Connect Webview with tedee as the provider
  $connect_webview = $seam->connect_webviews->create([
  ]);

  // check if the login was successful
  assert($connect_webview->login_successful === false);

  // print the connect webview URL
  print($connect_webview->url);
  ?>
  ```
</CodeGroup>

### Authorize Your Workspace

Navigate to the URL returned by the Webview object. Since you are using a sandbox workspace, complete the login flow by entering the Tedee [sandbox test accounts ](./sandbox-tedee-locks)credentials below:

* **email:** [jane@example.com](mailto:jane@example.com)
* **password:** 1234

Confirm the Connect Webview was successful by querying its status:

<CodeGroup>
  ```javascript JavaScript theme={null}
  const updatedWebview = await seam.connectWebviews.get(
    connectWebview.connect_webview_id
  )

  console.log(updatedWebview.login_successful) // true

  ```

  ```python Python theme={null}
  updated_webview = seam.connect_webviews.get(connect_webview_id: webview.connect_webview_id)

  assert updated_webview.login_successful # true
  ```

  ```ruby Ruby theme={null}
  updated_webview = seam.connect_webviews.get(connect_webview_id: webview.connect_webview_id)

  puts updated_webview.login_successful # true

  ```

  ```php PHP theme={null}
  $webview = $seam->connect_webviews->get($webview->id);
  echo json_encode($webview);
  ```
</CodeGroup>

## 3 — Retrieve Tedee Devices

After a Tedee account is linked with Seam, you can retrieve devices for this Tedee account. The Seam API exposes most of the device's properties such as battery level.

<CodeGroup>
  ```javascript JavaScript theme={null}
  const allLocks = await seam.locks.list()

  const someLock = allLocks[0]

  console.log(someLock.properties.online) // true
  console.log(someLock.properties.locked) // true

  console.log(someLock)
  /_
  {
  device_id: 'ffc4d67f-e3a6-4ef8-ac84-f3770750422a',
  device_type: 'tedee_lock',
  capabilities_supported: [ 'access_code', 'battery', 'lock' ],
  properties: {
  locked: true,
  online: true,
  manufacturer: 'tedee',
  battery_level: 1,
  tedee_metadata: {
  bridge_id: 1,
  device_id: 1,
  bridge_name: "Jane's Bridge",
  device_name: 'Front Door',
  device_model: 'Lock PRO',
  serial_number: '111111-11111'
  },
  supported_code_lengths: [ 5, 6, 7, 8 ],
  online_access_codes_enabled: true,
  offline_access_codes_enabled: true,
  supports_offline_access_codes: true,
  name: 'Front Door',
  model: {
  display_name: 'Lock PRO',
  manufacturer_display_name: 'Tedee',
  accessory_keypad_supported: false,
  offline_access_codes_supported: false,
  online_access_codes_supported: true
  },
  battery: { level: 1, status: 'full' },
  image_url: 'https://connect.getseam.com/assets/images/devices/unknown-lock.png',
  image_alt_text: 'Placeholder Lock Image',
  code_constraints: [ [Object], [Object] ],
  supports_backup_access_code_pool: true
  },
  location: null,
  connected_account_id: 'f1e093d9-7a11-4d04-8c7e-619a037bd11a',
  workspace_id: '398d80b7-3f96-47c2-b85a-6f8ba21d07be',
  created_at: '2024-02-08T19:47:43.810Z',
  errors: [],
  warnings: [],
  is_managed: true,
  custom_metadata: {}
  }
  _/

  ```

  ```python Python theme={null}
  all_locks = seam.locks.list()

  some_lock = all_locks[0]

  assert some_lock.properties["online"] is True
  assert some_lock.properties["battery_level"] is True

  print(some_lock)
  # Device(device_id='ffc4d67f-e3a6-4ef8-ac84-f3770750422a', device_type='tedee_lock', location=None, properties={'locked': True, 'online': True, 'manufacturer': 'tedee', 'battery_level': 1, 'tedee_metadata': {'bridge_id': 1, 'device_id': 1, 'bridge_name': "Jane's Bridge", 'device_name': 'Front Door', 'device_model': 'Lock PRO', 'serial_number': '111111-11111'}, 'supported_code_lengths': [5, 6, 7, 8], 'online_access_codes_enabled': True, 'offline_access_codes_enabled': True, 'supports_offline_access_codes': True, 'name': 'Front Door', 'model': {'display_name': 'Lock PRO', 'manufacturer_display_name': 'Tedee', 'accessory_keypad_supported': False, 'offline_access_codes_supported': False, 'online_access_codes_supported': True}, 'battery': {'level': 1, 'status': 'full'}, 'image_url': 'https://connect.getseam.com/assets/images/devices/unknown-lock.png', 'image_alt_text': 'Placeholder Lock Image', 'code_constraints': [{'constraint_type': 'no_ascending_or_descending_sequence'}, {'constraint_type': 'at_least_three_unique_digits'}], 'supports_backup_access_code_pool': True}, capabilities_supported=['access_code', 'battery', 'lock'], errors=[], warnings=[], connected_account_id='f1e093d9-7a11-4d04-8c7e-619a037bd11a', workspace_id='398d80b7-3f96-47c2-b85a-6f8ba21d07be', created_at='2024-02-08T19:47:43.810Z', is_managed=True)
  ```

  ```ruby Ruby theme={null}
  some_lock = seam.locks.list.first

  puts some_lock.properties.online # true
  puts some_lock.properties.locked # true

  puts some_lock

  # <Seam::Device:0x00438

  # device_id="ffc4d67f-e3a6-4ef8-ac84-f3770750422a"

  # device_type="tedee_lock"

  # capabilities_supported=["access_code", "battery", "lock"]

  # properties={"locked"=>true, "online"=>true, "manufacturer"=>"tedee", "battery_level"=>1, "tedee_metadata"=>{"bridge_id"=>1, "device_id"=>1, "bridge_name"=>"Jane's Bridge", "device_name"=>"Front Door", "device_model"=>"Lock PRO", "serial_number"=>"111111-11111"}, "supported_code_lengths"=>[5, 6, 7, 8], "online_access_codes_enabled"=>true, "offline_access_codes_enabled"=>true, "supports_offline_access_codes"=>true, "name"=>"Front Door", "model"=>{"display_name"=>"Lock PRO", "manufacturer_display_name"=>"Tedee", "accessory_keypad_supported"=>false, "offline_access_codes_supported"=>false, "online_access_codes_supported"=>true}, "battery"=>{"level"=>1, "status"=>"full"}, "image_url"=>"https://connect.getseam.com/assets/images/devices/unknown-lock.png", "image_alt_text"=>"Placeholder Lock Image", "code_constraints"=>[{"constraint_type"=>"no_ascending_or_descending_sequence"}, {"constraint_type"=>"at_least_three_unique_digits"}], "supports_backup_access_code_pool"=>true}

  # connected_account_id="f1e093d9-7a11-4d04-8c7e-619a037bd11a"

  # workspace_id="398d80b7-3f96-47c2-b85a-6f8ba21d07be"

  # created_at=2024-02-08 19:47:43.81 UTC

  # errors=[]

  # warnings=[]

  # is_managed=true>

  ```

  ```php PHP theme={null}
  use Seam\SeamClient;

  $seam = new SeamClient('YOUR_API_KEY');

  $locks = $seam->locks->list();

  echo json_encode($locks);
  /*
  {"device_id":"ffc4d67f-e3a6-4ef8-ac84-f3770750422a","device_type":"tedee_lock","capabilities_supported":["access_code","battery","lock"],"properties":{"online":true,"name":"Front Door","model":{"display_name":"Lock PRO","manufacturer_display_name":"Tedee","offline_access_codes_supported":false,"online_access_codes_supported":true,"accessory_keypad_supported":false},"has_direct_power":null,"battery_level":1,"battery":{"level":1,"status":"full"},"manufacturer":"tedee","image_url":"https:\/\/connect.getseam.com\/assets\/images\/devices\/unknown-lock.png","image_alt_text":"Placeholder Lock Image","serial_number":null,"online_access_codes_enabled":true,"offline_access_codes_enabled":true,"supports_accessory_keypad":null,"supports_offline_access_codes":true,"august_metadata":null,"avigilon_alta_metadata":null,"schlage_metadata":null,"smartthings_metadata":null,"lockly_metadata":null,"nuki_metadata":null,"kwikset_metadata":null,"salto_metadata":null,"genie_metadata":null,"brivo_metadata":null,"igloo_metadata":null,"noiseaware_metadata":null,"minut_metadata":null,"four_suites_metadata":null,"two_n_metadata":null,"controlbyweb_metadata":null,"ttlock_metadata":null,"seam_bridge_metadata":null,"igloohome_metadata":null,"nest_metadata":null,"ecobee_metadata":null,"dormakaba_oracode_metadata":null,"wyze_metadata":null,"code_constraints":[{"constraint_type":"no_ascending_or_descending_sequence","min_length":null,"max_length":null},{"constraint_type":"at_least_three_unique_digits","min_length":null,"max_length":null}],"supported_code_lengths":[5,6,7,8],"max_active_codes_supported":null,"supports_backup_access_code_pool":true,"has_native_entry_events":null,"locked":true,"keypad_battery":null,"door_open":null,"temperature_fahrenheit":null,"temperature_celsius":null,"relative_humidity":null,"available_hvac_mode_settings":null,"is_heating":null,"is_cooling":null,"is_fan_running":null,"fan_mode_setting":null,"is_temporary_manual_override_active":null,"current_climate_setting":null,"is_climate_setting_schedule_active":null,"active_climate_setting_schedule":null,"min_cooling_set_point_celsius":null,"min_cooling_set_point_fahrenheit":null,"max_cooling_set_point_celsius":null,"max_cooling_set_point_fahrenheit":null,"min_heating_set_point_celsius":null,"min_heating_set_point_fahrenheit":null,"max_heating_set_point_celsius":null,"max_heating_set_point_fahrenheit":null,"min_heating_cooling_delta_celsius":null,"min_heating_cooling_delta_fahrenheit":null,"assa_abloy_credential_service_metadata":null},"location":null,"connected_account_id":"f1e093d9-7a11-4d04-8c7e-619a037bd11a","workspace_id":"398d80b7-3f96-47c2-b85a-6f8ba21d07be","errors":[],"warnings":[],"created_at":"2024-02-08T19:47:43.810Z","is_managed":true,"custom_metadata":{}}
  */
  ```
</CodeGroup>

### 4 — Locking & Unlocking a Door

Next, you can perform the basic action of locking and unlocking a door.

<mark>`POST`</mark> `undefined/locks/lock_door`

## Unlock a door

<mark>`POST`</mark>
`https://connect.getseam.com/locks/unlock_door`

#### Request Body

| Name       | Type   | Description |
| ---------- | ------ | ----------- |
| device\_id | String |             |

<CodeGroup>
  ```javascript JavaScript theme={null}
  // lock the door
  await seam.locks.lockDoor(someLock.device_id)
  const updatedLock = await seam.locks.get(someLock.device_id)
  console.log(updatedLock.properties.locked) // true

  // unlock the door
  await seam.locks.unlockDoor(someLock.device_id)
  updatedLock = await seam.locks.get(someLock.device_id)
  console.log(updatedLock.properties.locked) // false

  ```

  ```python Python theme={null}
  # lock the door
  seam.locks.lock_door(device_id: some_lock.device_id)
  updated_lock = seam.locks.get(device_id: some_lock.device_id)
  assert updated_lock.properties["locked"] is True

  # Now unlock the door
  seam.locks.unlock_door(device_id: some_lock.device_id)
  updated_lock = seam.locks.get(device_id: some_lock.device_id)
  assert updated_lock.properties["locked"] is False
  ```

  ```ruby Ruby theme={null}
  # lock the door
  seam.locks.lock_door(device_id: some_lock.device_id)
  updated_lock = seam.locks.get(device_id: some_lock.device_id)
  puts updated_lock.properties.locked # true

  # unlock the door

  seam.locks.unlock_door(device_id: some_lock.device_id)
  updated_lock = seam.locks.get(device_id: some_lock.device_id)
  puts updated_lock.properties.locked # false

  ```

  ```php PHP theme={null}
  use Seam\SeamClient;

  $seam = new SeamClient('YOUR_API_KEY');

  $some_lock = $seam->locks->list()[0];

  # unlock the door
  $seam->locks->unlock_door($lock->device_id);
  # lock the door
  $seam->locks->lock_door($lock->device_id);
  ```
</CodeGroup>

### 5 — Setting Access Code on Tedee Lock

Some Tedee locks also have a keypad paired to them to program access codes. These codes can then be entered to unlock a Tedee lock.

The Seam API makes it easy to program both `ongoing` codes and `timebound` codes on a Tedee lock. You can find out more about Tedee lock access code in our [core concept section on access codes.](/low-level-apis/smart-locks/access-codes)

<Info>
  For Tedee-specific access code restrictions, see [Access (PIN) Code
  Requirements](/device-and-system-integration-guides/tedee-locks#brand-specific-access-pin-code-requirements).
</Info>

<CodeGroup>
  ```javascript JavaScript theme={null}
  // create an ongoing code
  await seam.accessCodes.create({
    device_id: someLock.device_id,
    code: "123456",
    name: "Personal Access Code",
  })

  // create a timebound code
  await seam.accessCodes.create({
  device_id: someLock.device_id,
  code: "888888",
  name: "My Temp Access Code",
  starts_at: "2028-11-12T19:23:42+0000",
  ends_at: "2028-11-13T19:23:42+0000",
  })

  // use a device_id as the "device_id" parameter
  await seam.accessCodes.list({
  device_id: someLock.device_id,
  })

  ```

  ```python Python theme={null}
  # create an ongoing code
  seam.access_codes.create(
    device=some_lock,
    code="492332",
    name="Personal Access Code")

  # create a timebound code
  seam.access_codes.create(
    device=some_lock,
    code="498882",
    name="My Temp Access Code",
    starts_at="2028-08-12T19:23:42+0000",
    ends_at="2028-08-13T19:23:42+0000")

  # you can use a device or a device_id as the "device" parameter
  seam.access_codes.list(device=some_lock)
  ```

  ```ruby Ruby theme={null}
  # create an ongoing code
  seam.access_codes.create(
    device_id: some_lock.device_id, code: '123456', name: 'Personal Access Code'
  )

  # create a timebound code

  seam.access_codes.create(
  device_id: some_lock.device_id,
  code: '888888',
  name: 'My Temp Access Code',
  starts_at: '2028-08-12T19:23:42+0000',
  ends_at: '2028-08-13T19:23:42+0000'
  )

  seam.access_codes.list(device_id: some_lock.device_id)

  ```

  ```php PHP theme={null}
  use Seam\SeamClient;

  $seam = new SeamClient("YOUR_API_KEY");

  $some_lock = $seam->locks->list()[0];
  $seam->access_codes->create(
    device_id: $some_lock->device_id, code: '123456', name: 'Personal Access Code'
  );

  $seam->access_codes->create(
    device_id: $some_lock->device_id,
    name: 'My Temp Access Code',
    code: '888888',
    starts_at: '2028-08-12T19:23:42+0000',
    ends_at: '2028-08-13T19:23:42+0000'
  );

  ```
</CodeGroup>

## Next Steps

Now that you've completed this guide, you can try to connect a real Tedee device. To do so, make sure to switch to a non-sandbox workspace and API key as real devices cannot be connected to sandbox workspaces.

In addition, if you'd like to explore other aspects of Seam, here is a list of helpful resources:

* [Schlage Getting Started Guide](../schlage-locks/get-started-with-schlage-locks)
* [Yale Getting Started Guide](../yale-locks/get-started-with-yale-locks)
* [SmartThings Getting Started Guide](../smartthings-hubs-+-devices/get-started-with-smartthings-hubs-+-smart-locks)
* [Receiving webhook](/developer-tools/webhooks) for [device events](/api/events/list)
* [Core Concepts](/core-concepts/overview)

If you have any questions or want to report an issue, email us at [support@seam.co](mailto:support@seam.co).


# Tedee Locks
Source: https://docs.seam.co/device-and-system-integration-guides/tedee-locks/index

Guide for using Tedee locks with Seam

<img alt="Tedee logo" />

## Overview

Tedee produces smart locks and accompanying products for the residential, rental, and business markets. Seam integrates with Tedee locks through the Wi-Fi-enabled Tedee smart bridge to provide app-based, remote locking and unlocking, as well as access sharing. In addition, Seam provides permanent, temporary, and scheduled access (PIN) code programming for Tedee locks with the Tedee keypad (and Tedee bridge). Tedee smart locks attach to existing locks, using either a Tedee hardware adapter or Tedee modular European cylinder.

***

## Supported Devices

<DeviceList />

This integration supports all Tedee smart lock models that are connected to Wi-Fi through the [Tedee smart bridge](https://tedee.com/product-info/bridge/#image-1). Seam also supports the addition of the optional [Tedee keypad](https://tedee.com/product-info/keypad/#image-1) to enable entering access codes to control the lock.

The following table details the requirements for compatibility with this Seam integration:

<table>
  <thead>
    <tr>
      <th>Capability</th>
      <th>Required Accessories</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Remote lock/unlock</td>

      <td>
        <ul>
          <li>Tedee smart bridge</li>
        </ul>
      </td>
    </tr>

    <tr>
      <td>Access codes</td>

      <td>
        <ul>
          <li>Tedee smart bridge</li>
          <li>Tedee keypad</li>
        </ul>
      </td>
    </tr>
  </tbody>
</table>

For detailed information about the Tedee devices that Seam supports, see our [Tedee Supported Devices page](https://www.seam.co/manufacturers/tedee).

***

## Supported Features

We support the following features:

* [Triggering web lock and unlock actions](/low-level-apis/smart-locks/lock-and-unlock)
* [Programming access codes](/low-level-apis/smart-locks/access-codes) on locks and openers that have an installed Tedee keypad

***

### Device Provider Key

Seam identifies these devices with the `tedee` device provider key. By default, a [Connect Webview](/core-concepts/connect-webviews) displays all of the stable providers that Seam supports, so your users can connect their Tedee devices without you specifying a provider list. To narrow what a Connect Webview displays, see [Customize the Brands to Display in Your Connect Webviews](/core-concepts/connect-webviews/customizing-connect-webviews#customize-the-brands-to-display-in-your-connect-webviews).

***

## Setup Instructions

For instructions on connecting Tedee locks to Seam, see the [Tedee Setup Guide](./tedee-setup-guide).

***

## Brand-Specific Access (PIN) Code Requirements

Tedee imposes the following PIN code requirements:

* The PIN code cannot be null, empty, or whitespace.
* The PIN length must be five-eight characters.
* The PIN can contain only numeric values (0-9).
* The PIN must contain at least three different digits.
* The PIN cannot be built as an ascending or descending sequence.

***

## Where to Order

To purchase Tedee devices, visit the Tedee online store.

<table>
  <thead>
    <tr>
      <th />

      <th />

      <th />

      <th />

      <th />
    </tr>
  </thead>

  <tbody>
    <tr>
      <td />

      <td>
        <strong>Tedee Online Store</strong>
      </td>

      <td />

      <td>
        <a href="https://tedee.com/shop/">[https://tedee.com/shop/](https://tedee.com/shop/)</a>
      </td>

      <td>
        <a href="/images/tedee-logo.png">tedee-logo.png</a>
      </td>
    </tr>
  </tbody>
</table>

***


# Sandbox Tedee Locks
Source: https://docs.seam.co/device-and-system-integration-guides/tedee-locks/sandbox-tedee-locks

Add virtual Tedee locks to your Seam sandbox workspace using these sample credentials to test your integration without real hardware.

Use the following set of credentials to add virtual [Tedee locks](/device-and-system-integration-guides/tedee-locks) to your Seam [sandbox workspace](/core-concepts/workspaces#sandbox-workspaces):

| Email Address                               | Password |
| ------------------------------------------- | -------- |
| [jane@example.com](mailto:jane@example.com) | 1234     |


# Tedee Setup Guide
Source: https://docs.seam.co/device-and-system-integration-guides/tedee-locks/tedee-setup-guide

Connect your Tedee locks to Seam.

To use Seam with Tedee locks, ask the device owner to complete the steps below. Locks must already be installed and connected to a Tedee smart bridge before proceeding.

### 1. Set up the Tedee mobile app

1. Download and install the [Tedee mobile app](https://tedee.com/knowledge-base/tedee-app/) and create an account if you don't have one.
2. In the Tedee app, add your Tedee devices.

<Info>
  You must add your Tedee devices through the Tedee mobile app. You cannot add
  devices through the Tedee web portal.
</Info>

### 2. Connect Tedee to Seam

1. Note your login credentials for the Tedee app.
2. In the form to connect Tedee to Seam, enter those credentials and click **Submit** to complete.

***

### Troubleshooting

If devices don't appear after connecting your account:

* Verify that each lock is online and connected to a Tedee smart bridge in the Tedee app.
* Confirm you added your devices through the Tedee mobile app, not the web portal.


# Get started with TTLock Locks
Source: https://docs.seam.co/device-and-system-integration-guides/ttlock-locks/get-started-with-ttlock-devices

Learn how to connect and control TTLock locks with the Seam API.

## Overview

Seam provides a universal API to connect and control many brands of IoT devices and systems, including smart locks, access control systems (ACSs), thermostats, and noise sensors.

This guide gives you a rapid introduction to connecting and controlling your [TTLock lock](./) using the Seam API. For application developers, you can use the Seam API in your app, and your users can authorize your app to control their devices using Seam.

For detailed information about the TTLock devices that Seam supports, see our [TTLock Supported Devices page](https://www.seam.co/manufacturers/ttlock).

To learn more about other IoT device and system brands that Seam supports—such as Yale, Schlage, Google Nest, and many more—visit our [integration page](https://www.seam.co/supported-devices-and-systems).

<Check>
  This guide shows you how to install a Seam SDK and then control your TTLock lock using the Seam API.

  Another easy way to learn about what you can do with the Seam API is to explore the [interactive Seam CLI](/core-concepts/seam-console/seam-online-cli), which you can access from directly within the [Seam Console](/core-concepts/seam-console).

  :arrow\_forward: [Go to the Seam Console!](https://console.seam.co/)
</Check>

***

## Step 1: Install a Seam SDK

Seam provides client libraries for many languages, including JavaScript, Python, Ruby, PHP, and others, as well as a Postman collection and an [OpenAPI](https://connect.getseam.com/openapi.json) spec.

* JavaScript / TypeScript ([npm](https://www.npmjs.com/package/seam), [GitHub](https://github.com/seamapi/javascript))
* Python ([pip](https://pypi.org/project/seam/), [GitHub](https://github.com/seamapi/python))
* Ruby Gem ([rubygem](https://rubygems.org/gems/seam), [GitHub](https://github.com/seamapi/ruby))
* PHP ([packagist](https://packagist.org/packages/seamapi/seam), [GitHub](https://github.com/seamapi/php))
* C# ([nuget](https://www.nuget.org/packages/Seam), [GitHub](https://github.com/seamapi/csharp))

First, install a Seam SDK, as follows:

<Tabs>
  <Tab title="JavaScript">
    ```bash theme={null}
    npm i seam
    ```
  </Tab>

  <Tab title="Python">
    ```bash theme={null}
    pip install seam
    # For some development environments, use pip3 in this command instead of pip.
    ```
  </Tab>

  <Tab title="Ruby">
    ```bash theme={null}
    bundle add seam
    ```
  </Tab>

  <Tab title="PHP">
    ```bash theme={null}
    composer require seamapi/seam
    ```
  </Tab>

  <Tab title="C#">
    Install using [nuget](https://www.nuget.org/packages/Seam).
  </Tab>
</Tabs>

Next, go to [https://console.seam.co/](https://console.seam.co/) and [sign up for Seam](/core-concepts/seam-console#create-a-seam-account) to get your [API key](/core-concepts/authentication/api-keys).

Then, export your API key as an environment variable.

```bash theme={null}
$ export SEAM_API_KEY=seam_test2bMS_94SrGUXuNR2JmJkjtvBQDg5c
```

<Info>
  This guide uses a [sandbox
  workspace](/core-concepts/workspaces#sandbox-workspaces).
  You can only connect virtual devices and systems in this type of workspace. If
  you want to connect a real TTLock lock, use a [non-sandbox
  workspace](/core-concepts/workspaces#production-workspaces)
  and API key.
</Info>

***

## Step 2: Link your TTLock account with Seam

To control your TTLock lock using the Seam API, you must first authorize your Seam workspace to connect to your TTLock account. If your application needs to connect to your users' TTLock accounts, Seam provides fully-embedded, [customizable](/core-concepts/connect-webviews/customizing-connect-webviews) client-side [Connect Webviews](/core-concepts/connect-webviews) to collect their authorization securely. These user-friendly pre-built authorization flows walk your users through the process of granting your Seam workspace permission to control their TTLock locks. The Connect Webview presents a flow that prompts your users to enter their credentials for their TTLock account.

In this guide, you create a Connect Webview object. Then, you display the graphical component of the created Connect Webview and enter a set of sample credentials to connect a sandbox TTLock account.

<Check>
  This guide shows you how to create a Connect Webview programmatically using the Seam API.

  The [Seam Console](/core-concepts/seam-console) provides another easy way to connect devices to your Seam workspace.

  Go to [https://console.seam.co/](https://console.seam.co/). On the **Devices** page, click **+ Add Devices**. Then, see [Authorize your workspace](#authorize-your-workspace) in this guide to complete the Connect Webview authorization flow.

  <img alt="You can also use the Seam Console to add devices." />
</Check>

### Create a Connect Webview

Create a `connect_webview` object and then note the returned URL.

**Code:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  import { Seam } from 'seam'

  const seam = new Seam() // Seam automatically uses your exported SEAM_API_KEY.

  const connectWebview = await seam.connectWebviews.create()

  console.log(connectWebview.login_successful) // false

  // Use the returned Connect Webview URL to display
  // the Connect Webview authorization flow to your user.
  console.log(connectWebview.url)
  ```

  ```bash cURL theme={null}
  curl -X 'POST' \
    'https://connect.getseam.com/connect_webviews/create' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d '{}' | jq -r '"Login Successful (false): " + (.connect_webview.login_successful | tostring),
    "URL: " + .connect_webview.url'
    # Use the returned Connect Webview URL to display
    # the Connect Webview authorization flow to your user.
  ```

  ```python Python theme={null}
  from seam import Seam

  seam = Seam()  # Seam automatically uses your exported SEAM_API_KEY.

  connect_webview = seam.connect_webviews.create()

  assert connect_webview.login_successful is False

  # Use the returned Connect Webview URL to display
  # the Connect Webview authorization flow to your user.
  print(connect_webview.url)
  ```

  ```ruby Ruby theme={null}
  require "seam"

  seam = Seam.new() # Seam automatically uses your exported SEAM_API_KEY.

  connect_webview = seam.connect_webviews.create()

  puts connect_webview.login_successful # false

  # Use the returned Connect Webview URL to display
  # the Connect Webview authorization flow to your user.
  puts connect_webview.url
  ```

  ```php PHP theme={null}
  <?php
  require 'vendor/autoload.php';

  $seam = new Seam\SeamClient(); // Seam automatically uses your exported SEAM_API_KEY.

  $connect_webview = $seam->connect_webviews->create();

  echo $connect_webview->login_successful ? 'true' : 'false', "\n"; // false

  // Use the returned Connect Webview URL to display
  // the Connect Webview authorization flow to your user.
  echo $connect_webview->url;
  ```

  ```csharp C# theme={null}
  using Seam.Client;

  var seam = new SeamClient(apiToken: SEAM_API_KEY);

  var connectWebview = seam.ConnectWebviews.Create();

  Console.WriteLine(connectWebview.LoginSuccessful); // False

  // Use the returned Connect Webview URL to display
  // the Connect Webview authorization flow to your user.
  Console.WriteLine(connectWebview.Url);
  ```
</CodeGroup>

**Output:**

<CodeGroup>
  ```json JavaScript theme={null}
  false
  https://connect.getseam.com/connect_webviews/view?connect_webview_id=12345678-1234-1234-1234-123456789012&auth_token=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
  ```

  ```json cURL theme={null}
  Login Successful (false): false
  https://connect.getseam.com/connect_webviews/view?connect_webview_id=12345678-1234-1234-1234-123456789012&auth_token=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
  ```

  ```json Python theme={null}
  https://connect.getseam.com/connect_webviews/view?connect_webview_id=12345678-1234-1234-1234-123456789012&auth_token=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
  ```

  ```json Ruby theme={null}
  false
  https://connect.getseam.com/connect_webviews/view?connect_webview_id=12345678-1234-1234-1234-123456789012&auth_token=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
  ```

  ```json PHP theme={null}
  false
  https://connect.getseam.com/connect_webviews/view?connect_webview_id=12345678-1234-1234-1234-123456789012&auth_token=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
  ```

  ```json C# theme={null}
  False
  https://connect.getseam.com/connect_webviews/view?connect_webview_id=12345678-1234-1234-1234-123456789012&auth_token=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
  ```
</CodeGroup>

***

### Authorize your workspace

In a web browser, go to the URL that the Connect Webview object returned.

For application developers, you can redirect your user to this Connect Webview URL so that they can authorize your app to control their devices using Seam. We even provide a prebuilt [Connect Account Button](/ui-components/overview/react-components/connect-account-button) within our suite of [Seam Components](/ui-components/overview) that help you build your device management flow.

<Check>
  Because you're using a sandbox workspace, you can connect Seam's test TTLock
  account. We provide [virtual devices](./ttlock-sample-data) for each of the
  brands that we support. These sandbox devices and systems enable you to test
  your app with devices from multiple brands without the need to own all the
  corresponding physical devices.
</Check>

Complete the Connect Webview authorization flow by entering the following [TTLock sandbox account](./ttlock-sample-data) credentials:

* **Email:** [jane@example.com](mailto:jane@example.com)
* **Password:** 1234

<picture>
  <source />

  <img alt="Use the Seam Connect Webview authorization flow to connect a TTLock account with Seam. This flow varies slightly based on the device manufacturer and region." />
</picture>

Confirm that authorization through the Connect Webview was successful by querying its status.

**Code:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  const updatedConnectWebview = await seam.connectWebviews.get({
    connect_webview_id: connectWebview.connect_webview_id,
  })

  console.log(updatedConnectWebview.login_successful) // true
  ```

  ```bash cURL theme={null}
  curl -X 'POST' \
    'https://connect.getseam.com/connect_webviews/get' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d "{
    \"connect_webview_id\": \"${connect_webview_id}\"
  }" | jq -r '"Login Successful (true): " + (.connect_webview.login_successful | tostring)'
  ```

  ```python Python theme={null}
  updated_connect_webview = seam.connect_webviews.get(connect_webview.connect_webview_id)

  assert updated_connect_webview.login_successful is True # True
  ```

  ```ruby Ruby theme={null}
  updated_connect_webview = seam.connect_webviews.get(
    connect_webview_id: connect_webview.connect_webview_id
  )

  puts updated_connect_webview.login_successful # true
  ```

  ```php PHP theme={null}
  $updated_connect_webview = $seam->connect_webviews->get(
    connect_webview_id: $connect_webview->connect_webview_id
  );

  echo $updated_connect_webview->login_successful ? 'true' : 'false', "\n"; // true
  ```

  ```csharp C# theme={null}
  var updatedConnectWebview = seam.ConnectWebviews.Get(
    connectWebviewId: connectWebview.connectWebviewId
  );

  Console.WriteLine(updatedConnectWebview.LoginSuccessful); // True
  ```
</CodeGroup>

**Output:**

<CodeGroup>
  ```json JavaScript theme={null}
  true
  ```

  ```json cURL theme={null}
  Login Successful (true): true
  ```

  ```json Python theme={null}
  True
  ```

  ```json Ruby theme={null}
  true
  ```

  ```json PHP theme={null}
  true
  ```

  ```json C# theme={null}
  True
  ```
</CodeGroup>

***

## Step 3: Retrieve TTLock lock devices

When you link a TTLock account with Seam, we create a `device` object to represent each TTLock lock in your account. You can then retrieve these TTLock devices using the [List Devices](/api/devices/list) and [Get Device](/api/devices/get) endpoints.

The Seam API exposes each device's properties, such as the door lock status, power status, capabilities, and so on.

**Code:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  // Retrieve all devices, filtered by manufacturer,
  // which is one of several filters that list() supports.
  const allTtlockLocks = await seam.devices.list({ manufacturer: 'ttlock' })

  // Select the first device as an example.
  const frontDoor = allTtlockLocks[0]

  // Inspect specific properties.
  console.log(frontDoor.properties.online) // true
  console.log(frontDoor.properties.locked) // true

  // View the entire returned device object.
  console.log(frontDoor)
  ```

  ```bash cURL theme={null}
  # Retrieve all devices, filtered by manufacturer, which is
  # one of several filters that the list endpoint supports.
  all_ttlock_locks=$(
    # Use GET or POST.
    curl -X 'GET' \
      'https://connect.getseam.com/devices/list' \
      -H 'accept: application/json' \
      -H "Authorization: Bearer ${SEAM_API_KEY}" \
      -H 'Content-Type: application/json' \
      -d '{
      "manufacturer": "ttlock"
    }')

  # Select the first device as an example.
  front_door=$(jq -r '.devices[0]' <<< ${all_ttlock_locks})

  # Inspect specific properties.
  echo $(jq -r '"Online (true): " + (.properties.online | tostring)' <<< ${front_door})
  echo $(jq -r '"Locked (true): " + (.properties.locked | tostring)' <<< ${front_door})

  # View the entire returned device object.
  echo ${front_door}
  ```

  ```python Python theme={null}
  # Retrieve all devices, filtered by manufacturer,
  # which is one of several filters that list() supports.
  all_ttlock_locks = seam.devices.list(manufacturer="ttlock")

  # Select the first device as an example.
  front_door = all_ttlock_locks[0]

  # Inspect specific properties.
  assert front_door.properties["online"] is True # True
  assert front_door.properties["locked"] is True # True

  # View the entire returned device object.
  pprint(front_door)
  ```

  ```ruby Ruby theme={null}
  # Retrieve all devices, filtered by manufacturer,
  # which is one of several filters that list() supports.
  all_ttlock_locks = seam.devices.list(manufacturer: "ttlock")

  # Select the first device as an example.
  front_door = all_ttlock_locks[0]

  # Inspect specific properties.
  puts front_door.properties.online # true
  puts front_door.properties.locked # true

  # View the entire returned device object.
  puts front_door.inspect
  ```

  ```php PHP theme={null}
  // Retrieve all devices, filtered by manufacturer,
  // which is one of several filters that list() supports.
  $all_ttlock_locks = $seam->devices->list(manufacturer: "ttlock");

  // Select the first device as an example.
  $front_door = $all_ttlock_locks[0];

  // Inspect specific properties.
  echo $front_door->properties->online ? 'true' : 'false', "\n"; // true
  echo $front_door->properties->locked ? 'true' : 'false', "\n"; // true

  // View the entire returned device object.
  echo json_encode($front_door, JSON_PRETTY_PRINT);
  ```

  ```csharp C# theme={null}
  // Retrieve all devices, filtered by manufacturer,
  // which is one of several filters that list() supports.
  var allTtlockLocks = seam.Devices.List(
    manufacturer: Seam.Api.Devices.ListRequest.ManufacturerEnum.Ttlock
  );

  // Select the first device as an example.
  Device frontDoor = allTtlockLocks[0];

  // Inspect specific properties.
  Console.WriteLine(frontDoor.Properties.Online); // true
  Console.WriteLine(frontDoor.Properties.Locked); // true

  // View the entire returned device object.
  Console.WriteLine(frontDoor);
  ```
</CodeGroup>

**Output:**

<CodeGroup>
  ```json JavaScript theme={null}
  true
  true
  {
    device_id: '11111111-1111-1111-1111-444444444444',
    display_name: 'Lock 1',
    workspace_id: '00000000-0000-0000-0000-000000000000',
    connected_account_id: '11111111-1111-1111-1111-222222222222',
    created_at: '2024-05-29T20:08:48.878Z',
    properties: {
      manufacturer: 'ttlock',
      online: true,
      locked: true,
      battery: {
        level: 0.9999532347993827,
        status: 'full'
      },
      ...
    },
    can_remotely_unlock: true,
    ...
  }
  ```

  ```json cURL theme={null}
  Online (true): true
  Locked (true): true
  {
    "device_id": "11111111-1111-1111-1111-444444444444",
    "display_name": "Lock 1",
    "workspace_id": "00000000-0000-0000-0000-000000000000",
    "connected_account_id": "11111111-1111-1111-1111-222222222222",
    "created_at": "2024-05-29T20:08:48.878Z",
    "properties": {
      "manufacturer": "ttlock",
      "locked": true,
      "online": true,
      "battery": {
        "level": 0.9999532347993827,
        "status": "full"
      },
      ...
    },
    "can_remotely_unlock": true,
    ...
  }
  ```

  ```json Python theme={null}
  Device(
    device_id='11111111-1111-1111-1111-444444444444',
    display_name='Lock 1',
    workspace_id='00000000-0000-0000-0000-000000000000'
    connected_account_id='11111111-1111-1111-1111-222222222222',
    created_at='2024-05-29T20:08:48.878Z',
    properties={
      'manufacturer': 'ttlock',
      'online': True,
      'locked': True,
      'battery': {
        'level': 0.9999532347993827,
        'status': 'full'
      },
      ...
    }
    can_remotely_unlock=True,
    ...
  )
  ```

  ```json Ruby theme={null}
  true
  true
  <
    Seam::Device:0x00438
      device_id="11111111-1111-1111-1111-444444444444"
      display_name="Lock 1"
      workspace_id="00000000-0000-0000-0000-000000000000"
      connected_account_id="11111111-1111-1111-1111-222222222222"
      created_at=2024-05-29 20:08:48.878 UTC
      properties={
        "manufacturer"=>"ttlock",
        "online"=>true,
        "locked"=>true,
        "battery"=>{
          "level"=>0.9999532347993827,
          "status"=>"full"
        },
        ...
      }
      can_remotely_unlock=true
      ...
  >
  ```

  ```json PHP theme={null}
  true
  true
  {
    "device_id": "11111111-1111-1111-1111-444444444444",
    "display_name": "Lock 1",
    "workspace_id": "00000000-0000-0000-0000-000000000000"
    "connected_account_id": "11111111-1111-1111-1111-222222222222",
    "created_at": "2024-05-29T20:08:48.878Z",
    "properties": {
      "manufacturer": "ttlock",
      "online": true,
      "locked": true,
      "battery": {
        "level": 0.9999532347993827,
        "status": "full"
      },
      ...
    },
    "can_remotely_unlock": true,
    ...
  }
  ```

  ```json C# theme={null}
  True
  True
  {
    "device_id": "11111111-1111-1111-1111-444444444444",
    "display_name": "Lock 1",
    "workspace_id": "00000000-0000-0000-0000-000000000000",
    "connected_account_id": "11111111-1111-1111-1111-222222222222",
    "created_at": "2024-05-29T20:08:48.878Z",
    "properties": {
      "manufacturer": "ttlock",
      "online": true,
      "locked": true,
      "battery": {
        "level": 0.9999532,
        "status": "full"
      },
      ...
    },
    "can_remotely_unlock": true,
    ...
  }
  ```
</CodeGroup>

***

## Step 4: Control your TTLock lock

Next, you can use the Seam API to control your lock.

Each device that you connect to Seam has a specific set of capabilities. These capabilities define the Seam API actions that you can use, such as [remote unlock actions](/low-level-apis/smart-locks/lock-and-unlock), [programming access codes](/low-level-apis/smart-locks/access-codes), and so on. Seam's intuitive and granular [capability flags](/capability-guides/device-and-system-capabilities#capability-flags) inform your application about what features and behaviors each device supports. Notice the capability flags within the code samples in this guide.

Try out the following actions on your TTLock lock:

* [ ] [Unlock your lock](#unlock-your-lock)
* [ ] [Program access codes on your lock](#program-access-codes-on-your-lock)

### Unlock your lock

To unlock a door, use the [Unlock Door](/api/locks/unlock_door) endpoint. Specify the device that you want to unlock by including the `device_id` in the request body. This endpoint returns an [action attempt](/core-concepts/action-attempts) to track the progress of the unlock operation.

**Code:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  // Confirm that the device can remotely unlock.
  // You're using a capability flag here!
  if (frontDoor.can_remotely_unlock) {
    // Perform the unlock operation
    // and return an action attempt.
    const actionAttempt = await seam.locks.unlockDoor({
      device_id: frontDoor.device_id,
    })
  }
  ```

  ```bash cURL theme={null}
  # Confirm that the device can remotely unlock.
  # You're using a capability flag here!
  if  $(jq -r '.can_remotely_lock' <<< ${front_door}); then \
    # Perform the unlock operation
    # and return an action attempt.
    curl -X 'POST' \
      'https://connect.getseam.com/locks/unlock_door' \
      -H 'accept: application/json' \
      -H "Authorization: Bearer ${SEAM_API_KEY}" \
      -H 'Content-Type: application/json' \
      -d "{
        \"device_id\": \"$(jq -r '.device_id' <<< ${front_door})\"
    }";
  fi
  ```

  ```python Python theme={null}
  # Confirm that the device can remotely unlock.
  # You're using a capability flag here!
  if front_door.can_remotely_unlock:
    # Perform the unlock operation
    # and return an action attempt.
    action_attempt=seam.locks.unlock_door(device_id=front_door.device_id)
  ```

  ```ruby Ruby theme={null}
  # Confirm that the device can remotely unlock.
  # You're using a capability flag here!
  if (front_door.can_remotely_unlock)
    # Perform the unlock operation
    # and return an action attempt.
    action_attempt = seam.locks.unlock_door(device_id: front_door.device_id)
  end
  ```

  ```php PHP theme={null}
  // Confirm that the device can remotely unlock.
  // You're using a capability flag here!
  if ($front_door->can_remotely_unlock) {
    // Perform the unlock operation
    // and return an action attempt.
    $action_attempt = $seam->locks->unlock_door(device_id: $front_door->device_id);
  }
  ```

  ```csharp C# theme={null}
  // Confirm that the device can remotely unlock.
  // You're using a capability flag here!
  if (frontDoor.CanRemotelyUnlock == true) {
    // Perform the unlock operation
    // and return an action attempt.
    ActionAttempt actionAttempt = seam.Locks.UnlockDoor(deviceId: frontDoor.DeviceId);
  }
  ```
</CodeGroup>

**Output:**

<CodeGroup>
  ```json JavaScript theme={null}
  {
    "actionAttempt": {
      "status": "success",
      "action_attempt_id": "11111111-2222-3333-4444-555555555555",
      "action_type": "UNLOCK_DOOR",
      "result": {},
      "error": null
    }
  }
  ```

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

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

  ```json Ruby theme={null}
  <Seam::ActionAttempt:0x00438
    status="pending"
    action_type="UNLOCK_DOOR"
    action_attempt_id="11111111-2222-3333-4444-555555555555"
    result=nil>
  ```

  ```json PHP theme={null}
  {
    "action_attempt_id": "11111111-2222-3333-4444-555555555555",
    "action_type": "UNLOCK_DOOR",
    "error": null,
    "result": {},
    "status": "success"
  }
  ```

  ```json C# theme={null}
  {
    "status": "pending",
    "action_type": "UNLOCK_DOOR",
    "action_attempt_id": "11111111-2222-3333-4444-555555555555"
  }
  ```
</CodeGroup>

You can track the status of the unlock operation to confirm that the device unlocked successfully. Query the `locked` status of the device, [retrieve the action attempt](/api/action_attempts/get) by ID, or look for a [`lock.unlocked` event](/api/locks/events#lock-unlocked).

To query the `locked` status of the device:

**Code:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  // Get the device by ID.
  const updatedFrontDoor = await seam.devices.get({
    device_id: frontDoor.device_id,
  })

  // Inspect the locked property to confirm
  // that the unlock operation was successful.
  console.log(updatedFrontDoor.properties.locked) // false
  ```

  ```bash cURL theme={null}
  # Get the device by ID.
  updated_front_door=$(
    # Use GET or POST.
    curl -X 'GET' \
      'https://connect.getseam.com/devices/get' \
      -H 'accept: application/json' \
      -H "Authorization: Bearer ${SEAM_API_KEY}" \
      -H 'Content-Type: application/json' \
      -d "{
        \"device_id\": \"$(jq -r '.device_id' <<< ${front_door})\"
    }")

  # Inspect the locked property to confirm
  # that the unlock operation was successful.
  echo $(jq -r '"Locked (false): " + (.device.properties.locked | tostring)' <<< ${updated_front_door})
  ```

  ```python Python theme={null}
  # Get the device by ID.
  updated_front_door = seam.devices.get(device_id=front_door.device_id)

  # Inspect the locked property to confirm
  # that the unlock operation was successful.
  assert updated_front_door.properties["locked"] is False # False
  ```

  ```ruby Ruby theme={null}
  # Get the device by ID.
  updated_front_door = seam.devices.get(device_id: front_door.device_id)

  # Inspect the locked property to confirm
  # that the unlock operation was successful.
  puts updated_front_door.properties.locked # false
  ```

  ```php PHP theme={null}
  // Get the device by ID.
  $updated_front_door = $seam->devices->get(device_id: $front_door->device_id);

  // Inspect the locked property to confirm
  // that the unlock operation was successful.
  echo $updated_front_door->properties->locked ? 'true' : 'false', "\n"; // false
  ```

  ```csharp C# theme={null}
  // Get the device by ID.
  Device updatedFrontDoor = seam.Devices.Get(
    deviceId: frontDoor.DeviceId
  );

  // Inspect the locked property to confirm
  // that the unlock operation was successful.
  Console.WriteLine(updatedFrontDoor.Properties.Locked); // false
  ```
</CodeGroup>

**Output:**

<CodeGroup>
  ```json JavaScript theme={null}
  false
  ```

  ```json cURL theme={null}
  Locked (false): false
  ```

  ```json Python theme={null}
  False
  ```

  ```json Ruby theme={null}
  false
  ```

  ```json PHP theme={null}
  false
  ```

  ```json C# theme={null}
  False
  ```
</CodeGroup>

<Check>
  Now that you have successfully unlocked your lock, you can use the [Lock
  Door](/api/locks/lock_door) endpoint to lock it
  again.
</Check>

***

### Program access codes on your lock

You can use the Seam API to program [online access codes](/low-level-apis/smart-locks/access-codes) on TTLock locks that have an integrated or accessory keypad. Lock users can then enter these access codes using the keypad to unlock the lock.

The Seam API makes it easy to program both [ongoing](/low-level-apis/smart-locks/access-codes#ongoing-access-codes) and [time-bound](/low-level-apis/smart-locks/access-codes#time-bound-access-codes) online access codes.

**Code:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  // Confirm that the device supports online access codes.
  // Here's another capability flag!
  if (updatedFrontDoor.can_program_online_access_codes) {
    // Create an ongoing online access code.
    await seam.accessCodes.create({
      device_id: updatedFrontDoor.device_id,
      name: 'my ongoing code',
      code: '1234',
    })
    // Create a time-bound online access code.
    await seam.accessCodes.create({
      device_id: updatedFrontDoor.device_id,
      name: 'my time-bound code',
      starts_at: '2025-01-01T16:00:00Z',
      ends_at: '2025-01-22T12:00:00Z',
      code: '2345',
    })
    // List all access codes for this device.
    const accessCodes = await seam.accessCodes.list({
      device_id: updatedFrontDoor.device_id,
    })
    console.log(accessCodes)
  }
  ```

  ```bash cURL theme={null}
  # Confirm that the device supports online access codes.
  # Here's another capability flag!
  if  $(jq -r '.device.can_program_online_access_codes' <<< ${updated_front_door}); then \
    # Create an ongoing online access code.
    curl -X 'POST' \
      'https://connect.getseam.com/access_codes/create' \
      -H 'accept: application/json' \
      -H "Authorization: Bearer ${SEAM_API_KEY}" \
      -H 'Content-Type: application/json' \
      -d "{
        \"device_id\": \"$(jq -r '.device.device_id' <<< ${updated_front_door})\",
        \"name\": \"my ongoing code\",
        \"code\": \"1234\"
    }"
    # Create a time-bound online access code.
    curl -X 'POST' \
      'https://connect.getseam.com/access_codes/create' \
      -H 'accept: application/json' \
      -H "Authorization: Bearer ${SEAM_API_KEY}" \
      -H 'Content-Type: application/json' \
      -d "{
        \"device_id\": \"$(jq -r '.device.device_id' <<< ${updated_front_door})\",
        \"name\": \"my time-bound code\",
        \"starts_at\": \"2025-01-01T16:00:00Z\",
        \"ends_at\": \"2025-01-22T12:00:00Z\",
        \"code\": \"2345\"
    }"
    # List all access codes for this device.
    access_codes=$(
    # Use GET or POST.
    curl -X 'GET' \
      'https://connect.getseam.com/access_codes/list' \
      -H 'accept: application/json' \
      -H "Authorization: Bearer ${SEAM_API_KEY}" \
      -H 'Content-Type: application/json' \
      -d "{
        \"device_id\": \"$(jq -r '.device.device_id' <<< ${updated_front_door})\"
    }")
    echo ${access_codes};
  fi
  ```

  ```python Python theme={null}
  # Confirm that the device supports online access codes.
  # Here's another capability flag!
  if updated_front_door.can_program_online_access_codes:
    # Create an ongoing online access code.
    seam.access_codes.create(
      device_id = updated_front_door.device_id,
      name = "my ongoing code",
      code = "1234"
    )
    # Create a time-bound online access code.
    seam.access_codes.create(
      device_id = updated_front_door.device_id,
      name = "my time-bound code",
      starts_at = "2025-01-01T16:00:00Z",
      ends_at = "2025-01-22T12:00:00Z",
      code = "2345"
    )
    # List all access codes for this device.
    access_codes = seam.access_codes.list(
      device_id = updated_front_door.device_id
    )
    pprint(access_codes)
  ```

  ```ruby Ruby theme={null}
  # Confirm that the device supports online access codes.
  # Here's another capability flag!
  if (updated_front_door.can_program_online_access_codes)
    # Create an ongoing online access code.
    seam.access_codes.create(
      device_id: updated_front_door.device_id,
      name: "my ongoing code",
      code: "1234"
    )
    # Create a time-bound online access code.
    seam.access_codes.create(
      device_id: updated_front_door.device_id,
      name: "my time-bound code",
      starts_at: "2025-01-01T16:00:00Z",
      ends_at: "2025-01-22T12:00:00Z",
      code: "2345"
    )
    # List all access codes for this device.
    access_codes = seam.access_codes.list(
      device_id: updated_front_door.device_id
    )
    puts access_codes.inspect
  end
  ```

  ```php PHP theme={null}
  // Confirm that the device supports online access codes.
  // Here's another capability flag!
  if ($updated_front_door->can_program_online_access_codes) {
    // Create an ongoing online access code.
    $seam->access_codes->create(
      device_id: $updated_front_door->device_id,
      name: "my ongoing code",
      code: "1234"
    );
    // Create a time-bound online access code.
    $seam->access_codes->create(
      device_id: $updated_front_door->device_id,
      name: "my time-bound code",
      starts_at:  "2025-01-01T16:00:00Z",
      ends_at: "2025-01-22T12:00:00Z",
      code: "2345"
    );
    // List all access codes for this device.
    $access_codes = $seam->access_codes->list(
      device_id: $updated_front_door->device_id
    );
    echo json_encode($access_codes, JSON_PRETTY_PRINT);
  }
  ```

  ```csharp C# theme={null}
  // Confirm that the device supports online access codes.
  // Here's another capability flag!
  if (updatedFrontDoor.CanProgramOnlineAccessCodes == true) {
    // Create an ongoing online access code.
    seam.AccessCodes.Create(
      deviceId: updatedFrontDoor.DeviceId,
      name: "my ongoing code",
      code: "1234"
    );
    // Create a time-bound online access code.
    seam.AccessCodes.Create(
      deviceId: updatedFrontDoor.DeviceId,
      name: "my time-bound code",
      startsAt: "2025-01-01T16:00:00Z",
      endsAt: "2025-01-22T12:00:00Z",
      code: "2345"
    );
    // List all access codes for this device.
    var accessCodes = seam.AccessCodes.List(
      deviceId: updatedFrontDoor.DeviceId
    );
    foreach (var accessCode in accessCodes)
    {
      Console.WriteLine(accessCode);
    }
  }
  ```
</CodeGroup>

**Output:**

<CodeGroup>
  ```json JavaScript theme={null}
  [
    {
      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-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',
      ...
    }
  ]
  ```

  ```json cURL theme={null}
  {
    "access_codes": [
      {
        "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-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
  }
  ```

  ```json Python theme={null}
  [
    AccessCode(
      access_code_id='11111111-1111-1111-1111-555555555555',
      device_id='11111111-1111-1111-1111-444444444444',
      type='ongoing',
      code='1234',
      name='my ongoing code',
      ...
    )
    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',
      ...
    )
  ]
  ```

  ```json Ruby theme={null}
  [
    <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"
      ...
    >,
    <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
      ...
    >
  ]
  ```

  ```json PHP theme={null}
  [
    {
      "access_code_id": "11111111-1111-1111-1111-555555555555",
      "device_id": "11111111-1111-1111-1111-444444444444",
      "name": "my ongoing code",
      "type": "ongoing",
      "code": "1234",
      ...
    },
    {
      "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",
    }
  ]
  ```

  ```json C# theme={null}
  {
    "type": "ongoing",
    "access_code_id": "11111111-1111-1111-1111-555555555555",
    "device_id": "11111111-1111-1111-1111-444444444444",
    "name": "my ongoing code",
    "code": "1234",
    ...
  }
  {
    "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",
    ...
  }
  ```
</CodeGroup>

***

## Step 5: Connect a real TTLock lock

Now that you have learned the basics of using the Seam API, you can connect and control a real TTLock device. To do so, make sure to switch to a [non-sandbox workspace](/core-concepts/workspaces#production-workspaces) and [API key](/core-concepts/authentication/api-keys).

For more details about setting up your real TTLock lock, see the [TTLock locks integration guide](./).

***

## Step 6: Build your application!

Seam makes it easy to develop your application. In addition to the robust Seam API and the wide variety of programming languages that our SDKs support, we also provide a suite of [Seam Components](/ui-components/overview). These prebuilt UI components help you to build your device management flow.

For example, you can use the [Device Table Seam Component](/ui-components/overview/react-components/device-table) to display a list of devices and to identify all devices with issues. You can use the [Device Details Seam Component](/ui-components/overview/react-components/device-details) to display a device's properties, settings, and issues, as well as to enable your users to perform actions based on each device's capabilities. The [Access Code Details Seam Component](/ui-components/overview/react-components/access-code-details) provides a similar display and actions for access codes.

Seam Components use a responsive design to fit seamlessly on any screen size. They also provide device debugging flows to help your users.

To learn about all the Seam Components that we provide, see [Seam Components](/ui-components/overview).

***

## Next steps

Now that you've completed this getting started guide for TTLock devices, you can learn more about what you can do with the Seam API.

* [ ] **Explore**\
  See the [other devices and system integrations](/device-and-system-integration-guides) that Seam supports.
* [ ] **Learn**\
  Read about Seam [concepts](/core-concepts/overview) and the [device and system capabilities ](/capability-guides/device-and-system-capabilities)that Seam supports.
* [ ] **Use Seam Components**\
  Find out about [Seam Components](/ui-components/overview), which are prebuilt UI components for building your device management flow.
* [ ] **Use webhooks**\
  Learn how to use [webhooks](/developer-tools/webhooks) as an efficient way to receive device events.
* [ ] **Find out more**\
  Explore the other types of devices and systems that you can control with Seam, including [access control systems](/low-level-apis/access-systems), [thermostats](/capability-guides/thermostats), and [noise sensors](/capability-guides/noise-sensors).
* [ ] **Develop for mobile access**\
  Learn about Seam's [mobile access solution](/capability-guides/mobile-access).

<Info>
  If you have any questions or want to report an issue, email us at
  [support@seam.co](mailto:support@seam.co).
</Info>

***

## Quick links

<CardGroup>
  <Card title="Get an API Key (free)" href="https://console.seam.co/">
    Sign up for the Seam Console and get your API keys. →
  </Card>

  <Card title="Contact Sales" href="https://www.seam.co/contact-us">
    Got a project or a specific question? Contact our team to get answers. →
  </Card>
</CardGroup>


# TTLock Locks
Source: https://docs.seam.co/device-and-system-integration-guides/ttlock-locks/index

Connect TTLock smart locks to Seam to lock, unlock, and program access codes across the many manufacturers built on the TTLock platform.

<img alt="TTLock logo" />

## Overview

TTLock produces both hardware and software for smart locks. Many other manufacturers utilize TTLock's platform to create their own smart lock products. Locks built on this platform are compatible with a wide range of entrance types, including traditional doors, glass doors, locker doors, and key cylinders. With the TTLock mobile app, businesses can effortlessly lock and unlock doors and program key codes into the locks.

***

## Supported Devices

<DeviceList />

This integration works with any TTLock locks that are paired with a [TTLock Gateway](https://ttlock.eu/shop/tag/ttlock+gateway/).

For detailed information about the TTLock devices that Seam supports, see our [TTLock Supported Devices page](https://www.seam.co/manufacturers/ttlock).

***

## Supported Features

We support the following features:

* [Triggering web lock and unlock actions](/low-level-apis/smart-locks/lock-and-unlock)
* [Programming access codes](/low-level-apis/smart-locks/access-codes) on door locks and card readers that have a PIN pad

***

### Device Provider Key

Seam identifies these devices with the `ttlock` device provider key. By default, a [Connect Webview](/core-concepts/connect-webviews) displays all of the stable providers that Seam supports, so your users can connect their TTLock devices without you specifying a provider list. To narrow what a Connect Webview displays, see [Customize the Brands to Display in Your Connect Webviews](/core-concepts/connect-webviews/customizing-connect-webviews#customize-the-brands-to-display-in-your-connect-webviews).

***

## Setup Instructions

For instructions on connecting TTLock locks to Seam, see the [TTLock Setup Guide](./ttlock-setup-guide).

***

## Troubleshooting

### Lock Not Appearing in Seam

Your users must be the top administrator for each TTLock that they want to connect to Seam. That is, they must supply the credentials for the top administrator account when completing the Connect Webview to connect their TTLocks to Seam.

### Lock Not Paired to Gateway Error

On the device, if you notice a `ttlock_lock_not_paired_to_gateway` error, you will need to purchase [a compatible gateway](https://ttlock.eu/shop/tag/ttlock+gateway/) and pair it to the lock. Follow the [set up instructions](#setup-instructions) to configure the door lock.

### Gateway Unlocking Not Enabled Warning

On the device, if you notice a `ttlock_lock_gateway_unlocking_not_enabled` warning, you will need to follow the [set up instructions](#setup-instructions) to turn on the "Remote Unlock" feature.

### Power-Saving Mode

Certain TTLock Wi-Fi lock models have a power-saving mode. When these locks are in power-saving mode, the Seam API cannot control them remotely. If a TTLock Wi-Fi lock is not completing requested actions successfully, confirm whether the lock is in power-saving mode. If so, prompt your user to turn off power-saving mode, and then retry the operation.

***

## Where to Order

Many manufacturers produce Smart Locks using the TTLock platform. Find a lock by searching for a TTLock lock that fits your entrance type.

<table>
  <thead>
    <tr>
      <th />

      <th />

      <th />

      <th />

      <th />
    </tr>
  </thead>

  <tbody>
    <tr>
      <td />

      <td>
        <strong>Amazon - TTLock Locks</strong>
      </td>

      <td />

      <td>
        <a href="https://amzn.to/4554ISo">[https://amzn.to/4554ISo](https://amzn.to/4554ISo)</a>
      </td>

      <td>
        <a href="/images/download.png">download.png</a>
      </td>
    </tr>
  </tbody>
</table>


# Sandbox TTLock Locks
Source: https://docs.seam.co/device-and-system-integration-guides/ttlock-locks/ttlock-sample-data

Add virtual TTLock locks to your Seam sandbox workspace using these sample credentials to test your integration without real hardware.

Use the following set of credentials to add virtual [TTLock locks](/device-and-system-integration-guides/ttlock-locks) to your Seam [sandbox workspace](/core-concepts/workspaces#sandbox-workspaces):

| Email Address                               | Password |
| ------------------------------------------- | -------- |
| [jane@example.com](mailto:jane@example.com) | 1234     |


# TTLock Setup Guide
Source: https://docs.seam.co/device-and-system-integration-guides/ttlock-locks/ttlock-setup-guide

Connect your TTLock locks to Seam.

To use Seam with TTLock locks, ask the device owner to complete the steps below. Locks must already be installed before proceeding.

### 1. Set up the TTLock app

1. Download and install the [TTLock app](https://www.ttlock.com/#/lock/app) and create an account if you don't have one.

<Warning>
  Your users must be the **top administrator** for each TTLock that they want to
  connect to Seam.
</Warning>

2. Set up your door lock in the TTLock app. Follow [the instructions in this video](https://www.youtube.com/watch?v=IbgZNc1dAx4) for guidance.

### 2. Pair the lock with a TTLock gateway

Pair each lock with a [TTLock gateway](https://ttlock.eu/shop/tag/ttlock+gateway/). Follow [the instructions in this video](https://www.youtube.com/watch?v=-lhKbjVP1as) for guidance.

### 3. Enable Remote Unlock

In the [TTLock app](https://www.ttlock.com/#/lock/app), go to the lock settings and enable the **Remote Unlock** feature for each lock. This feature must be enabled to unlock a TTLock device through Seam. Follow [the instructions in this video](https://www.youtube.com/watch?v=ni-38QpoNA4) for guidance.

### 4. Connect TTLock to Seam

1. Note your login credentials for the TTLock app.
2. In the form to connect TTLock to Seam, enter those credentials and click **Submit** to complete.

***

### Troubleshooting

If locks don't appear after connecting your account:

* Verify that you're logging in with the **top administrator** account for each lock. Locks added under a sub-account will not appear.

If you see a `ttlock_lock_not_paired_to_gateway` error:

* Purchase [a compatible gateway](https://ttlock.eu/shop/tag/ttlock+gateway/) and pair it to the lock using the TTLock app.

If you see a `ttlock_lock_gateway_unlocking_not_enabled` warning:

* Open the lock settings in the TTLock app and enable the **Remote Unlock** feature.

If a lock is not completing requested actions:

* Certain TTLock Wi-Fi lock models have a power-saving mode that prevents remote control. Confirm whether the lock is in power-saving mode and, if so, ask the user to turn it off.


# Configuring Ultraloq Device Timezones
Source: https://docs.seam.co/device-and-system-integration-guides/ultraloq-locks/configuring-ultraloq-device-timezones

Configure device timezones for Ultraloq locks to enable time-bound access codes

Ultraloq devices require timezone configuration before you can create time-bound access codes. This guide explains why this is necessary and how to configure timezones for your Ultraloq devices.

***

## Why Timezone Configuration is Required

Ultraloq devices have a unique characteristic that requires manual timezone configuration:

**The Problem:**

* Ultraloq devices schedule access codes using **device-local time** (e.g., "2024-01-15 14:30")
* The Ultraloq API returns timestamps **without timezone information**
* Without knowing the device's timezone, Seam cannot correctly convert UTC timestamps to device-local time

**The Solution:**

* You must manually configure each device's timezone using the `/devices/report_provider_metadata` API
* This tells Seam what timezone the device is in so it can correctly schedule time-bound access codes

<Info>
  This is a **one-time configuration** per device. Once set, the timezone
  persists until you change it.
</Info>

***

## What Works Without Timezone

You can use the following features **without** configuring the device's timezone:

* ✅ **Permanent access codes** — Codes without `starts_at` and `ends_at` work immediately
* ✅ **Lock and unlock operations** — Remote lock/unlock commands work immediately
* ✅ **Device monitoring** — Battery level, lock status, and online/offline state

***

## What Requires Timezone

The following feature **requires** timezone configuration:

* ❌ **Time-bound access codes** — Codes with `starts_at` and `ends_at` require timezone

If you attempt to create a time-bound access code without configuring the timezone, you'll receive a validation error:

```json theme={null}
{
  "error": {
    "type": "invalid_input",
    "message": "Time zone required for time-bound access codes on Ultraloq devices"
  }
}
```

***

## Detecting Unconfigured Devices

When you first connect an Ultraloq device, it will have the `ultraloq_time_zone_unknown` warning:

<CodeGroup>
  ```javascript JavaScript theme={null}
  import { Seam } from 'seam'

  const seam = new Seam()

  const device = await seam.devices.get({
    device_id: 'your-device-id',
  })

  // Check for timezone warning
  const hasTimezoneWarning = device.warnings.some(
    (w) => w.warning_code === 'ultraloq_time_zone_unknown',
  )

  if (hasTimezoneWarning) {
    console.log('⚠️ Timezone not configured')
    console.log('Configure timezone before creating time-bound access codes')
  }

  // Check timezone value
  const timezone = device.properties.ultraloq_metadata?.time_zone
  console.log(`Current timezone: ${timezone}`) // Will be null if not configured
  ```

  ```bash cURL theme={null}
  device=$(curl -X 'POST' \
    'https://connect.getseam.com/devices/get' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d "{
      \"device_id\": \"your-device-id\"
    }")

  # Check for timezone warning
  echo $device | jq '.device.warnings[] | select(.warning_code == "ultraloq_time_zone_unknown")'

  # Check timezone value
  echo $device | jq '.device.properties.ultraloq_metadata.time_zone'
  ```

  ```python Python theme={null}
  from seam import Seam

  seam = Seam()

  device = seam.devices.get(device_id="your-device-id")

  # Check for timezone warning
  has_timezone_warning = any(
    w.warning_code == "ultraloq_time_zone_unknown"
    for w in device.warnings
  )

  if has_timezone_warning:
    print("⚠️ Timezone not configured")
    print("Configure timezone before creating time-bound access codes")

  # Check timezone value
  timezone = device.properties.get("ultraloq_metadata", {}).get("time_zone")
  print(f"Current timezone: {timezone}")  # Will be None if not configured
  ```

  ```ruby Ruby theme={null}
  require "seam"

  seam = Seam.new()

  device = seam.devices.get(device_id: "your-device-id")

  # Check for timezone warning
  has_timezone_warning = device.warnings.any? do |w|
    w.warning_code == "ultraloq_time_zone_unknown"
  end

  if has_timezone_warning
    puts "⚠️ Timezone not configured"
    puts "Configure timezone before creating time-bound access codes"
  end

  # Check timezone value
  timezone = device.properties.dig("ultraloq_metadata", "time_zone")
  puts "Current timezone: #{timezone}"  # Will be nil if not configured
  ```

  ```php PHP theme={null}
  <?php
  require 'vendor/autoload.php';

  use Seam\SeamClient;

  $seam = new SeamClient();

  $device = $seam->devices->get(device_id: "your-device-id");

  // Check for timezone warning
  $hasTimezoneWarning = false;
  foreach ($device->warnings as $warning) {
    if ($warning->warning_code === "ultraloq_time_zone_unknown") {
      $hasTimezoneWarning = true;
      break;
    }
  }

  if ($hasTimezoneWarning) {
    echo "⚠️ Timezone not configured\n";
    echo "Configure timezone before creating time-bound access codes\n";
  }

  // Check timezone value
  $timezone = $device->properties->ultraloq_metadata->time_zone ?? null;
  echo "Current timezone: " . ($timezone ?? "not set") . "\n";
  ```

  ```csharp C# theme={null}
  using Seam.Client;

  var seam = new SeamClient();

  var device = seam.Devices.Get(deviceId: "your-device-id");

  // Check for timezone warning
  var hasTimezoneWarning = device.Warnings.Any(
    w => w.WarningCode == "ultraloq_time_zone_unknown"
  );

  if (hasTimezoneWarning)
  {
    Console.WriteLine("⚠️ Timezone not configured");
    Console.WriteLine("Configure timezone before creating time-bound access codes");
  }

  // Check timezone value
  var timezone = device.Properties.UltraloqMetadata?.TimeZone;
  Console.WriteLine($"Current timezone: {timezone ?? "not set"}");
  ```

  ```java Java theme={null}
  import com.seam.api.Seam;
  import com.seam.api.types.Device;

  Seam seam = Seam.builder().build();

  Device device = seam.devices().get(
    DevicesGetRequest.builder()
      .deviceId("your-device-id")
      .build()
  );

  // Check for timezone warning
  boolean hasTimezoneWarning = device.getWarnings().stream()
    .anyMatch(w -> w.getWarningCode().equals("ultraloq_time_zone_unknown"));

  if (hasTimezoneWarning) {
    System.out.println("⚠️ Timezone not configured");
    System.out.println("Configure timezone before creating time-bound access codes");
  }

  // Check timezone value
  String timezone = device.getProperties().getUltraloqMetadata().getTimeZone();
  System.out.println("Current timezone: " + (timezone != null ? timezone : "not set"));
  ```
</CodeGroup>

***

## Configuring Timezones

### Single Device

To configure the timezone for a single device, use the `/devices/report_provider_metadata` endpoint:

<CodeGroup>
  ```javascript JavaScript theme={null}
  import { Seam } from 'seam'

  const seam = new Seam()

  // Configure timezone for one device
  await seam.devices.reportProviderMetadata({
    devices: [
      {
        device_id: 'your-device-id',
        ultraloq_metadata: {
          time_zone: 'America/New_York',
        },
      },
    ],
  })

  console.log('✓ Timezone configured successfully!')
  ```

  ```bash cURL theme={null}
  curl -X 'POST' \
    'https://connect.getseam.com/devices/report_provider_metadata' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d '{
      "devices": [
        {
          "device_id": "your-device-id",
          "ultraloq_metadata": {
            "time_zone": "America/New_York"
          }
        }
      ]
    }'
  ```

  ```python Python theme={null}
  from seam import Seam

  seam = Seam()

  # Configure timezone for one device
  seam.devices.report_provider_metadata(
    devices=[
      {
        "device_id": "your-device-id",
        "ultraloq_metadata": {
          "time_zone": "America/New_York"
        }
      }
    ]
  )

  print("✓ Timezone configured successfully!")
  ```

  ```ruby Ruby theme={null}
  require "seam"

  seam = Seam.new()

  # Configure timezone for one device
  seam.devices.report_provider_metadata(
    devices: [
      {
        device_id: "your-device-id",
        ultraloq_metadata: {
          time_zone: "America/New_York"
        }
      }
    ]
  )

  puts "✓ Timezone configured successfully!"
  ```

  ```php PHP theme={null}
  <?php
  require 'vendor/autoload.php';

  use Seam\SeamClient;

  $seam = new SeamClient();

  // Configure timezone for one device
  $seam->devices->report_provider_metadata(
    devices: [
      [
        "device_id" => "your-device-id",
        "ultraloq_metadata" => [
          "time_zone" => "America/New_York"
        ]
      ]
    ]
  );

  echo "✓ Timezone configured successfully!";
  ```

  ```csharp C# theme={null}
  using Seam.Client;

  var seam = new SeamClient();

  // Configure timezone for one device
  seam.Devices.ReportProviderMetadata(
    devices: new[] {
      new DeviceMetadata {
        DeviceId = "your-device-id",
        UltraloqMetadata = new UltraloqMetadata {
          TimeZone = "America/New_York"
        }
      }
    }
  );

  Console.WriteLine("✓ Timezone configured successfully!");
  ```

  ```java Java theme={null}
  import com.seam.api.Seam;

  Seam seam = Seam.builder().build();

  // Configure timezone for one device
  seam.devices().reportProviderMetadata(
    DevicesReportProviderMetadataRequest.builder()
      .devices(List.of(
        DeviceMetadata.builder()
          .deviceId("your-device-id")
          .ultraloqMetadata(UltraloqMetadata.builder()
            .timeZone("America/New_York")
            .build())
          .build()
      ))
      .build()
  );

  System.out.println("✓ Timezone configured successfully!");
  ```
</CodeGroup>

### Multiple Devices (Batch Configuration)

You can configure timezones for multiple devices in a single API call:

<CodeGroup>
  ```javascript JavaScript theme={null}
  import { Seam } from 'seam'

  const seam = new Seam()

  // Get all Ultraloq devices
  const devices = await seam.devices.list({
    device_type: 'ultraloq_lock',
  })

  // Configure timezone for all devices
  await seam.devices.reportProviderMetadata({
    devices: devices.map((device) => ({
      device_id: device.device_id,
      ultraloq_metadata: {
        time_zone: 'America/Los_Angeles', // Or get from user
      },
    })),
  })

  console.log(`✓ Configured timezone for ${devices.length} devices`)
  ```

  ```bash cURL theme={null}
  # Get all Ultraloq devices
  devices=$(curl -X 'POST' \
    'https://connect.getseam.com/devices/list' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d '{
      "device_type": "ultraloq_lock"
    }')

  # Configure timezone for all devices
  # (Requires jq to construct the request)
  curl -X 'POST' \
    'https://connect.getseam.com/devices/report_provider_metadata' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d "$(echo $devices | jq '{
      devices: [.devices[] | {
        device_id: .device_id,
        ultraloq_metadata: {
          time_zone: "America/Los_Angeles"
        }
      }]
    }')"
  ```

  ```python Python theme={null}
  from seam import Seam

  seam = Seam()

  # Get all Ultraloq devices
  devices = seam.devices.list(device_type="ultraloq_lock")

  # Configure timezone for all devices
  seam.devices.report_provider_metadata(
    devices=[
      {
        "device_id": device.device_id,
        "ultraloq_metadata": {
          "time_zone": "America/Los_Angeles"  # Or get from user
        }
      }
      for device in devices
    ]
  )

  print(f"✓ Configured timezone for {len(devices)} devices")
  ```

  ```ruby Ruby theme={null}
  require "seam"

  seam = Seam.new()

  # Get all Ultraloq devices
  devices = seam.devices.list(device_type: "ultraloq_lock")

  # Configure timezone for all devices
  seam.devices.report_provider_metadata(
    devices: devices.map do |device|
      {
        device_id: device.device_id,
        ultraloq_metadata: {
          time_zone: "America/Los_Angeles"  # Or get from user
        }
      }
    end
  )

  puts "✓ Configured timezone for #{devices.length} devices"
  ```

  ```php PHP theme={null}
  <?php
  require 'vendor/autoload.php';

  use Seam\SeamClient;

  $seam = new SeamClient();

  // Get all Ultraloq devices
  $devices = $seam->devices->list(device_type: "ultraloq_lock");

  // Configure timezone for all devices
  $deviceMetadata = array_map(function($device) {
    return [
      "device_id" => $device->device_id,
      "ultraloq_metadata" => [
        "time_zone" => "America/Los_Angeles"  // Or get from user
      ]
    ];
  }, $devices);

  $seam->devices->report_provider_metadata(devices: $deviceMetadata);

  echo "✓ Configured timezone for " . count($devices) . " devices";
  ```

  ```csharp C# theme={null}
  using Seam.Client;
  using System.Linq;

  var seam = new SeamClient();

  // Get all Ultraloq devices
  var devices = seam.Devices.List(deviceType: "ultraloq_lock");

  // Configure timezone for all devices
  seam.Devices.ReportProviderMetadata(
    devices: devices.Select(device => new DeviceMetadata {
      DeviceId = device.DeviceId,
      UltraloqMetadata = new UltraloqMetadata {
        TimeZone = "America/Los_Angeles"  // Or get from user
      }
    }).ToArray()
  );

  Console.WriteLine($"✓ Configured timezone for {devices.Count()} devices");
  ```

  ```java Java theme={null}
  import com.seam.api.Seam;
  import com.seam.api.types.Device;
  import java.util.stream.Collectors;

  Seam seam = Seam.builder().build();

  // Get all Ultraloq devices
  List<Device> devices = seam.devices().list(
    DevicesListRequest.builder()
      .deviceType("ultraloq_lock")
      .build()
  );

  // Configure timezone for all devices
  seam.devices().reportProviderMetadata(
    DevicesReportProviderMetadataRequest.builder()
      .devices(devices.stream()
        .map(device -> DeviceMetadata.builder()
          .deviceId(device.getDeviceId())
          .ultraloqMetadata(UltraloqMetadata.builder()
            .timeZone("America/Los_Angeles")  // Or get from user
            .build())
          .build())
        .collect(Collectors.toList()))
      .build()
  );

  System.out.println("✓ Configured timezone for " + devices.size() + " devices");
  ```
</CodeGroup>

***

## Valid Timezone Values

You must use **IANA timezone strings** (also called "tz database" timezones). These are standardized timezone identifiers in the format `Continent/City`.

### Examples of Valid Timezones

* `"America/New_York"` — Eastern Time (US)
* `"America/Chicago"` — Central Time (US)
* `"America/Denver"` — Mountain Time (US)
* `"America/Los_Angeles"` — Pacific Time (US)
* `"America/Phoenix"` — Arizona (no DST)
* `"America/Toronto"` — Eastern Time (Canada)
* `"Europe/London"` — UK
* `"Europe/Paris"` — Central European Time
* `"Asia/Tokyo"` — Japan
* `"Australia/Sydney"` — Australian Eastern Time

<Warning>
  **Do not use timezone abbreviations** like `"EST"`, `"PST"`, or `"GMT-5"`.
  These are ambiguous and will cause validation errors. Always use the full IANA
  timezone string.
</Warning>

### Finding the Right Timezone

For a complete list of valid IANA timezones, see:

* [IANA Time Zone Database (Wikipedia)](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones)
* [IANA Official Database](https://www.iana.org/time-zones)

Most programming languages also provide timezone lookup utilities:

<CodeGroup>
  ```javascript JavaScript theme={null}
  // Using Intl API (built-in)
  const userTimezone = Intl.DateTimeFormat().resolvedOptions().timeZone
  console.log(`User's timezone: ${userTimezone}`)
  // Example: "America/Los_Angeles"

  // Or using moment-timezone library
  const moment = require('moment-timezone')
  const allTimezones = moment.tz.names()
  console.log(`Available timezones: ${allTimezones.length}`)
  ```

  ```python Python theme={null}
  import pytz

  # List all available timezones
  all_timezones = pytz.all_timezones
  print(f"Available timezones: {len(all_timezones)}")

  # Search for timezones containing "New"
  ny_timezones = [tz for tz in all_timezones if "New" in tz]
  print(ny_timezones)
  # ['America/New_York', 'America/North_Dakota/New_Salem', ...]
  ```

  ```ruby Ruby theme={null}
  require 'tzinfo'

  # List all available timezones
  all_timezones = TZInfo::Timezone.all_identifiers
  puts "Available timezones: #{all_timezones.length}"

  # Search for timezones containing "New"
  ny_timezones = all_timezones.select { |tz| tz.include?("New") }
  puts ny_timezones
  # ["America/New_York", "America/North_Dakota/New_Salem", ...]
  ```
</CodeGroup>

***

## Verification

After configuring the timezone, verify that the configuration was successful:

<CodeGroup>
  ```javascript JavaScript theme={null}
  import { Seam } from 'seam'

  const seam = new Seam()

  const device = await seam.devices.get({
    device_id: 'your-device-id',
  })

  // Verify timezone is set
  const timezone = device.properties.ultraloq_metadata.time_zone
  console.log(`Device timezone: ${timezone}`)

  // Verify warning is cleared
  const hasWarning = device.warnings.some(
    (w) => w.warning_code === 'ultraloq_time_zone_unknown',
  )

  if (!hasWarning) {
    console.log('✓ Timezone configured successfully!')
    console.log('✓ Device is ready to create time-bound access codes')
  } else {
    console.log('✗ Warning still present - check timezone configuration')
  }
  ```

  ```bash cURL theme={null}
  device=$(curl -X 'POST' \
    'https://connect.getseam.com/devices/get' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d "{
      \"device_id\": \"your-device-id\"
    }")

  # Check timezone
  echo $device | jq -r '.device.properties.ultraloq_metadata.time_zone'

  # Check warnings
  echo $device | jq '.device.warnings[] | select(.warning_code == "ultraloq_time_zone_unknown")'
  ```

  ```python Python theme={null}
  from seam import Seam

  seam = Seam()

  device = seam.devices.get(device_id="your-device-id")

  # Verify timezone is set
  timezone = device.properties["ultraloq_metadata"]["time_zone"]
  print(f"Device timezone: {timezone}")

  # Verify warning is cleared
  has_warning = any(
    w.warning_code == "ultraloq_time_zone_unknown"
    for w in device.warnings
  )

  if not has_warning:
    print("✓ Timezone configured successfully!")
    print("✓ Device is ready to create time-bound access codes")
  else:
    print("✗ Warning still present - check timezone configuration")
  ```

  ```ruby Ruby theme={null}
  require "seam"

  seam = Seam.new()

  device = seam.devices.get(device_id: "your-device-id")

  # Verify timezone is set
  timezone = device.properties["ultraloq_metadata"]["time_zone"]
  puts "Device timezone: #{timezone}"

  # Verify warning is cleared
  has_warning = device.warnings.any? { |w| w.warning_code == "ultraloq_time_zone_unknown" }

  if !has_warning
    puts "✓ Timezone configured successfully!"
    puts "✓ Device is ready to create time-bound access codes"
  else
    puts "✗ Warning still present - check timezone configuration"
  end
  ```

  ```php PHP theme={null}
  <?php
  require 'vendor/autoload.php';

  use Seam\SeamClient;

  $seam = new SeamClient();

  $device = $seam->devices->get(device_id: "your-device-id");

  // Verify timezone is set
  $timezone = $device->properties->ultraloq_metadata->time_zone;
  echo "Device timezone: $timezone\n";

  // Verify warning is cleared
  $hasWarning = false;
  foreach ($device->warnings as $warning) {
    if ($warning->warning_code === "ultraloq_time_zone_unknown") {
      $hasWarning = true;
      break;
    }
  }

  if (!$hasWarning) {
    echo "✓ Timezone configured successfully!\n";
    echo "✓ Device is ready to create time-bound access codes\n";
  } else {
    echo "✗ Warning still present - check timezone configuration\n";
  }
  ```

  ```csharp C# theme={null}
  using Seam.Client;

  var seam = new SeamClient();

  var device = seam.Devices.Get(deviceId: "your-device-id");

  // Verify timezone is set
  var timezone = device.Properties.UltraloqMetadata.TimeZone;
  Console.WriteLine($"Device timezone: {timezone}");

  // Verify warning is cleared
  var hasWarning = device.Warnings.Any(
    w => w.WarningCode == "ultraloq_time_zone_unknown"
  );

  if (!hasWarning)
  {
    Console.WriteLine("✓ Timezone configured successfully!");
    Console.WriteLine("✓ Device is ready to create time-bound access codes");
  }
  else
  {
    Console.WriteLine("✗ Warning still present - check timezone configuration");
  }
  ```

  ```java Java theme={null}
  import com.seam.api.Seam;
  import com.seam.api.types.Device;

  Seam seam = Seam.builder().build();

  Device device = seam.devices().get(
    DevicesGetRequest.builder()
      .deviceId("your-device-id")
      .build()
  );

  // Verify timezone is set
  String timezone = device.getProperties().getUltraloqMetadata().getTimeZone();
  System.out.println("Device timezone: " + timezone);

  // Verify warning is cleared
  boolean hasWarning = device.getWarnings().stream()
    .anyMatch(w -> w.getWarningCode().equals("ultraloq_time_zone_unknown"));

  if (!hasWarning) {
    System.out.println("✓ Timezone configured successfully!");
    System.out.println("✓ Device is ready to create time-bound access codes");
  } else {
    System.out.println("✗ Warning still present - check timezone configuration");
  }
  ```
</CodeGroup>

After configuration, the device will also have the timezone in `device.location.timezone`:

```json theme={null}
{
  "device_id": "...",
  "properties": {
    "ultraloq_metadata": {
      "time_zone": "America/New_York"
    }
  },
  "location": {
    "timezone": "America/New_York"
  },
  "warnings": []
}
```

***

## Changing Timezones

You can change a device's timezone at any time by calling `/devices/report_provider_metadata` again with the new timezone.

<CodeGroup>
  ```javascript JavaScript theme={null}
  import { Seam } from 'seam'

  const seam = new Seam()

  // User moved device from New York to Los Angeles
  await seam.devices.reportProviderMetadata({
    devices: [
      {
        device_id: 'your-device-id',
        ultraloq_metadata: {
          time_zone: 'America/Los_Angeles', // Changed from America/New_York
        },
      },
    ],
  })

  console.log('✓ Timezone updated to Pacific Time')
  ```

  ```bash cURL theme={null}
  curl -X 'POST' \
    'https://connect.getseam.com/devices/report_provider_metadata' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d '{
      "devices": [
        {
          "device_id": "your-device-id",
          "ultraloq_metadata": {
            "time_zone": "America/Los_Angeles"
          }
        }
      ]
    }'
  ```

  ```python Python theme={null}
  from seam import Seam

  seam = Seam()

  # User moved device from New York to Los Angeles
  seam.devices.report_provider_metadata(
    devices=[
      {
        "device_id": "your-device-id",
        "ultraloq_metadata": {
          "time_zone": "America/Los_Angeles"  # Changed from America/New_York
        }
      }
    ]
  )

  print("✓ Timezone updated to Pacific Time")
  ```

  ```ruby Ruby theme={null}
  require "seam"

  seam = Seam.new()

  # User moved device from New York to Los Angeles
  seam.devices.report_provider_metadata(
    devices: [
      {
        device_id: "your-device-id",
        ultraloq_metadata: {
          time_zone: "America/Los_Angeles"  # Changed from America/New_York
        }
      }
    ]
  )

  puts "✓ Timezone updated to Pacific Time"
  ```

  ```php PHP theme={null}
  <?php
  require 'vendor/autoload.php';

  use Seam\SeamClient;

  $seam = new SeamClient();

  // User moved device from New York to Los Angeles
  $seam->devices->report_provider_metadata(
    devices: [
      [
        "device_id" => "your-device-id",
        "ultraloq_metadata" => [
          "time_zone" => "America/Los_Angeles"  // Changed from America/New_York
        ]
      ]
    ]
  );

  echo "✓ Timezone updated to Pacific Time";
  ```

  ```csharp C# theme={null}
  using Seam.Client;

  var seam = new SeamClient();

  // User moved device from New York to Los Angeles
  seam.Devices.ReportProviderMetadata(
    devices: new[] {
      new DeviceMetadata {
        DeviceId = "your-device-id",
        UltraloqMetadata = new UltraloqMetadata {
          TimeZone = "America/Los_Angeles"  // Changed from America/New_York
        }
      }
    }
  );

  Console.WriteLine("✓ Timezone updated to Pacific Time");
  ```

  ```java Java theme={null}
  import com.seam.api.Seam;

  Seam seam = Seam.builder().build();

  // User moved device from New York to Los Angeles
  seam.devices().reportProviderMetadata(
    DevicesReportProviderMetadataRequest.builder()
      .devices(List.of(
        DeviceMetadata.builder()
          .deviceId("your-device-id")
          .ultraloqMetadata(UltraloqMetadata.builder()
            .timeZone("America/Los_Angeles")  // Changed from America/New_York
            .build())
          .build()
      ))
      .build()
  );

  System.out.println("✓ Timezone updated to Pacific Time");
  ```
</CodeGroup>

**Impact on Existing Access Codes:**

* Existing time-bound access codes maintain their **UTC timestamps**
* They continue working correctly because Seam stores them in UTC internally
* Future access codes will use the new timezone for scheduling

***

## Best Practices

### 1. Set Timezone Immediately After Connection

Configure the timezone as soon as you connect an Ultraloq device, before users try to create time-bound access codes:

```python theme={null}
# Good practice: Configure timezone right after connection
devices = seam.devices.list(connected_account_id=account_id)

seam.devices.report_provider_metadata(
  devices=[
    {
      "device_id": device.device_id,
      "ultraloq_metadata": {"time_zone": user_timezone}
    }
    for device in devices
  ]
)
```

### 2. Check Warnings Before Creating Time-Bound Codes

Always check for the `ultraloq_time_zone_unknown` warning before creating time-bound access codes:

```python theme={null}
def can_create_time_bound_codes(device):
  return not any(
    w.warning_code == "ultraloq_time_zone_unknown"
    for w in device.warnings
  )

if can_create_time_bound_codes(device):
  # Safe to create time-bound codes
  seam.access_codes.create(
    device_id=device.device_id,
    starts_at="...",
    ends_at="..."
  )
else:
  # Prompt user to configure timezone
  print("Configure device timezone before creating time-bound codes")
```

### 3. Use device.location.timezone for Reference

After configuration, you can reference the configured timezone from `device.location.timezone`:

```python theme={null}
device = seam.devices.get(device_id="...")

if device.location and device.location.timezone:
  print(f"Device is in {device.location.timezone}")
  # Use this timezone for display or calculations
```

### 4. Provide Clear UI Guidance

In your application UI, guide users to select the correct timezone:

```
┌─────────────────────────────────────────────┐
│ ⚠️  Action Required: Set Device Timezone    │
│                                             │
│ Your Ultraloq device needs a timezone to   │
│ support scheduled access codes.             │
│                                             │
│ Device: Front Door Lock                     │
│                                             │
│ Select timezone: [America/New_York     ▼]  │
│                                             │
│ [ Configure Timezone ]                      │
└─────────────────────────────────────────────┘
```

***

## Troubleshooting

### Invalid Timezone Error

**Problem:** You receive an error like `"Invalid timezone. Must be a valid IANA timezone string."`

**Solution:**

* Verify you're using a valid IANA timezone (e.g., `"America/New_York"`, not `"EST"`)
* Check for typos in the timezone string
* Refer to the [IANA timezone list](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones)

### Warning Not Cleared After Configuration

**Problem:** The `ultraloq_time_zone_unknown` warning persists after calling `report_provider_metadata`.

**Solution:**

* Verify the API call succeeded (check for errors in the response)
* Refresh the device by calling `seam.devices.get()` again
* Ensure you used the correct `device_id`
* Wait a few seconds and check again (state updates are usually immediate but may take a moment)

### Time-Bound Codes Still Failing

**Problem:** Time-bound access codes still fail to create after configuring timezone.

**Solution:**

* Verify `device.properties.ultraloq_metadata.time_zone` is not `null`
* Check that `device.warnings` does not contain `ultraloq_time_zone_unknown`
* Ensure you're providing both `starts_at` and `ends_at` in your access code request
* Verify your timestamps are valid ISO 8601 UTC strings

***

## API Reference

For complete API documentation, see:

* [POST /devices/report\_provider\_metadata](/api/devices/report_provider_metadata)

***

## Next Steps

Now that you understand timezone configuration, you can:

* **Create time-bound access codes:** See [Creating Ultraloq Access Codes](./creating-ultraloq-access-codes)
* **Review the setup guide:** See [Ultraloq Setup Guide](./ultraloq-setup-guide)
* **Learn about access code constraints:** See [Understanding Code Constraints](/low-level-apis/smart-locks/access-codes/creating-access-codes/understanding-code-constraints)

***


# Creating Ultraloq Access Codes
Source: https://docs.seam.co/device-and-system-integration-guides/ultraloq-locks/creating-ultraloq-access-codes

Create and manage access codes for Ultraloq locks

This guide explains how to create and manage access codes for Ultraloq locks using the Seam API.

***

## Overview

Ultraloq locks support two types of access codes:

* **Permanent access codes** — Codes without start or end times that work indefinitely
* **Time-bound access codes** — Codes that automatically activate and deactivate at specific times

<Warning>
  **Important:** Time-bound access codes require [timezone
  configuration](./configuring-ultraloq-device-timezones). Permanent access
  codes work without timezone configuration.
</Warning>

***

## Before You Begin

To create access codes for an Ultraloq device:

1. Your Ultraloq device must be [connected to Seam](./ultraloq-setup-guide)
2. For **time-bound access codes only**: Device timezone must be [configured](./configuring-ultraloq-device-timezones)
3. Device must have `can_program_online_access_codes: true`

***

## Creating Permanent Access Codes

Permanent access codes work indefinitely until you delete them. They **do not require timezone configuration**.

<CodeGroup>
  ```javascript JavaScript theme={null}
  import { Seam } from 'seam'

  const seam = new Seam()

  // Create permanent access code
  const accessCode = await seam.accessCodes.create({
    device_id: 'your-device-id',
    name: 'Maintenance Team',
    code: '1234', // Optional: auto-generated if omitted
  })

  console.log(`Access code created: ${accessCode.code}`)
  console.log(`Status: ${accessCode.status}`)
  ```

  ```bash cURL theme={null}
  curl -X 'POST' \
    'https://connect.getseam.com/access_codes/create' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d '{
      "device_id": "your-device-id",
      "name": "Maintenance Team",
      "code": "1234"
    }'
  ```

  ```python Python theme={null}
  from seam import Seam

  seam = Seam()

  # Create permanent access code
  access_code = seam.access_codes.create(
    device_id="your-device-id",
    name="Maintenance Team",
    code="1234"  # Optional: auto-generated if omitted
  )

  print(f"Access code created: {access_code.code}")
  print(f"Status: {access_code.status}")
  ```

  ```ruby Ruby theme={null}
  require "seam"

  seam = Seam.new()

  # Create permanent access code
  access_code = seam.access_codes.create(
    device_id: "your-device-id",
    name: "Maintenance Team",
    code: "1234"  # Optional: auto-generated if omitted
  )

  puts "Access code created: #{access_code.code}"
  puts "Status: #{access_code.status}"
  ```

  ```php PHP theme={null}
  <?php
  require 'vendor/autoload.php';

  use Seam\SeamClient;

  $seam = new SeamClient();

  // Create permanent access code
  $accessCode = $seam->access_codes->create(
    device_id: "your-device-id",
    name: "Maintenance Team",
    code: "1234"  // Optional: auto-generated if omitted
  );

  echo "Access code created: " . $accessCode->code . "\n";
  echo "Status: " . $accessCode->status . "\n";
  ```

  ```csharp C# theme={null}
  using Seam.Client;

  var seam = new SeamClient();

  // Create permanent access code
  var accessCode = seam.AccessCodes.Create(
    deviceId: "your-device-id",
    name: "Maintenance Team",
    code: "1234"  // Optional: auto-generated if omitted
  );

  Console.WriteLine($"Access code created: {accessCode.Code}");
  Console.WriteLine($"Status: {accessCode.Status}");
  ```

  ```java Java theme={null}
  import com.seam.api.Seam;
  import com.seam.api.types.AccessCode;

  Seam seam = Seam.builder().build();

  // Create permanent access code
  AccessCode accessCode = seam.accessCodes().create(
    AccessCodesCreateRequest.builder()
      .deviceId("your-device-id")
      .name("Maintenance Team")
      .code("1234")  // Optional: auto-generated if omitted
      .build()
  );

  System.out.println("Access code created: " + accessCode.getCode());
  System.out.println("Status: " + accessCode.getStatus());
  ```
</CodeGroup>

***

## Creating Time-Bound Access Codes

Time-bound access codes automatically activate and deactivate at specified times. They **require timezone configuration**.

<Warning>
  **Prerequisites:** 1. Device timezone must be configured (see [Configuring
  Ultraloq Device Timezones](./configuring-ultraloq-device-timezones)) 2.
  Device must not have the `ultraloq_time_zone_unknown` warning
</Warning>

<CodeGroup>
  ```javascript JavaScript theme={null}
  import { Seam } from 'seam'

  const seam = new Seam()

  // Define time range in UTC
  const startsAt = new Date(Date.now() + 24 * 60 * 60 * 1000) // Tomorrow
  const endsAt = new Date(startsAt.getTime() + 2 * 24 * 60 * 60 * 1000) // +2 days

  // Create time-bound access code
  const accessCode = await seam.accessCodes.create({
    device_id: 'your-device-id',
    name: 'Weekend Guest',
    code: '5678', // Optional: auto-generated if omitted
    starts_at: startsAt.toISOString(),
    ends_at: endsAt.toISOString(),
  })

  console.log(`Access code created: ${accessCode.code}`)
  console.log(`Active from ${accessCode.starts_at} to ${accessCode.ends_at}`)
  console.log(`Status: ${accessCode.status}`)
  ```

  ```bash cURL theme={null}
  # Calculate timestamps (requires date command)
  STARTS_AT=$(date -u -d '+1 day' '+%Y-%m-%dT%H:%M:%SZ')
  ENDS_AT=$(date -u -d '+3 days' '+%Y-%m-%dT%H:%M:%SZ')

  curl -X 'POST' \
    'https://connect.getseam.com/access_codes/create' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d "{
      \"device_id\": \"your-device-id\",
      \"name\": \"Weekend Guest\",
      \"code\": \"5678\",
      \"starts_at\": \"${STARTS_AT}\",
      \"ends_at\": \"${ENDS_AT}\"
    }"
  ```

  ```python Python theme={null}
  from seam import Seam
  from datetime import datetime, timedelta

  seam = Seam()

  # Define time range in UTC
  starts_at = datetime.utcnow() + timedelta(days=1)
  ends_at = starts_at + timedelta(days=2)

  # Create time-bound access code
  access_code = seam.access_codes.create(
    device_id="your-device-id",
    name="Weekend Guest",
    code="5678",  # Optional: auto-generated if omitted
    starts_at=starts_at.isoformat() + "Z",
    ends_at=ends_at.isoformat() + "Z"
  )

  print(f"Access code created: {access_code.code}")
  print(f"Active from {access_code.starts_at} to {access_code.ends_at}")
  print(f"Status: {access_code.status}")
  ```

  ```ruby Ruby theme={null}
  require "seam"
  require "time"

  seam = Seam.new()

  # Define time range in UTC
  starts_at = Time.now.utc + (24 * 60 * 60)  # Tomorrow
  ends_at = starts_at + (2 * 24 * 60 * 60)   # +2 days

  # Create time-bound access code
  access_code = seam.access_codes.create(
    device_id: "your-device-id",
    name: "Weekend Guest",
    code: "5678",  # Optional: auto-generated if omitted
    starts_at: starts_at.iso8601,
    ends_at: ends_at.iso8601
  )

  puts "Access code created: #{access_code.code}"
  puts "Active from #{access_code.starts_at} to #{access_code.ends_at}"
  puts "Status: #{access_code.status}"
  ```

  ```php PHP theme={null}
  <?php
  require 'vendor/autoload.php';

  use Seam\SeamClient;

  $seam = new SeamClient();

  // Define time range in UTC
  $startsAt = new DateTime('+1 day', new DateTimeZone('UTC'));
  $endsAt = (clone $startsAt)->add(new DateInterval('P2D'));

  // Create time-bound access code
  $accessCode = $seam->access_codes->create(
    device_id: "your-device-id",
    name: "Weekend Guest",
    code: "5678",  // Optional: auto-generated if omitted
    starts_at: $startsAt->format(DateTime::ATOM),
    ends_at: $endsAt->format(DateTime::ATOM)
  );

  echo "Access code created: " . $accessCode->code . "\n";
  echo "Active from " . $accessCode->starts_at . " to " . $accessCode->ends_at . "\n";
  echo "Status: " . $accessCode->status . "\n";
  ```

  ```csharp C# theme={null}
  using Seam.Client;
  using System;

  var seam = new SeamClient();

  // Define time range in UTC
  var startsAt = DateTime.UtcNow.AddDays(1);
  var endsAt = startsAt.AddDays(2);

  // Create time-bound access code
  var accessCode = seam.AccessCodes.Create(
    deviceId: "your-device-id",
    name: "Weekend Guest",
    code: "5678",  // Optional: auto-generated if omitted
    startsAt: startsAt,
    endsAt: endsAt
  );

  Console.WriteLine($"Access code created: {accessCode.Code}");
  Console.WriteLine($"Active from {accessCode.StartsAt} to {accessCode.EndsAt}");
  Console.WriteLine($"Status: {accessCode.Status}");
  ```

  ```java Java theme={null}
  import com.seam.api.Seam;
  import com.seam.api.types.AccessCode;
  import java.time.Instant;
  import java.time.temporal.ChronoUnit;

  Seam seam = Seam.builder().build();

  // Define time range in UTC
  Instant startsAt = Instant.now().plus(1, ChronoUnit.DAYS);
  Instant endsAt = startsAt.plus(2, ChronoUnit.DAYS);

  // Create time-bound access code
  AccessCode accessCode = seam.accessCodes().create(
    AccessCodesCreateRequest.builder()
      .deviceId("your-device-id")
      .name("Weekend Guest")
      .code("5678")  // Optional: auto-generated if omitted
      .startsAt(startsAt.toString())
      .endsAt(endsAt.toString())
      .build()
  );

  System.out.println("Access code created: " + accessCode.getCode());
  System.out.println("Active from " + accessCode.getStartsAt() + " to " + accessCode.getEndsAt());
  System.out.println("Status: " + accessCode.getStatus());
  ```
</CodeGroup>

### How Time Zone Conversion Works

When you create a time-bound access code:

1. **You provide:** UTC timestamps (`starts_at` and `ends_at`)
2. **Seam converts:** UTC → Device local time using the configured timezone
3. **Ultraloq schedules:** Code activation/deactivation in device's local time
4. **Seam stores:** UTC timestamps for consistent time representation

**Example:**

```
User creates code with:
  starts_at: "2024-01-20T19:00:00Z"  (7:00 PM UTC)
  ends_at:   "2024-01-22T02:00:00Z"  (2:00 AM UTC)

Device timezone: "America/New_York" (UTC-5)

Seam converts to local time:
  Starts: 2024-01-20 14:00 (2:00 PM EST)
  Ends:   2024-01-21 21:00 (9:00 PM EST)

Ultraloq device activates code from 2:00 PM to 9:00 PM EST.
```

***

## Access Code Requirements

### Code Format

Ultraloq access codes must be:

* **Numeric only** — Only digits 0-9
* **4-8 characters long** — Examples: `"1234"`, `"567890"`, `"12345678"`

<Info>
  **Auto-generated codes:** If you omit the `code` parameter, Seam automatically
  generates a random 4-8 digit numeric code.
</Info>

### Valid Examples

```python theme={null}
# Valid codes
"1234"      # 4 digits
"56789"     # 5 digits
"123456"    # 6 digits
"1234567"   # 7 digits
"12345678"  # 8 digits
```

### Invalid Examples

```python theme={null}
# Invalid codes
"123"       # Too short (< 4 digits)
"123456789" # Too long (> 8 digits)
"abcd"      # Non-numeric characters
"12-34"     # Special characters not allowed
```

***

## Checking Device Readiness

Before creating time-bound access codes, verify that the device's timezone is configured:

<CodeGroup>
  ```javascript JavaScript theme={null}
  import { Seam } from 'seam'

  const seam = new Seam()

  async function canCreateTimeBoundCodes(deviceId) {
    const device = await seam.devices.get({ device_id: deviceId })

    // Check for timezone warning
    const hasTimezoneWarning = device.warnings.some(
      (w) => w.warning_code === 'ultraloq_time_zone_unknown',
    )

    return !hasTimezoneWarning
  }

  // Check before creating
  if (await canCreateTimeBoundCodes('your-device-id')) {
    // Safe to create time-bound codes
    const accessCode = await seam.accessCodes.create({
      device_id: 'your-device-id',
      starts_at: '...',
      ends_at: '...',
    })
  } else {
    console.log('Configure device timezone first')
    console.log('See: Configuring Ultraloq Device Timezones')
  }
  ```

  ```python Python theme={null}
  from seam import Seam

  seam = Seam()

  def can_create_time_bound_codes(device_id):
    device = seam.devices.get(device_id=device_id)

    # Check for timezone warning
    has_timezone_warning = any(
      w.warning_code == "ultraloq_time_zone_unknown"
      for w in device.warnings
    )

    return not has_timezone_warning

  # Check before creating
  if can_create_time_bound_codes("your-device-id"):
    # Safe to create time-bound codes
    access_code = seam.access_codes.create(
      device_id="your-device-id",
      starts_at="...",
      ends_at="..."
    )
  else:
    print("Configure device timezone first")
    print("See: Configuring Ultraloq Device Timezones")
  ```

  ```ruby Ruby theme={null}
  require "seam"

  seam = Seam.new()

  def can_create_time_bound_codes?(seam, device_id)
    device = seam.devices.get(device_id: device_id)

    # Check for timezone warning
    has_timezone_warning = device.warnings.any? do |w|
      w.warning_code == "ultraloq_time_zone_unknown"
    end

    !has_timezone_warning
  end

  # Check before creating
  if can_create_time_bound_codes?(seam, "your-device-id")
    # Safe to create time-bound codes
    access_code = seam.access_codes.create(
      device_id: "your-device-id",
      starts_at: "...",
      ends_at: "..."
    )
  else
    puts "Configure device timezone first"
    puts "See: Configuring Ultraloq Device Timezones"
  end
  ```

  ```php PHP theme={null}
  <?php
  require 'vendor/autoload.php';

  use Seam\SeamClient;

  $seam = new SeamClient();

  function canCreateTimeBoundCodes($seam, $deviceId) {
    $device = $seam->devices->get(device_id: $deviceId);

    // Check for timezone warning
    foreach ($device->warnings as $warning) {
      if ($warning->warning_code === "ultraloq_time_zone_unknown") {
        return false;
      }
    }

    return true;
  }

  // Check before creating
  if (canCreateTimeBoundCodes($seam, "your-device-id")) {
    // Safe to create time-bound codes
    $accessCode = $seam->access_codes->create(
      device_id: "your-device-id",
      starts_at: "...",
      ends_at: "..."
    );
  } else {
    echo "Configure device timezone first\n";
    echo "See: Configuring Ultraloq Device Timezones\n";
  }
  ```
</CodeGroup>

***

## Disabled Access Codes

Users can disable access codes through the Ultraloq mobile app. When this happens, Seam detects the change and adds a warning to the access code.

### Detecting Disabled Codes

<CodeGroup>
  ```javascript JavaScript theme={null}
  import { Seam } from 'seam'

  const seam = new Seam()

  const accessCode = await seam.accessCodes.get({
    access_code_id: 'your-access-code-id',
  })

  // Check for disabled warning
  const isDisabled = accessCode.warnings.some(
    (w) => w.warning_code === 'ultraloq_access_code_disabled',
  )

  if (isDisabled) {
    console.log('⚠️ Code is disabled on Ultraloq device')
    console.log('User must re-enable it in the Ultraloq mobile app')
  }
  ```

  ```python Python theme={null}
  from seam import Seam

  seam = Seam()

  access_code = seam.access_codes.get(
    access_code_id="your-access-code-id"
  )

  # Check for disabled warning
  is_disabled = any(
    w.warning_code == "ultraloq_access_code_disabled"
    for w in access_code.warnings
  )

  if is_disabled:
    print("⚠️ Code is disabled on Ultraloq device")
    print("User must re-enable it in the Ultraloq mobile app")
  ```

  ```ruby Ruby theme={null}
  require "seam"

  seam = Seam.new()

  access_code = seam.access_codes.get(
    access_code_id: "your-access-code-id"
  )

  # Check for disabled warning
  is_disabled = access_code.warnings.any? do |w|
    w.warning_code == "ultraloq_access_code_disabled"
  end

  if is_disabled
    puts "⚠️ Code is disabled on Ultraloq device"
    puts "User must re-enable it in the Ultraloq mobile app"
  end
  ```

  ```php PHP theme={null}
  <?php
  require 'vendor/autoload.php';

  use Seam\SeamClient;

  $seam = new SeamClient();

  $accessCode = $seam->access_codes->get(
    access_code_id: "your-access-code-id"
  );

  // Check for disabled warning
  $isDisabled = false;
  foreach ($accessCode->warnings as $warning) {
    if ($warning->warning_code === "ultraloq_access_code_disabled") {
      $isDisabled = true;
      break;
    }
  }

  if ($isDisabled) {
    echo "⚠️ Code is disabled on Ultraloq device\n";
    echo "User must re-enable it in the Ultraloq mobile app\n";
  }
  ```
</CodeGroup>

<Info>
  **Resolution:** The user must re-enable the code in the Ultraloq mobile app.
  Seam cannot programmatically re-enable disabled codes. Once re-enabled in the
  app, Seam will automatically detect the change and clear the warning.
</Info>

***

## Validation and Error Handling

### Time-Bound Code Without Timezone

If you attempt to create a time-bound code without configuring the device's timezone:

```json theme={null}
{
  "error": {
    "type": "invalid_input",
    "message": "Time zone required for time-bound access codes on Ultraloq devices"
  }
}
```

**Solution:** Configure the device's timezone first using `/devices/report_provider_metadata`. See [Configuring Ultraloq Device Timezones](./configuring-ultraloq-device-timezones).

### Invalid Code Format

If you provide a code that doesn't meet the 4-8 digit numeric requirement:

```json theme={null}
{
  "error": {
    "type": "invalid_input",
    "message": "Access code must be 4-8 digit numeric PIN for Ultraloq devices"
  }
}
```

**Solution:** Use only numeric digits (0-9) and ensure the code is 4-8 characters long.

### Missing Time Bounds

If you provide only `starts_at` or only `ends_at`:

```json theme={null}
{
  "error": {
    "type": "invalid_input",
    "message": "Both starts_at and ends_at must be provided together"
  }
}
```

**Solution:** Either provide both `starts_at` and `ends_at`, or omit both for a permanent code.

### Invalid Time Ordering

If `ends_at` is before `starts_at`:

```json theme={null}
{
  "error": {
    "type": "invalid_input",
    "message": "ends_at must be after starts_at"
  }
}
```

**Solution:** Ensure `starts_at` comes before `ends_at`.

***

## Best Practices

### 1. Use Auto-Generated Codes

For better security, let Seam generate random codes instead of using predictable patterns:

```python theme={null}
# Good: Auto-generated random code
access_code = seam.access_codes.create(
  device_id="your-device-id",
  name="Guest 123"
  # code parameter omitted - Seam generates random code
)

# Less secure: Predictable pattern
access_code = seam.access_codes.create(
  device_id="your-device-id",
  name="Guest 123",
  code="1234"  # Easy to guess
)
```

### 2. Check Timezone Before Creating Time-Bound Codes

Always verify timezone configuration before attempting to create time-bound codes:

```python theme={null}
device = seam.devices.get(device_id="your-device-id")

if not any(w.warning_code == "ultraloq_time_zone_unknown" for w in device.warnings):
  # Safe to create time-bound codes
  seam.access_codes.create(device_id=device.device_id, starts_at="...", ends_at="...")
else:
  # Configure timezone first
  print("Configure timezone before creating time-bound codes")
```

### 3. Monitor Access Code Warnings

Regularly check access code warnings to detect disabled codes:

```python theme={null}
access_codes = seam.access_codes.list(device_id="your-device-id")

disabled_codes = [
  code for code in access_codes
  if any(w.warning_code == "ultraloq_access_code_disabled" for w in code.warnings)
]

if disabled_codes:
  print(f"⚠️ {len(disabled_codes)} codes are disabled")
  # Notify user to re-enable in Ultraloq app
```

### 4. Use UTC Timestamps

Always provide timestamps in UTC (ISO 8601 format with 'Z' suffix):

```python theme={null}
# Good: UTC timestamp
starts_at = "2024-01-20T15:00:00Z"

# Bad: Local time without timezone info
starts_at = "2024-01-20T10:00:00"  # Ambiguous!
```

***

## Troubleshooting

### Code Not Appearing on Device

If an access code doesn't appear on the physical device:

1. Verify the code status is `set` (not `setting` or `unset`)
2. Check for warnings on the access code
3. Ensure the device is online and connected to Wi-Fi
4. Wait a few minutes for synchronization

### Time-Bound Code Activates at Wrong Time

If a time-bound code activates at an unexpected time:

1. Verify the device's timezone is correctly configured
2. Check `device.properties.ultraloq_metadata.time_zone`
3. Ensure you provided UTC timestamps (with 'Z' suffix)
4. Recalculate the local time conversion to verify correctness

### Code Validation Errors

If you receive validation errors when creating codes:

1. **Invalid format:** Ensure code is 4-8 numeric digits
2. **Timezone required:** Configure device timezone for time-bound codes
3. **Missing time bounds:** Provide both `starts_at` and `ends_at`, or neither
4. **Invalid ordering:** Ensure `starts_at` is before `ends_at`

***

## API Reference

For complete API documentation, see:

* [POST /access\_codes/create](/api/access_codes/create)
* [GET /access\_codes/get](/api/access_codes/get)
* [GET /access\_codes/list](/api/access_codes/list)
* [POST /access\_codes/delete](/api/access_codes/delete)

***

## Next Steps

* **Learn about timezone configuration:** See [Configuring Ultraloq Device Timezones](./configuring-ultraloq-device-timezones)
* **Understand code constraints:** See [Understanding Code Constraints](/low-level-apis/smart-locks/access-codes/creating-access-codes/understanding-code-constraints)
* **Review the setup guide:** See [Ultraloq Setup Guide](./ultraloq-setup-guide)
* **Explore access code webhooks:** See [Webhooks](/developer-tools/webhooks)

***


# Ultraloq Locks
Source: https://docs.seam.co/device-and-system-integration-guides/ultraloq-locks/index

Guide for using Ultraloq smart locks with Seam

<img alt="Ultraloq logo" />

## Overview

Seam integrates with Ultraloq smart locks, providing Wi-Fi-enabled access control with online programming capabilities. Ultraloq locks support both permanent and time-bound access codes, remote lock and unlock operations, and device monitoring.

<Warning>
  **Important:** Ultraloq devices require timezone configuration before you can
  create time-bound access codes. This is a unique requirement for Ultraloq
  locks. See [Configuring Ultraloq Device
  Timezones](/device-and-system-integration-guides/ultraloq-locks/configuring-ultraloq-device-timezones) for details.
</Warning>

***

## Supported Devices

<DeviceList />

All Ultraloq smart locks with Wi-Fi connectivity are supported through this integration.

For detailed information about the Ultraloq devices that Seam supports, see our [Ultraloq Supported Devices page](https://www.seam.co/manufacturers/ultraloq).

***

## Supported Features

We support the following features:

#### Device control

* Lock and unlock actions (online)

#### Access code management

* Permanent access codes (no timezone required)
* Time-bound access codes (requires timezone configuration)
* Custom code lengths between 4 and 8 digits
* Auto-generated codes

#### Device monitoring

* Lock status
* Online/offline state
* Battery level (where supported)

***

## Time Zone Requirement

Unlike most other integrations, Ultraloq devices require timezone configuration to enable time-bound access codes. This is because Ultraloq devices schedule access codes using device-local time, but the Ultraloq API does not report the device's timezone.

### What Works Without Timezone

* ✅ Permanent access codes (codes without start/end times)
* ✅ Lock and unlock operations
* ✅ Device monitoring

### What Requires Timezone

* ❌ Time-bound access codes (codes with `starts_at` and `ends_at`)

When you first connect an Ultraloq device, it will have a `ultraloq_time_zone_unknown` warning in `device.warnings`. You must configure the timezone using the `/devices/report_provider_metadata` endpoint before creating time-bound access codes.

For complete instructions, see [Configuring Ultraloq Device Timezones](/device-and-system-integration-guides/ultraloq-locks/configuring-ultraloq-device-timezones).

***

## Connecting Ultraloq to Seam

To enable your users to [connect Ultraloq devices through Connect Webviews](/core-concepts/connect-webviews/customizing-connect-webviews#customize-the-brands-to-display-in-your-connect-webviews), include the Ultraloq provider:

```json theme={null}
{
}
```

After the user authorizes Seam through the OAuth flow, their Ultraloq devices will be automatically discovered and added to Seam.

[→ See: Ultraloq Setup Guide](/device-and-system-integration-guides/ultraloq-locks/ultraloq-setup-guide)

***

## Brand-specific notes

* **Access codes:** Ultraloq requires access codes to be 4–8 digit numeric PINs (e.g., "1234", "567890").
* **Timezone configuration:** Required before creating time-bound access codes. Permanent codes work without timezone configuration.
* **Code disabling:** Users can disable access codes through the Ultraloq mobile app. Seam detects this and adds a `ultraloq_access_code_disabled` warning to the affected access code.

***

## Next Steps

<CardGroup>
  <Card title="Connect Ultraloq to Seam" href="/device-and-system-integration-guides/ultraloq-locks/ultraloq-setup-guide">
    Follow the setup guide to connect your Ultraloq account and configure device
    timezones.
  </Card>

  <Card title="Configure Device Timezones" href="/device-and-system-integration-guides/ultraloq-locks/configuring-ultraloq-device-timezones">
    Learn how to set device timezones to enable time-bound access codes.
  </Card>

  <Card title="Create Access Codes" href="/device-and-system-integration-guides/ultraloq-locks/creating-ultraloq-access-codes">
    Learn how to create permanent and time-bound access codes for Ultraloq
    locks.
  </Card>

  <Card title="Order Locks" href="https://www.amazon.com/stores/ULTRALOQ/page/1F5DDCF3-7F1E-4B36-8D3F-8F8C5E5A5C5F">
    Purchase Ultraloq locks from Amazon.
  </Card>
</CardGroup>

***


# Ultraloq Setup Guide
Source: https://docs.seam.co/device-and-system-integration-guides/ultraloq-locks/ultraloq-setup-guide

Step-by-step instructions for connecting Ultraloq devices to Seam

This guide walks you through connecting Ultraloq locks to Seam and configuring them for use with the Seam API.

## Before You Begin

To follow this guide, you need:

* A Seam account (create one at [console.seam.co](https://console.seam.co))
* An API key from your Seam workspace
* An Ultraloq account with at least one lock configured

<Info>
  If you're testing the integration, you can use a [sandbox
  workspace](/core-concepts/workspaces#sandbox-workspaces)
  with test Ultraloq devices.
</Info>

***

## Step 1: Create a Connect Webview

Create a [Connect Webview](/core-concepts/connect-webviews) to enable the Ultraloq device owner to authorize Seam to access their Ultraloq account.

<CodeGroup>
  ```javascript JavaScript theme={null}
  import { Seam } from 'seam'

  const seam = new Seam()

  const webview = await seam.connectWebviews.create({
    custom_redirect_url: 'https://your-app.com/oauth/callback',
  })

  console.log(webview.url)
  ```

  ```bash cURL theme={null}
  curl -X 'POST' \
    'https://connect.getseam.com/connect_webviews/create' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d '{
      "custom_redirect_url": "https://your-app.com/oauth/callback"
    }'
  ```

  ```python Python theme={null}
  from seam import Seam

  seam = Seam()

  webview = seam.connect_webviews.create(
    custom_redirect_url="https://your-app.com/oauth/callback"
  )

  print(webview.url)
  ```

  ```ruby Ruby theme={null}
  require "seam"

  seam = Seam.new()

  webview = seam.connect_webviews.create(
    custom_redirect_url: "https://your-app.com/oauth/callback"
  )

  puts webview.url
  ```

  ```php PHP theme={null}
  <?php
  require 'vendor/autoload.php';

  use Seam\SeamClient;

  $seam = new SeamClient();

  $webview = $seam->connect_webviews->create(
    custom_redirect_url: "https://your-app.com/oauth/callback"
  );

  echo $webview->url;
  ```

  ```csharp C# theme={null}
  using Seam.Client;

  var seam = new SeamClient();

  var webview = seam.ConnectWebviews.Create(
    customRedirectUrl: "https://your-app.com/oauth/callback"
  );

  Console.WriteLine(webview.Url);
  ```

  ```java Java theme={null}
  import com.seam.api.Seam;
  import com.seam.api.types.ConnectWebview;

  Seam seam = Seam.builder().build();

  ConnectWebview webview = seam.connectWebviews().create(
    ConnectWebviewsCreateRequest.builder()
      .customRedirectUrl("https://your-app.com/oauth/callback")
      .build()
  );

  System.out.println(webview.getUrl());
  ```
</CodeGroup>

***

## Step 2: User Authorization

Direct the user to the Connect Webview URL returned in Step 1. The user will be prompted to:

1. Sign in to their Ultraloq account
2. Authorize Seam to access their Ultraloq devices

After authorization, the user is redirected to your `custom_redirect_url` with the `connect_webview_id` as a query parameter.

***

## Step 3: Verify Connection

Wait for the Connect Webview status to change to `authorized`, indicating that the connection was successful. You can either poll the Connect Webview or use [webhooks](/developer-tools/webhooks) to be notified when the status changes.

<CodeGroup>
  ```javascript JavaScript theme={null}
  import { Seam } from 'seam'

  const seam = new Seam()

  // Poll until authorized
  const webview = await seam.connectWebviews.get({
    connect_webview_id: webview.connect_webview_id,
  })

  if (webview.status === 'authorized') {
    console.log('Connection successful!')
    console.log(`Connected account ID: ${webview.connected_account_id}`)
  }
  ```

  ```bash cURL theme={null}
  curl -X 'POST' \
    'https://connect.getseam.com/connect_webviews/get' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d "{
      \"connect_webview_id\": \"${CONNECT_WEBVIEW_ID}\"
    }"
  ```

  ```python Python theme={null}
  from seam import Seam

  seam = Seam()

  # Poll until authorized
  webview = seam.connect_webviews.get(
    connect_webview_id=webview.connect_webview_id
  )

  if webview.status == "authorized":
    print("Connection successful!")
    print(f"Connected account ID: {webview.connected_account_id}")
  ```

  ```ruby Ruby theme={null}
  require "seam"

  seam = Seam.new()

  # Poll until authorized
  webview = seam.connect_webviews.get(
    connect_webview_id: webview.connect_webview_id
  )

  if webview.status == "authorized"
    puts "Connection successful!"
    puts "Connected account ID: #{webview.connected_account_id}"
  end
  ```

  ```php PHP theme={null}
  <?php
  require 'vendor/autoload.php';

  use Seam\SeamClient;

  $seam = new SeamClient();

  // Poll until authorized
  $webview = $seam->connect_webviews->get(
    connect_webview_id: $webview->connect_webview_id
  );

  if ($webview->status === "authorized") {
    echo "Connection successful!\n";
    echo "Connected account ID: " . $webview->connected_account_id;
  }
  ```

  ```csharp C# theme={null}
  using Seam.Client;

  var seam = new SeamClient();

  // Poll until authorized
  var webview = seam.ConnectWebviews.Get(
    connectWebviewId: webview.ConnectWebviewId
  );

  if (webview.Status == "authorized")
  {
    Console.WriteLine("Connection successful!");
    Console.WriteLine($"Connected account ID: {webview.ConnectedAccountId}");
  }
  ```

  ```java Java theme={null}
  import com.seam.api.Seam;
  import com.seam.api.types.ConnectWebview;

  Seam seam = Seam.builder().build();

  // Poll until authorized
  ConnectWebview webview = seam.connectWebviews().get(
    ConnectWebviewsGetRequest.builder()
      .connectWebviewId(webview.getConnectWebviewId())
      .build()
  );

  if (webview.getStatus().equals("authorized")) {
    System.out.println("Connection successful!");
    System.out.println("Connected account ID: " + webview.getConnectedAccountId());
  }
  ```
</CodeGroup>

***

## Step 4: List Devices

Once the connection is authorized, retrieve the list of Ultraloq devices associated with the connected account.

<CodeGroup>
  ```javascript JavaScript theme={null}
  import { Seam } from 'seam'

  const seam = new Seam()

  const devices = await seam.devices.list({
    connected_account_id: webview.connected_account_id,
  })

  for (const device of devices) {
    console.log(`Device: ${device.properties.name}`)
    console.log(`Device ID: ${device.device_id}`)
    console.log(`Warnings:`, device.warnings)
    console.log()
  }
  ```

  ```bash cURL theme={null}
  curl -X 'POST' \
    'https://connect.getseam.com/devices/list' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d "{
      \"connected_account_id\": \"${CONNECTED_ACCOUNT_ID}\"
    }"
  ```

  ```python Python theme={null}
  from seam import Seam

  seam = Seam()

  devices = seam.devices.list(
    connected_account_id=webview.connected_account_id
  )

  for device in devices:
    print(f"Device: {device.properties['name']}")
    print(f"Device ID: {device.device_id}")
    print(f"Warnings: {device.warnings}")
    print()
  ```

  ```ruby Ruby theme={null}
  require "seam"

  seam = Seam.new()

  devices = seam.devices.list(
    connected_account_id: webview.connected_account_id
  )

  devices.each do |device|
    puts "Device: #{device.properties['name']}"
    puts "Device ID: #{device.device_id}"
    puts "Warnings: #{device.warnings}"
    puts
  end
  ```

  ```php PHP theme={null}
  <?php
  require 'vendor/autoload.php';

  use Seam\SeamClient;

  $seam = new SeamClient();

  $devices = $seam->devices->list(
    connected_account_id: $webview->connected_account_id
  );

  foreach ($devices as $device) {
    echo "Device: " . $device->properties->name . "\n";
    echo "Device ID: " . $device->device_id . "\n";
    echo "Warnings: " . json_encode($device->warnings) . "\n\n";
  }
  ```

  ```csharp C# theme={null}
  using Seam.Client;

  var seam = new SeamClient();

  var devices = seam.Devices.List(
    connectedAccountId: webview.ConnectedAccountId
  );

  foreach (var device in devices)
  {
    Console.WriteLine($"Device: {device.Properties.Name}");
    Console.WriteLine($"Device ID: {device.DeviceId}");
    Console.WriteLine($"Warnings: {string.Join(", ", device.Warnings)}");
    Console.WriteLine();
  }
  ```

  ```java Java theme={null}
  import com.seam.api.Seam;
  import com.seam.api.types.Device;

  Seam seam = Seam.builder().build();

  List<Device> devices = seam.devices().list(
    DevicesListRequest.builder()
      .connectedAccountId(webview.getConnectedAccountId())
      .build()
  );

  for (Device device : devices) {
    System.out.println("Device: " + device.getProperties().getName());
    System.out.println("Device ID: " + device.getDeviceId());
    System.out.println("Warnings: " + device.getWarnings());
    System.out.println();
  }
  ```
</CodeGroup>

**Expected Output:**

When you first list Ultraloq devices, they will have the `ultraloq_time_zone_unknown` warning:

```json theme={null}
{
  "device_id": "11111111-2222-3333-4444-555555555555",
  "device_type": "ultraloq_lock",
  "can_program_online_access_codes": true,
  "can_remotely_lock": true,
  "can_remotely_unlock": true,
  "warnings": [
    {
      "warning_code": "ultraloq_time_zone_unknown",
      "message": "Seam does not know the time zone of the Ultraloq device. Set a time zone to enable time-bound access codes."
    }
  ],
  "properties": {
    "ultraloq_metadata": {
      "time_zone": null
    }
  }
}
```

<Warning>
  **Important:** The `ultraloq_time_zone_unknown` warning indicates that you
  must configure the device's timezone before creating time-bound access codes.
  Proceed to Step 5 to configure timezones.
</Warning>

***

## Step 5: Configure Device Timezones

This is a **required step** for Ultraloq devices. You must configure each device's timezone before you can create time-bound access codes.

<CodeGroup>
  ```javascript JavaScript theme={null}
  import { Seam } from 'seam'

  const seam = new Seam()

  // Configure timezone for one or more devices
  await seam.devices.reportProviderMetadata({
    devices: [
      {
        device_id: device.device_id,
        ultraloq_metadata: {
          time_zone: 'America/New_York',
        },
      },
    ],
  })

  console.log('Timezone configured successfully!')
  ```

  ```bash cURL theme={null}
  curl -X 'POST' \
    'https://connect.getseam.com/devices/report_provider_metadata' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d "{
      \"devices\": [
        {
          \"device_id\": \"${DEVICE_ID}\",
          \"ultraloq_metadata\": {
            \"time_zone\": \"America/New_York\"
          }
        }
      ]
    }"
  ```

  ```python Python theme={null}
  from seam import Seam

  seam = Seam()

  # Configure timezone for one or more devices
  seam.devices.report_provider_metadata(
    devices=[
      {
        "device_id": device.device_id,
        "ultraloq_metadata": {
          "time_zone": "America/New_York"
        }
      }
    ]
  )

  print("Timezone configured successfully!")
  ```

  ```ruby Ruby theme={null}
  require "seam"

  seam = Seam.new()

  # Configure timezone for one or more devices
  seam.devices.report_provider_metadata(
    devices: [
      {
        device_id: device.device_id,
        ultraloq_metadata: {
          time_zone: "America/New_York"
        }
      }
    ]
  )

  puts "Timezone configured successfully!"
  ```

  ```php PHP theme={null}
  <?php
  require 'vendor/autoload.php';

  use Seam\SeamClient;

  $seam = new SeamClient();

  // Configure timezone for one or more devices
  $seam->devices->report_provider_metadata(
    devices: [
      [
        "device_id" => $device->device_id,
        "ultraloq_metadata" => [
          "time_zone" => "America/New_York"
        ]
      ]
    ]
  );

  echo "Timezone configured successfully!";
  ```

  ```csharp C# theme={null}
  using Seam.Client;

  var seam = new SeamClient();

  // Configure timezone for one or more devices
  seam.Devices.ReportProviderMetadata(
    devices: new[] {
      new DeviceMetadata {
        DeviceId = device.DeviceId,
        UltraloqMetadata = new UltraloqMetadata {
          TimeZone = "America/New_York"
        }
      }
    }
  );

  Console.WriteLine("Timezone configured successfully!");
  ```

  ```java Java theme={null}
  import com.seam.api.Seam;

  Seam seam = Seam.builder().build();

  // Configure timezone for one or more devices
  seam.devices().reportProviderMetadata(
    DevicesReportProviderMetadataRequest.builder()
      .devices(List.of(
        DeviceMetadata.builder()
          .deviceId(device.getDeviceId())
          .ultraloqMetadata(UltraloqMetadata.builder()
            .timeZone("America/New_York")
            .build())
          .build()
      ))
      .build()
  );

  System.out.println("Timezone configured successfully!");
  ```
</CodeGroup>

<Check>
  **Valid Timezone Values:** Use IANA timezone strings such as `"America/New_York"`, `"Europe/London"`, or `"Asia/Tokyo"`. Do not use timezone abbreviations like `"EST"` or `"PST"`.

  For a complete list of valid timezones, see the [IANA Time Zone Database](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones).
</Check>

For detailed information about timezone configuration, including best practices and troubleshooting, see [Configuring Ultraloq Device Timezones](/device-and-system-integration-guides/ultraloq-locks/configuring-ultraloq-device-timezones).

***

## Step 6: Verify Configuration

After configuring the timezone, verify that the warning has been cleared and the timezone is set correctly.

<CodeGroup>
  ```javascript JavaScript theme={null}
  import { Seam } from 'seam'

  const seam = new Seam()

  const device = await seam.devices.get({
    device_id: device.device_id,
  })

  // Check that timezone is configured
  console.assert(
    device.properties.ultraloq_metadata.time_zone === 'America/New_York',
    'Timezone should be set',
  )

  // Check that warning is cleared
  const hasWarning = device.warnings.some(
    (w) => w.warning_code === 'ultraloq_time_zone_unknown',
  )
  console.assert(!hasWarning, 'Timezone warning should be cleared')

  console.log('✓ Device is ready to create time-bound access codes!')
  ```

  ```bash cURL theme={null}
  device=$(curl -X 'POST' \
    'https://connect.getseam.com/devices/get' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d "{
      \"device_id\": \"${DEVICE_ID}\"
    }")

  # Check timezone is set
  echo $device | jq '.device.properties.ultraloq_metadata.time_zone'

  # Check warnings are cleared
  echo $device | jq '.device.warnings'
  ```

  ```python Python theme={null}
  from seam import Seam

  seam = Seam()

  device = seam.devices.get(device_id=device.device_id)

  # Check that timezone is configured
  assert device.properties["ultraloq_metadata"]["time_zone"] == "America/New_York"

  # Check that warning is cleared
  has_warning = any(
    w.warning_code == "ultraloq_time_zone_unknown"
    for w in device.warnings
  )
  assert not has_warning, "Timezone warning should be cleared"

  print("✓ Device is ready to create time-bound access codes!")
  ```

  ```ruby Ruby theme={null}
  require "seam"

  seam = Seam.new()

  device = seam.devices.get(device_id: device.device_id)

  # Check that timezone is configured
  raise "Timezone not set" unless device.properties["ultraloq_metadata"]["time_zone"] == "America/New_York"

  # Check that warning is cleared
  has_warning = device.warnings.any? { |w| w.warning_code == "ultraloq_time_zone_unknown" }
  raise "Timezone warning not cleared" if has_warning

  puts "✓ Device is ready to create time-bound access codes!"
  ```

  ```php PHP theme={null}
  <?php
  require 'vendor/autoload.php';

  use Seam\SeamClient;

  $seam = new SeamClient();

  $device = $seam->devices->get(device_id: $device->device_id);

  // Check that timezone is configured
  assert($device->properties->ultraloq_metadata->time_zone === "America/New_York");

  // Check that warning is cleared
  $hasWarning = false;
  foreach ($device->warnings as $warning) {
    if ($warning->warning_code === "ultraloq_time_zone_unknown") {
      $hasWarning = true;
      break;
    }
  }
  assert(!$hasWarning, "Timezone warning should be cleared");

  echo "✓ Device is ready to create time-bound access codes!";
  ```

  ```csharp C# theme={null}
  using Seam.Client;

  var seam = new SeamClient();

  var device = seam.Devices.Get(deviceId: device.DeviceId);

  // Check that timezone is configured
  Debug.Assert(
    device.Properties.UltraloqMetadata.TimeZone == "America/New_York",
    "Timezone should be set"
  );

  // Check that warning is cleared
  var hasWarning = device.Warnings.Any(
    w => w.WarningCode == "ultraloq_time_zone_unknown"
  );
  Debug.Assert(!hasWarning, "Timezone warning should be cleared");

  Console.WriteLine("✓ Device is ready to create time-bound access codes!");
  ```

  ```java Java theme={null}
  import com.seam.api.Seam;
  import com.seam.api.types.Device;

  Seam seam = Seam.builder().build();

  Device device = seam.devices().get(
    DevicesGetRequest.builder()
      .deviceId(device.getDeviceId())
      .build()
  );

  // Check that timezone is configured
  assert device.getProperties().getUltraloqMetadata().getTimeZone().equals("America/New_York");

  // Check that warning is cleared
  boolean hasWarning = device.getWarnings().stream()
    .anyMatch(w -> w.getWarningCode().equals("ultraloq_time_zone_unknown"));
  assert !hasWarning : "Timezone warning should be cleared";

  System.out.println("✓ Device is ready to create time-bound access codes!");
  ```
</CodeGroup>

***

## Next Steps

Now that your Ultraloq devices are connected and configured, you can perform common operations:

### Lock and Unlock Devices

<CodeGroup>
  ```javascript JavaScript theme={null}
  import { Seam } from 'seam'

  const seam = new Seam()

  // Lock the door
  await seam.locks.lockDoor({ device_id: 'your-device-id' })
  console.log('Door locked')

  // Unlock the door
  await seam.locks.unlockDoor({ device_id: 'your-device-id' })
  console.log('Door unlocked')
  ```

  ```bash cURL theme={null}
  # Lock the door
  curl -X 'POST' \
    'https://connect.getseam.com/locks/lock_door' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d "{\"device_id\": \"your-device-id\"}"

  # Unlock the door
  curl -X 'POST' \
    'https://connect.getseam.com/locks/unlock_door' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d "{\"device_id\": \"your-device-id\"}"
  ```

  ```python Python theme={null}
  from seam import Seam

  seam = Seam()

  # Lock the door
  seam.locks.lock_door(device_id="your-device-id")
  print("Door locked")

  # Unlock the door
  seam.locks.unlock_door(device_id="your-device-id")
  print("Door unlocked")
  ```

  ```ruby Ruby theme={null}
  require "seam"

  seam = Seam.new()

  # Lock the door
  seam.locks.lock_door(device_id: "your-device-id")
  puts "Door locked"

  # Unlock the door
  seam.locks.unlock_door(device_id: "your-device-id")
  puts "Door unlocked"
  ```

  ```php PHP theme={null}
  <?php
  require 'vendor/autoload.php';

  use Seam\SeamClient;

  $seam = new SeamClient();

  // Lock the door
  $seam->locks->lock_door(device_id: "your-device-id");
  echo "Door locked\n";

  // Unlock the door
  $seam->locks->unlock_door(device_id: "your-device-id");
  echo "Door unlocked\n";
  ```

  ```csharp C# theme={null}
  using Seam.Client;

  var seam = new SeamClient();

  // Lock the door
  seam.Locks.LockDoor(deviceId: "your-device-id");
  Console.WriteLine("Door locked");

  // Unlock the door
  seam.Locks.UnlockDoor(deviceId: "your-device-id");
  Console.WriteLine("Door unlocked");
  ```

  ```java Java theme={null}
  import com.seam.api.Seam;

  Seam seam = Seam.builder().build();

  // Lock the door
  seam.locks().lockDoor(LocksLockDoorRequest.builder()
    .deviceId("your-device-id")
    .build());
  System.out.println("Door locked");

  // Unlock the door
  seam.locks().unlockDoor(LocksUnlockDoorRequest.builder()
    .deviceId("your-device-id")
    .build());
  System.out.println("Door unlocked");
  ```
</CodeGroup>

### Create Permanent Access Codes

Permanent access codes work indefinitely and do not require timezone configuration:

<CodeGroup>
  ```javascript JavaScript theme={null}
  import { Seam } from 'seam'

  const seam = new Seam()

  // Create permanent access code
  const accessCode = await seam.accessCodes.create({
    device_id: 'your-device-id',
    name: 'Maintenance Team',
    code: '1234', // Optional: auto-generated if omitted
  })

  console.log(`Created permanent code: ${accessCode.code}`)
  ```

  ```bash cURL theme={null}
  curl -X 'POST' \
    'https://connect.getseam.com/access_codes/create' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d '{
      "device_id": "your-device-id",
      "name": "Maintenance Team",
      "code": "1234"
    }'
  ```

  ```python Python theme={null}
  from seam import Seam

  seam = Seam()

  # Create permanent access code
  access_code = seam.access_codes.create(
    device_id="your-device-id",
    name="Maintenance Team",
    code="1234"  # Optional: auto-generated if omitted
  )

  print(f"Created permanent code: {access_code.code}")
  ```

  ```ruby Ruby theme={null}
  require "seam"

  seam = Seam.new()

  # Create permanent access code
  access_code = seam.access_codes.create(
    device_id: "your-device-id",
    name: "Maintenance Team",
    code: "1234"  # Optional: auto-generated if omitted
  )

  puts "Created permanent code: #{access_code.code}"
  ```

  ```php PHP theme={null}
  <?php
  require 'vendor/autoload.php';

  use Seam\SeamClient;

  $seam = new SeamClient();

  // Create permanent access code
  $accessCode = $seam->access_codes->create(
    device_id: "your-device-id",
    name: "Maintenance Team",
    code: "1234"  // Optional: auto-generated if omitted
  );

  echo "Created permanent code: " . $accessCode->code . "\n";
  ```

  ```csharp C# theme={null}
  using Seam.Client;

  var seam = new SeamClient();

  // Create permanent access code
  var accessCode = seam.AccessCodes.Create(
    deviceId: "your-device-id",
    name: "Maintenance Team",
    code: "1234"  // Optional: auto-generated if omitted
  );

  Console.WriteLine($"Created permanent code: {accessCode.Code}");
  ```

  ```java Java theme={null}
  import com.seam.api.Seam;
  import com.seam.api.types.AccessCode;

  Seam seam = Seam.builder().build();

  // Create permanent access code
  AccessCode accessCode = seam.accessCodes().create(
    AccessCodesCreateRequest.builder()
      .deviceId("your-device-id")
      .name("Maintenance Team")
      .code("1234")  // Optional: auto-generated if omitted
      .build()
  );

  System.out.println("Created permanent code: " + accessCode.getCode());
  ```
</CodeGroup>

### Create Time-Bound Access Codes

Time-bound access codes require timezone configuration (completed in Step 5):

<CodeGroup>
  ```javascript JavaScript theme={null}
  import { Seam } from 'seam'

  const seam = new Seam()

  // Define time range
  const startsAt = new Date(Date.now() + 24 * 60 * 60 * 1000)
  const endsAt = new Date(startsAt.getTime() + 2 * 24 * 60 * 60 * 1000)

  // Create time-bound access code
  const accessCode = await seam.accessCodes.create({
    device_id: 'your-device-id',
    name: 'Weekend Guest',
    starts_at: startsAt.toISOString(),
    ends_at: endsAt.toISOString(),
  })

  console.log(`Created time-bound code: ${accessCode.code}`)
  console.log(`Active from ${accessCode.starts_at} to ${accessCode.ends_at}`)
  ```

  ```bash cURL theme={null}
  # Calculate timestamps
  STARTS_AT=$(date -u -d '+1 day' '+%Y-%m-%dT%H:%M:%SZ')
  ENDS_AT=$(date -u -d '+3 days' '+%Y-%m-%dT%H:%M:%SZ')

  curl -X 'POST' \
    'https://connect.getseam.com/access_codes/create' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d "{
      \"device_id\": \"your-device-id\",
      \"name\": \"Weekend Guest\",
      \"starts_at\": \"${STARTS_AT}\",
      \"ends_at\": \"${ENDS_AT}\"
    }"
  ```

  ```python Python theme={null}
  from seam import Seam
  from datetime import datetime, timedelta

  seam = Seam()

  # Define time range
  starts_at = datetime.utcnow() + timedelta(days=1)
  ends_at = starts_at + timedelta(days=2)

  # Create time-bound access code
  access_code = seam.access_codes.create(
    device_id="your-device-id",
    name="Weekend Guest",
    starts_at=starts_at.isoformat() + "Z",
    ends_at=ends_at.isoformat() + "Z"
  )

  print(f"Created time-bound code: {access_code.code}")
  print(f"Active from {access_code.starts_at} to {access_code.ends_at}")
  ```

  ```ruby Ruby theme={null}
  require "seam"
  require "time"

  seam = Seam.new()

  # Define time range
  starts_at = Time.now.utc + (24 * 60 * 60)
  ends_at = starts_at + (2 * 24 * 60 * 60)

  # Create time-bound access code
  access_code = seam.access_codes.create(
    device_id: "your-device-id",
    name: "Weekend Guest",
    starts_at: starts_at.iso8601,
    ends_at: ends_at.iso8601
  )

  puts "Created time-bound code: #{access_code.code}"
  puts "Active from #{access_code.starts_at} to #{access_code.ends_at}"
  ```

  ```php PHP theme={null}
  <?php
  require 'vendor/autoload.php';

  use Seam\SeamClient;

  $seam = new SeamClient();

  // Define time range
  $startsAt = new DateTime('+1 day', new DateTimeZone('UTC'));
  $endsAt = (clone $startsAt)->add(new DateInterval('P2D'));

  // Create time-bound access code
  $accessCode = $seam->access_codes->create(
    device_id: "your-device-id",
    name: "Weekend Guest",
    starts_at: $startsAt->format(DateTime::ATOM),
    ends_at: $endsAt->format(DateTime::ATOM)
  );

  echo "Created time-bound code: " . $accessCode->code . "\n";
  echo "Active from " . $accessCode->starts_at . " to " . $accessCode->ends_at . "\n";
  ```

  ```csharp C# theme={null}
  using Seam.Client;
  using System;

  var seam = new SeamClient();

  // Define time range
  var startsAt = DateTime.UtcNow.AddDays(1);
  var endsAt = startsAt.AddDays(2);

  // Create time-bound access code
  var accessCode = seam.AccessCodes.Create(
    deviceId: "your-device-id",
    name: "Weekend Guest",
    startsAt: startsAt,
    endsAt: endsAt
  );

  Console.WriteLine($"Created time-bound code: {accessCode.Code}");
  Console.WriteLine($"Active from {accessCode.StartsAt} to {accessCode.EndsAt}");
  ```

  ```java Java theme={null}
  import com.seam.api.Seam;
  import com.seam.api.types.AccessCode;
  import java.time.Instant;
  import java.time.temporal.ChronoUnit;

  Seam seam = Seam.builder().build();

  // Define time range
  Instant startsAt = Instant.now().plus(1, ChronoUnit.DAYS);
  Instant endsAt = startsAt.plus(2, ChronoUnit.DAYS);

  // Create time-bound access code
  AccessCode accessCode = seam.accessCodes().create(
    AccessCodesCreateRequest.builder()
      .deviceId("your-device-id")
      .name("Weekend Guest")
      .startsAt(startsAt.toString())
      .endsAt(endsAt.toString())
      .build()
  );

  System.out.println("Created time-bound code: " + accessCode.getCode());
  System.out.println("Active from " + accessCode.getStartsAt() + " to " + accessCode.getEndsAt());
  ```
</CodeGroup>

### Monitor Device Status

<CodeGroup>
  ```javascript JavaScript theme={null}
  import { Seam } from 'seam'

  const seam = new Seam()

  const device = await seam.devices.get({ device_id: 'your-device-id' })

  // Check lock status
  console.log(`Lock status: ${device.properties.locked}`)

  // Check online status
  console.log(`Online: ${device.properties.online}`)

  // Check battery level (if available)
  if (device.properties.battery_level) {
    console.log(`Battery level: ${device.properties.battery_level}`)
  }

  // Check for warnings
  if (device.warnings.length > 0) {
    console.log(`Warnings: ${device.warnings.map((w) => w.warning_code)}`)
  }
  ```

  ```bash cURL theme={null}
  device=$(curl -X 'POST' \
    'https://connect.getseam.com/devices/get' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d "{\"device_id\": \"your-device-id\"}")

  # Check lock status
  echo $device | jq '.device.properties.locked'

  # Check online status
  echo $device | jq '.device.properties.online'

  # Check battery level
  echo $device | jq '.device.properties.battery_level'

  # Check warnings
  echo $device | jq '.device.warnings'
  ```

  ```python Python theme={null}
  from seam import Seam

  seam = Seam()

  device = seam.devices.get(device_id="your-device-id")

  # Check lock status
  print(f"Lock status: {device.properties['locked']}")

  # Check online status
  print(f"Online: {device.properties['online']}")

  # Check battery level (if available)
  if 'battery_level' in device.properties:
    print(f"Battery level: {device.properties['battery_level']}")

  # Check for warnings
  if device.warnings:
    print(f"Warnings: {[w.warning_code for w in device.warnings]}")
  ```

  ```ruby Ruby theme={null}
  require "seam"

  seam = Seam.new()

  device = seam.devices.get(device_id: "your-device-id")

  # Check lock status
  puts "Lock status: #{device.properties['locked']}"

  # Check online status
  puts "Online: #{device.properties['online']}"

  # Check battery level (if available)
  if device.properties['battery_level']
    puts "Battery level: #{device.properties['battery_level']}"
  end

  # Check for warnings
  if device.warnings.any?
    puts "Warnings: #{device.warnings.map(&:warning_code)}"
  end
  ```

  ```php PHP theme={null}
  <?php
  require 'vendor/autoload.php';

  use Seam\SeamClient;

  $seam = new SeamClient();

  $device = $seam->devices->get(device_id: "your-device-id");

  // Check lock status
  echo "Lock status: " . ($device->properties->locked ? "locked" : "unlocked") . "\n";

  // Check online status
  echo "Online: " . ($device->properties->online ? "yes" : "no") . "\n";

  // Check battery level (if available)
  if (isset($device->properties->battery_level)) {
    echo "Battery level: " . $device->properties->battery_level . "\n";
  }

  // Check for warnings
  if (count($device->warnings) > 0) {
    $warningCodes = array_map(fn($w) => $w->warning_code, $device->warnings);
    echo "Warnings: " . implode(", ", $warningCodes) . "\n";
  }
  ```

  ```csharp C# theme={null}
  using Seam.Client;
  using System.Linq;

  var seam = new SeamClient();

  var device = seam.Devices.Get(deviceId: "your-device-id");

  // Check lock status
  Console.WriteLine($"Lock status: {device.Properties.Locked}");

  // Check online status
  Console.WriteLine($"Online: {device.Properties.Online}");

  // Check battery level (if available)
  if (device.Properties.BatteryLevel.HasValue)
  {
    Console.WriteLine($"Battery level: {device.Properties.BatteryLevel}");
  }

  // Check for warnings
  if (device.Warnings.Any())
  {
    var warningCodes = string.Join(", ", device.Warnings.Select(w => w.WarningCode));
    Console.WriteLine($"Warnings: {warningCodes}");
  }
  ```

  ```java Java theme={null}
  import com.seam.api.Seam;
  import com.seam.api.types.Device;
  import java.util.stream.Collectors;

  Seam seam = Seam.builder().build();

  Device device = seam.devices().get(
    DevicesGetRequest.builder()
      .deviceId("your-device-id")
      .build()
  );

  // Check lock status
  System.out.println("Lock status: " + device.getProperties().getLocked());

  // Check online status
  System.out.println("Online: " + device.getProperties().getOnline());

  // Check battery level (if available)
  if (device.getProperties().getBatteryLevel() != null) {
    System.out.println("Battery level: " + device.getProperties().getBatteryLevel());
  }

  // Check for warnings
  if (!device.getWarnings().isEmpty()) {
    String warningCodes = device.getWarnings().stream()
      .map(w -> w.getWarningCode())
      .collect(Collectors.joining(", "));
    System.out.println("Warnings: " + warningCodes);
  }
  ```
</CodeGroup>

***

## Related Resources

* **[Creating Ultraloq Access Codes](/device-and-system-integration-guides/ultraloq-locks/creating-ultraloq-access-codes)** - Detailed guide on permanent and time-bound access codes
* **[Configuring Ultraloq Device Timezones](/device-and-system-integration-guides/ultraloq-locks/configuring-ultraloq-device-timezones)** - Complete timezone configuration reference
* **[Lock and Unlock Operations](/low-level-apis/smart-locks/lock-and-unlock)** - General smart lock control documentation
* **[Access Codes Overview](/low-level-apis/smart-locks/access-codes)** - Understanding access code management

***

## Troubleshooting

### Devices not appearing after connection

If devices don't appear after connecting your Ultraloq account:

1. Verify that your locks are connected to Wi-Fi in the Ultraloq mobile app
2. Ensure your Ultraloq account has access to the locks you're trying to connect
3. Wait a few minutes for the initial sync to complete

### Warning persists after setting timezone

If the `ultraloq_time_zone_unknown` warning persists after setting the timezone:

1. Verify you used a valid IANA timezone string (e.g., `"America/New_York"`, not `"EST"`)
2. Check that the API call succeeded without errors
3. Refresh the device by calling `seam.devices.get()` to get the latest state

### Time-bound access codes fail to create

If you receive an error when creating time-bound access codes:

1. Confirm the device's timezone is configured (check `device.properties.ultraloq_metadata.time_zone`)
2. Verify the `ultraloq_time_zone_unknown` warning is not present in `device.warnings`
3. Ensure you're providing both `starts_at` and `ends_at` parameters

***


# Get started with Wyze Locks
Source: https://docs.seam.co/device-and-system-integration-guides/wyze-locks/get-started-with-wyze-locks

Learn how to connect and control your Wyze locks with the Seam API.

<img alt="" />

## Overview

Seam provides a universal API to connect and control many brands of locks. This guide provides a rapid introduction to connecting and controlling your [Wyze](https://www.seam.co/manufacturers/wyze) locks using the Seam API. To learn more about other device brands supported by the Seam API, such as Yale, Schlage, Kwikset and August, head over to our [integration page](https://www.seam.co/supported-devices-and-systems).

<Info>
  There are two types of Wyze Locks, a [Gateway Wyze Lock](https://www.wyze.com/products/wyze-lock) that supports Wi-Fi connections and a [Wyze Lock Bolt](https://www.wyze.com/products/wyze-lock-bolt) that supports bluetooth connections only.

  For **Gateway Wyze Locks** we support all normal functionality including locking or unlocking the device and setting access codes remotely through Seam as long as the lock is proplery connected to the provided gateway.

  For **Bluetooth-only Wyze Lock Bolts** we're not able to control the lock remotely (meaning no locking or unlocking the device and no setting access codes) but we are able to return some information on the lock such as the battery level and the locked / unlocked state.
</Info>

## 1 — Install Seam SDK

Seam provides client libraries for many languages, such as JavaScript, Python, Ruby, PHP, and others, as well as a Postman collection and [OpenAPI](https://connect.getseam.com/openapi.json) spec.

* JavaScript / TypeScript ([npm](https://www.npmjs.com/package/seam), [GitHub](https://github.com/seamapi/javascript))
* Python ([pip](https://pypi.org/project/seam/), [GitHub](https://github.com/seamapi/python))
* Ruby Gem ([rubygem](https://rubygems.org/gems/seam), [GitHub](https://github.com/seamapi/ruby))
* PHP ([packagist](https://packagist.org/packages/seamapi/seam), [GitHub](https://github.com/seamapi/php))
* C# ([nuget](https://www.nuget.org/packages/Seam), [GitHub](https://github.com/seamapi/csharp))

<Tabs>
  <Tab title="JavaScript">
    ```bash theme={null}
    npm i seam
    ```
  </Tab>

  <Tab title="Python">
    ```bash theme={null}
    pip install seam
    # For some development environments, use pip3 in this command instead of pip.
    ```
  </Tab>

  <Tab title="Ruby">
    ```bash theme={null}
    bundle add seam
    ```
  </Tab>

  <Tab title="PHP">
    ```bash theme={null}
    composer require seamapi/seam
    ```
  </Tab>

  <Tab title="C#">
    Install using [nuget](https://www.nuget.org/packages/Seam).
  </Tab>
</Tabs>

Once installed, [sign-up for Seam](https://console.seam.co/) to get your API key, and export it as an environment variable:

```
$ export SEAM_API_KEY=seam_test2ZTo_0mEYQW2TvNDCxG5Atpj85Ffw
```

<Info>
  This guide uses a Sandbox Workspace. Only virtual devices can be connected. If
  you need to connect a real Wyze device, use a non-sandbox workspace and API
  key.
</Info>

## 2 — Link Your Wyze with Seam

To control your Wyze locks via the Seam API, you must first authorize your Seam workspace against your Wyze account. To do so, Seam provides[Connect Webviews](/core-concepts/connect-webviews): pre-built UX flows that walk you through authorizing your application to control Wyze locks.

#### Obtain a Wyze API Key and Wyze API Key ID

You will need create a Wyze API Key for your Wyze account. To see how to create a Wyze API Key for your Wyze account, [click here](https://support.wyze.com/hc/en-us/articles/16129834216731-Creating-an-API-Key).

<Info>
  Note that both the API Key and Key ID returned from Wyze are required to connect your Wyze account to Seam. Make sure to copy both values to somewhere secure!

  <img alt="Wyze API Key example" />

  For Sandbox integrations, you can simply use `ABC123ABC` for both the API Key and API Key ID.
</Info>

#### Request a Connect Webview

<CodeGroup>
  ```javascript JavaScript theme={null}
  import { Seam } from "seam";

  const seam = new Seam();

  const { connect_webview: connectWebview } = await seam.connectWebviews.create();

  console.log(connectWebview.login_successful); // false

  // Send the webview URL to your user
  console.log(connectWebview.url);

  ```

  ```python Python theme={null}
  from seam import Seam

  seam = Seam()

  webview = seam.connect_webviews.create()

  assert webview.login_successful is False

  # Send the webview URL to your user
  print(webview.url)
  ```

  ```ruby Ruby theme={null}
  require "seam"

  seam = Seam.new(api_key: 'MY_API_KEY')

  webview = seam.connect_webviews.create()

  puts webview.login_successful # false

  # Send the webview URL to your user

  puts webview.url

  ```

  ```php PHP theme={null}
  use Seam\SeamClient;

  $seam = new SeamClient("YOUR_API_KEY");

  $webview = $seam->connect_webviews->create();
  ```
</CodeGroup>

#### Authorize Your Workspace

Navigate to the URL returned by the Webview object. Since you are using a sandbox workspace, complete the login flow by entering the Wyze [sandbox test account](/device-and-system-integration-guides/wyze-locks/wyze-sample-data)credentials below:

* **Wyze API Key ID:** ABC123ABC
* **Wyze API Key** ABC123ABC
* **email:** [jane@example.com](mailto:jane@example.com)
* **password:** 1234

<img alt="Seam Connect Webview flow to connect Wyze account with Seam" />

Confirm the Connect Webview was successful by querying its status:

<CodeGroup>
  ```javascript JavaScript theme={null}
  const updatedWebview = await seam.connectWebviews.get(
    connectWebview.connect_webview_id
  );

  console.log(updatedWebview.login_successful); // true

  ```

  ```python Python theme={null}
  updated_webview = seam.connect_webviews.get(connect_webview_id: webview.connect_webview_id)

  assert updated_webview.login_successful # true
  ```

  ```ruby Ruby theme={null}
  updated_webview = seam.connect_webviews.get(connect_webview_id: webview.connect_webview_id)

  puts updated_webview.login_successful # true

  ```

  ```php PHP theme={null}
  $webview = $seam->connect_webviews->get('729847ff-98e0-418d-aeba-1e3cb38157c6');
  assert($webview->status == 'pending');
  ```
</CodeGroup>

## 3 — Retrieve Wyze Devices

After a Wyze account is linked with Seam, you can retrieve its devices.

<CodeGroup>
  ```javascript JavaScript theme={null}
  const allLocks = await seam.locks.list();

  const someLock = allLocks[0];

  console.log(someLock.properties.battery_level);

  console.log(someLock);

  ```

  ```python Python theme={null}
  all_locks = seam.locks.list()

  some_lock = all_locks[0]

  assert some_lock.properties["battery_level"] is True

  print(some_lock)
  ```

  ```ruby Ruby theme={null}
  some_lock = seam.locks.list.first

  puts some_lock.properties.battery_level

  puts some_lock

  ```

  ```php PHP theme={null}
  use Seam\SeamClient;

  $seam = new SeamClient('YOUR_API_KEY');

  $locks = $seam->locks->list();

  echo json_encode($locks);

  */
  ```
</CodeGroup>

## 4 — Locking & Unlocking a Door

Next, you can perform the basic action of locking and unlocking the door.

> **`POST`** `/locks/lock_door`
>
> See the [API Reference](/api/locks/lock_door) for details.

## Unlock a door

<mark>`POST`</mark>
`https://connect.getseam.com/locks/unlock_door`

#### Request Body

| Name       | Type   | Description |
| ---------- | ------ | ----------- |
| device\_id | String |             |

<CodeGroup>
  ```javascript JavaScript theme={null}
  // lock the door
  await seam.locks.lockDoor(someLock.device_id);
  const updatedLock = await seam.locks.get(someLock.device_id);
  console.log(updatedLock.properties.locked); // true

  // unlock the door
  await seam.locks.unlockDoor(someLock.device_id);
  updatedLock = await seam.locks.get(someLock.device_id);
  console.log(updatedLock.properties.locked); // false

  ```

  ```python Python theme={null}
  # lock the door
  seam.locks.lock_door(device_id: some_lock.device_id)
  updated_lock = seam.locks.get(device_id: some_lock.device_id)
  assert updated_lock.properties["locked"] is True

  # Now unlock the door
  seam.locks.unlock_door(device_id: some_lock.device_id)
  updated_lock = seam.locks.get(device_id: some_lock.device_id)
  assert updated_lock.properties["locked"] is False
  ```

  ```ruby Ruby theme={null}
  # lock the door
  seam.locks.lock_door(device_id: some_lock.device_id)
  updated_lock = seam.locks.get(device_id: some_lock.device_id)
  puts updated_lock.properties.locked # true

  # unlock the door

  seam.locks.unlock_door(device_id: some_lock.device_id)
  updated_lock = seam.locks.get(device_id: some_lock.device_id)
  puts updated_lock.properties.locked # false

  ```

  ```php PHP theme={null}
  use Seam\SeamClient;

  $seam = new SeamClient('YOUR_API_KEY');

  $some_lock = $seam->locks->list()[0];

  # unlock the door
  $seam->locks->unlock_door($lock->device_id);
  # lock the door
  $seam->locks->lock_door($lock->device_id);
  ```
</CodeGroup>

## 5 — Programming Access Code on a Wyze Lock

The Seam API lets you create access codes on Wyze locks with a gateway. These codes can then be entered to unlock the door. You can find out more info about how Seam access codes in our [core concept section on access codes.](/low-level-apis/smart-locks/access-codes)

<Info>
  Wyze does not allow pin code values to be seen after the code is created. If
  you create a code through Seam, avoid changing the pin code through the app
  and instead use Seam to change any information about the code!
</Info>

<CodeGroup>
  ```javascript JavaScript theme={null}
  // create an ongoing code
  await seam.accessCodes.create({
    device_id: someLock.device_id,
    name: "Personal Access Code",
  });

  // create a timebound code
  await seam.accessCodes.create({
  device_id: someLock.device_id,
  name: "My Temp Access Code",
  starts_at: "2028-11-12T19:23:42+0000",
  ends_at: "2028-11-13T19:23:42+0000",
  });

  // use a device_id as the "device_id" parameter
  await seam.accessCodes.list({
  device_id: someLock.device_id,
  });

  /*
  [
  {
  access_code_id: '631a3a30-3fa7-462a-b3bc-65528ccf8765',
  device_id: '681bf7bc-e7c6-48e6-acfe-6dbabd0615c5',
  name: 'My Temp Access Code',
  code: null,
  is_waiting_for_code_assignment: true,
  common_code_key: null,
  type: 'time_bound',
  status: 'unset',
  starts_at: '2028-08-12T19:24:00.000Z',
  ends_at: '2028-08-13T19:24:00.000Z',
  created_at: '2023-02-08T23:28:57.061Z',
  errors: [],
  warnings: []
  },
  {
  access_code_id: '774986f8-5fad-4911-a4fb-e5a2ef9f15bd',
  device_id: '681bf7bc-e7c6-48e6-acfe-6dbabd0615c5',
  name: 'Personal Access Code',
  code: '123*12346',
  common_code_key: null,
  type: 'ongoing',
  status: 'set',
  created_at: '2023-02-08T23:10:54.096Z',
  errors: [],
  warnings: []
  },
  ]
  \*/

  ```

  ```python Python theme={null}
  # create an ongoing code
  seam.access_codes.create(
    device=some_lock,
    name="Personal Access Code")

  # create a timebound code
  seam.access_codes.create(
    device=some_lock,
    name="My Temp Access Code",
    starts_at="2028-08-12T19:23:42+0000",
    ends_at="2028-08-13T19:23:42+0000")

  # you can use a device or a device_id as the "device" parameter
  seam.access_codes.list(device=some_lock)

  # [
  #   AccessCode(access_code_id='631a3a30-3fa7-462a-b3bc-65528ccf8765', type='time_bound', code=None, starts_at='2028-08-12T19:24:00.000Z', ends_at='2028-08-13T19:24:00.000Z', name='My Temp Access Code', status='unset', common_code_key=None),
  #  AccessCode(access_code_id='4d2f4952-5446-4051-ba7e-a6fc01a376d7', type='ongoing', code='123*12346', starts_at=None, ends_at=None, name='Personal Access Code', status='set', common_code_key=None)
  #  ]

  ```

  ```ruby Ruby theme={null}
  # create an ongoing code
  seam.access_codes.create(
    device_id: some_lock.device_id, name: 'Personal Access Code'
  )

  # create a timebound code

  seam.access_codes.create(
  device_id: some_lock.device_id,
  name: 'My Temp Access Code',
  starts_at: '2028-08-12T19:23:42+0000',
  ends_at: '2028-08-13T19:23:42+0000'
  )

  seam.access_codes.list(device_id: some_lock.device_id)

  # [<Seam::AccessCode:0x00690

  # access_code_id="631a3a30-3fa7-462a-b3bc-65528ccf8765"

  # name="My Temp Access Code"

  # code=nil

  # type="time_bound"

  # starts_at=2028-08-12 19:24:00 UTC

  # ends_at=2028-08-13 19:24:00 UTC

  # errors=[]

  # warnings=[]>, <Seam::AccessCode:0x006b8

  # access_code_id="774986f8-5fad-4911-a4fb-e5a2ef9f15bd"

  # name="Personal Access Code"

  # code="123\*12346"

  # type="ongoing"

  # errors=[]

  # warnings=[]>]

  ```

  ```php PHP theme={null}
  use Seam\SeamClient;

  $seam = new SeamClient("YOUR_API_KEY");

  $some_lock = $seam->locks->list()[0];
  $seam->access_codes->create(
    device_id: $some_lock->device_id, name: 'Personal Access Code'
  );

  $seam->access_codes->create(
    device_id: $some_lock->device_id,
    name: 'My Temp Access Code',
    starts_at: '2028-08-12T19:23:42+0000',
    ends_at: '2028-08-13T19:23:42+0000'
  );

  echo json_encode($access_code)
  /*
  [{"access_code_id":"19cea367-fd8c-40b7-9ce3-6dec76fe1763","name":"My Temp Access Code","type":"time_bound","status":"unset","starts_at":"2028-08-12T19:24:00.000Z","ends_at":"2028-08-13T19:24:00.000Z","code":null,"created_at":"2023-02-09T05:53:46.293Z","errors":[],"warnings":[]},{"access_code_id":"f797a8f0-b8f7-4734-9bea-962de5cad413","name":"Personal Access Code","type":"ongoing","status":"set","starts_at":null,"ends_at":null,"code":"123*12346","created_at":"2023-02-09T05:53:46.172Z","errors":[],"warnings":[]}]
  */
  ```
</CodeGroup>

###

## Next Steps

Now that you've completed this guide, you can try to connect a real Wyze device. To do so, make sure to switch to a non-sandbox workspace and API key as real devices cannot be connected to sandbox workspaces.

In addition, if you'd like to explore other aspects of Seam, here is a list of helpful resources:

* [Yale Getting Started Guide](../yale-locks/get-started-with-yale-locks)
* [August Getting Started Guide](../august-locks/get-started-with-august-locks)
* [Schlage Getting Started Guide](../schlage-locks/get-started-with-schlage-locks)
* [SmartThings Getting Started Guide](../smartthings-hubs-+-devices/get-started-with-smartthings-hubs-+-smart-locks)
* [Receiving webhook](/developer-tools/webhooks) for [device events](/api/events/list)
* [Core Concepts](/core-concepts/overview)

If you have any questions or want to report an issue, email us at [support@seam.co](mailto:support@seam.co).


# Wyze Locks
Source: https://docs.seam.co/device-and-system-integration-guides/wyze-locks/index

Guide for using Wyze locks with Seam

<img alt="Wyze logo" />

## Overview

Wyze produces a smart lock with an accompanying gateway and an optional keypad. Intended for the residential and short-term rental industries, Wyze Locks provide fast installation, virtual keys, and automatic unlocking and locking functionality. Wyze Locks replace only the interior side of existing deadbolts, so existing physical keys still work. Further, Wyze Locks are compatible with most single-cylinder deadbolts.

To integrate the Wyze Smart Lock with Seam, you must first install the Wyze Lock Gateway and connect this gateway to the internet.

***

## Supported Devices

<DeviceList />

This integration supports the [Wyze Lock](https://www.wyze.com/products/wyze-lock), when accompanied by a [Wyze Lock Gateway](https://support.wyze.com/hc/en-us/articles/360037584772-How-does-Wyze-Lock-connect-to-the-internet-) that is connected to the internet. In addition, this integration supports access code functions for the optional [Wyze Lock Keypad](https://www.wyze.com/products/wyze-lock-keypad).

<Info>
  Seam does not integrate with the [Wyze Lock
  Bolt](https://www.wyze.com/products/wyze-lock-bolt).
</Info>

For detailed information about the Wyze devices that Seam supports, see our [Wyze Supported Devices page](https://www.seam.co/manufacturers/wyze).

***

## Supported Features

We support the following features:

* [Triggering web lock and unlock actions](/low-level-apis/smart-locks/lock-and-unlock)
* [Programming access codes](/low-level-apis/smart-locks/access-codes) on locks that have an installed Wyze Lock Keypad

<Info>
  The Seam platform cannot determine the PIN codes for access codes that were
  created outside of the Seam platform.
</Info>

***

### Device Provider Key

Seam identifies these devices with the `wyze` device provider key. By default, a [Connect Webview](/core-concepts/connect-webviews) displays all of the stable providers that Seam supports, so your users can connect their Wyze devices without you specifying a provider list. To narrow what a Connect Webview displays, see [Customize the Brands to Display in Your Connect Webviews](/core-concepts/connect-webviews/customizing-connect-webviews#customize-the-brands-to-display-in-your-connect-webviews).

***

## Setup Instructions

For instructions on connecting Wyze locks to Seam, see the [Wyze Setup Guide](./wyze-setup-guide).

***

## Where to Order

To purchase Wyze devices, visit the Wyze online store.

<table>
  <thead>
    <tr>
      <th />

      <th />

      <th />

      <th />

      <th />
    </tr>
  </thead>

  <tbody>
    <tr>
      <td />

      <td>
        <strong>Wyze Online Store</strong>
      </td>

      <td />

      <td>
        <a href="https://www.wyze.com/products/wyze-lock">
          [https://www.wyze.com/products/wyze-lock](https://www.wyze.com/products/wyze-lock)
        </a>
      </td>

      <td />
    </tr>
  </tbody>
</table>

***


# Sandbox Wyze Locks
Source: https://docs.seam.co/device-and-system-integration-guides/wyze-locks/wyze-sample-data

Add virtual Wyze locks to your Seam sandbox workspace using these sample API key credentials to test your integration without real hardware.

Use the following set of credentials to add virtual [Wyze locks](/device-and-system-integration-guides/wyze-locks) to your Seam [sandbox workspace](/core-concepts/workspaces#sandbox-workspaces):

| Field           | Value                                                                                      |
| --------------- | ------------------------------------------------------------------------------------------ |
| Wyze API Key ID | ABC123ABC                                                                                  |
| Wyze API Key    | ABC123ABC                                                                                  |
| Email           | [jane@example.com](mailto:jane@example.com) or any email address in the example.com domain |
| Password        | 1234                                                                                       |


# Wyze Setup Guide
Source: https://docs.seam.co/device-and-system-integration-guides/wyze-locks/wyze-setup-guide

Connect your Wyze locks to Seam.

To use Seam with Wyze locks, ask the device owner to complete the steps below. Locks must already be installed and connected to a Wyze Lock Gateway before proceeding.

### 1. Set up the Wyze app

1. Download and install the [Wyze app](https://support.wyze.com/hc/en-us/articles/360032748451-Wyze-App-Setup-Guide) and create an account if you don't have one.
2. In the Wyze app, add your Wyze devices.

### 2. Create a Wyze API key

1. Log in to the [Wyze developer portal](https://developer-api-console.wyze.com/#/apikey/view).
2. Click **Create an API key**.
3. Click **view** and note the API key.

### 3. Connect Wyze to Seam

1. In the form to connect Wyze to Seam, enter your Wyze app login credentials and the API key you created.
2. Click **Submit** to complete.

***

### Troubleshooting

If devices don't appear after connecting your account:

* Verify that each lock is online and connected to a Wyze Lock Gateway in the Wyze app.
* Confirm that you entered the correct API key from the Wyze developer portal.


# Get started with Yale Locks
Source: https://docs.seam.co/device-and-system-integration-guides/yale-locks/get-started-with-yale-locks

Learn how to connect and control your Yale lock with the Seam API.

## Overview

Seam provides a universal API to connect and control many brands of smart locks. This guide provides a rapid introduction to connecting and controlling your [Yale](https://www.seam.co/manufacturers/yale) lock using the Seam API. Note that this guide is intended for Yale locks connected via the Yale wifi bridge and Yale access app. For Z-Wave Yale devices, head over to [our guide for SmartThings](../smartthings-hubs-+-devices/get-started-with-smartthings-hubs-+-smart-locks).

To learn more about other smart lock brands supported by Seam such as August, Schlage, and Salto, head over to our [integration page](https://www.seam.co/supported-devices-and-systems).

## 1 — Install Seam SDK

Seam provides client libraries for many languages, such as JavaScript, Python, Ruby, PHP, and others, as well as a Postman collection and [OpenAPI](https://connect.getseam.com/openapi.json) spec.

* JavaScript / TypeScript ([npm](https://www.npmjs.com/package/seam), [GitHub](https://github.com/seamapi/javascript))
* Python ([pip](https://pypi.org/project/seam/), [GitHub](https://github.com/seamapi/python))
* Ruby Gem ([rubygem](https://rubygems.org/gems/seam), [GitHub](https://github.com/seamapi/ruby))
* PHP ([packagist](https://packagist.org/packages/seamapi/seam), [GitHub](https://github.com/seamapi/php))
* C# ([nuget](https://www.nuget.org/packages/Seam), [GitHub](https://github.com/seamapi/csharp))

<Tabs>
  <Tab title="JavaScript">
    ```bash theme={null}
    npm i seam
    ```
  </Tab>

  <Tab title="Python">
    ```bash theme={null}
    pip install seam
    # For some development environments, use pip3 in this command instead of pip.
    ```
  </Tab>

  <Tab title="Ruby">
    ```bash theme={null}
    bundle add seam
    ```
  </Tab>

  <Tab title="PHP">
    ```bash theme={null}
    composer require seamapi/seam
    ```
  </Tab>

  <Tab title="C#">
    Install using [nuget](https://www.nuget.org/packages/Seam).
  </Tab>
</Tabs>

Once installed, [sign-up for Seam](https://console.seam.co/) to get your API key, and export it as an environment variable:

```
$ export SEAM_API_KEY=seam_test2ZTo_0mEYQW2TvNDCxG5Atpj85Ffw
```

<Info>
  This guide uses a Sandbox Workspace. Only virtual devices can be connected. If
  you need to connect a real Yale Lock, use a non-sandbox workspace and API key.
</Info>

## 2 — Link Yale Account with Seam

To control your Yale lock via the Seam API, you must first authorize your Seam workspace against your Yale account. To do so, Seam provides[ Connect Webviews](/core-concepts/connect-webviews): pre-built UX flows that walk you through authorizing your application to control your Yale lock.

<Info>
  Note that `yale_access` or `yale_home` are now deprecated in favor of
  just`yale` which will work with whichever version of the Yale backend.
</Info>

#### Request a Connect Webview

<CodeGroup>
  ```javascript JavaScript theme={null}
  import { Seam } from 'seam'

  const seam = new Seam()

  const { connect_webview: connectWebview } = await seam.connectWebviews.create()

  console.log(connectWebview.login_successful) // false

  // Send the webview URL to your user
  console.log(connectWebview.url)

  ```

  ```python Python theme={null}
  from seam import Seam

  seam = Seam()

  webview = seam.connect_webviews.create()

  assert webview.login_successful is False

  # Send the webview URL to your user
  print(webview.url)
  ```

  ```ruby Ruby theme={null}
  require "seam"

  seam = Seam.new(api_key: "MY_API_KEY")

  webview = seam.connect_webviews.create()

  puts webview.login_successful # false

  # Send the webview URL to your user

  puts webview.url

  ```
</CodeGroup>

#### Authorize Your Workspace

Navigate to the URL returned by the Webview object. Since you are using a sandbox workspace, complete the login flow by entering the Yale [sandbox test accounts ](/device-and-system-integration-guides/yale-locks/yale-sample-data)credentials below:

* **email:** [jane@example.com](mailto:jane@example.com)
* **password:** 1234
* **2-factor-auth:** 123456

<img alt="Seam Connect Webview flow to connect Yale account with Seam" />

Confirm the Connect Webview was successful by querying its status:

<CodeGroup>
  ```javascript JavaScript theme={null}
  const updatedWebview = await seam.connectWebviews.get(
    connectWebview.connect_webview_id,
  )

  console.log(updatedWebview.login_successful) // true
  ```

  ```python Python theme={null}
  updated_webview = seam.connect_webviews.get(connect_webview_id: webview.connect_webview_id)

  assert updated_webview.login_successful # true

  ```

  ```ruby Ruby theme={null}
  updated_webview = seam.connect_webviews.get(connect_webview_id: webview.connect_webview_id)

  puts updated_webview.login_successful # true
  ```
</CodeGroup>

## 3 — Retrieve Yale Lock Devices

After a Yale account is linked with Seam, you can retrieve devices for this Yale account. The Seam API exposes most of the device's properties such as battery level or door lock status.

<CodeGroup>
  ```javascript JavaScript theme={null}
  const allLocks = await seam.locks.list()

  const someLock = allLocks[0]

  console.log(someLock.properties.online) // true
  console.log(someLock.properties.locked) // true

  console.log(someLock)
  /*
  {
  device_id: 'b013d947-cef1-4dfe-8aa2-1e452eca5262',
  device_type: 'yale_lock',
  capabilities_supported: [ 'access_code', 'lock' ],
  properties: {
  locked: true,
  online: true,
  door_open: false,
  manufacturer: 'august',
  battery_level: 0.9999532347993827,
  august_metadata: {
  lock_id: 'lock-2',
  lock_name: 'BACK DOOR',
  has_keypad: true,
  house_name: 'My House'
  },
  name: 'BACK DOOR'
  },
  location: null,
  connected_account_id: '2a860181-dba7-49aa-9d5e-a66ff585dc08',
  workspace_id: 'd7418ff3-a476-4f48-9a4b-211d1d21a03d',
  created_at: '2022-12-16T00:52:16.975Z',
  errors: [],
  warnings: []
  }
  */

  ```

  ```python Python theme={null}
  all_locks = seam.locks.list()

  some_lock = all_locks[0]

  assert some_lock.properties["online"] is True
  assert some_lock.properties["locked"] is True

  print(some_lock)
  # Device(
  #   device_id='b013d947-cef1-4dfe-8aa2-1e452eca5262',
  #   device_type='yale_lock',
  #   location=None,
  #   properties={
  #     'locked': True,
  #     'online': True,
  #     'door_open': False,
  #     'manufacturer': 'august',
  #     'battery_level': 0.9999532347993827,
  #     'august_metadata': {...},
  #     'name': 'BACK DOOR'},
  #     capabilities_supported=['access_code', 'lock']
  #     )
  ```

  ```ruby Ruby theme={null}
  some_lock = seam.locks.list.first

  puts some_lock.properties.online # true
  puts some_lock.properties.locked # true

  puts some_lock # warnings=[]> # errors=[] # created_at=2022-12-16 00:52:16.975 UTC # } # "name"=>"BACK DOOR" # "august_metadata"=>{...}, # "battery_level"=>0.9999532347993827, # "manufacturer"=>"august", # "door_open"=>false, # "online"=>true, # "locked"=>true, # properties={ # device_type="yale_lock" # device_id="b013d947-cef1-4dfe-8aa2-1e452eca5262" # <Seam::Device:0x00960

  ```
</CodeGroup>

### 4 — Locking & Unlocking a Door

Next, you can perform the basic action of locking and unlocking the door.

> **`POST`** `/locks/lock_door`
>
> See the [API Reference](/api/locks/lock_door) for details.

## Unlock a door

<mark>`POST`</mark> `https://connect.getseam.com/locks/unlock_door`

#### Request Body

| Name       | Type   | Description |
| ---------- | ------ | ----------- |
| device\_id | String |             |

<CodeGroup>
  ```javascript JavaScript theme={null}
  // lock the door
  await seam.locks.lockDoor(someLock.device_id)
  const updatedLock = await seam.locks.get(someLock.device_id)
  console.log(updatedLock.properties.locked) // true

  // unlock the door
  await seam.locks.unlockDoor(someLock.device_id)
  updatedLock = await seam.locks.get(someLock.device_id)
  console.log(updatedLock.properties.locked) // false
  ```

  ```python Python theme={null}
  # lock the door
  seam.locks.lock_door(device_id: some_lock.device_id)
  updated_lock = seam.locks.get(device_id: some_lock.device_id)
  assert updated_lock.properties["locked"] is True

  # Now unlock the door

  seam.locks.unlock_door(device_id: some_lock.device_id)
  updated_lock = seam.locks.get(device_id: some_lock.device_id)
  assert updated_lock.properties["locked"] is False

  ```

  ```ruby Ruby theme={null}
  # lock the door
  seam.locks.lock_door(device_id: some_lock.device_id)
  updated_lock = seam.locks.get(device_id: some_lock.device_id)
  puts updated_lock.properties.locked # true

  # unlock the door
  seam.locks.unlock_door(device_id: some_lock.device_id)
  updated_lock = seam.locks.get(device_id: some_lock.device_id)
  puts updated_lock.properties.locked # false
  ```
</CodeGroup>

### 5 — Setting Access Code on Yale Lock

Most Yale locks come with a keypad built-in to program access codes. These codes can then be entered to unlock a Yale lock.

The Seam API makes it easy to program both `ongoing` codes and `timebound` codes on a Yale lock. You can find out more about Yale lock access code in our [core concept section on access codes.](/low-level-apis/smart-locks/access-codes)

<CodeGroup>
  ```javascript JavaScript theme={null}
  // create an ongoing code
  await seam.accessCodes.create({
    device_id: someLock.device_id,
    code: '123456',
    name: 'Personal Access Code',
  })

  // create a timebound code
  await seam.accessCodes.create({
  device_id: someLock.device_id,
  code: '888888',
  name: 'My Temp Access Code',
  starts_at: '2028-11-12T19:23:42+0000',
  ends_at: '2028-11-13T19:23:42+0000',
  })

  // use a device_id as the "device_id" parameter
  await seam.accessCodes.list({
  device_id: someLock.device_id,
  })

  /*
  [
  {
  code: '1988',
  type: 'ongoing',
  status: 'setting',
  created_at: '2022-08-26T12:50:17.858Z',
  access_code_id: '26d6138c-6524-4f3c-ac96-43cc3bea0a8d'
  },
  {
  type: 'timebound',
  code: '888888',
  starts_at: '2028-08-12T19:24:00.000Z',
  ends_at: '2028-08-13T19:24:00.000Z',
  access_code_id: '8c2db4da-b137-4c08-a2c3-d611e6ff91b3',
  }
  ]
  */

  ```

  ```python Python theme={null}
  # create an ongoing code
  seam.access_codes.create(
      device=some_lock, code="123456", name="Personal Access Code"
  )

  # create a timebound code
  seam.access_codes.create(
      device=some_lock,
      code="888888",
      name="My Temp Access Code",
      starts_at="2028-08-12T19:23:42+0000",
      ends_at="2028-08-13T19:23:42+0000"
  )

  # you can use a device or a device_id as the "device" parameter
  seam.access_codes.list(device=some_lock)
  # [
  #   AccessCode(
  #     access_code_id='af5272b1-2a49-4eb5-9388-2447fc7b5bd1',
  #     type='ongoing',
  #     code='123459'
  #   ),
  #   AccessCode(
  #     access_code_id='8c2db4da-b137-4c08-a2c3-d611e6ff91b3',
  #     type='timebound',
  #     code='888888',
  #     starts_at='2028-08-12T19:24:00.000Z',
  #     ends_at='2028-08-13T19:24:00.000Z',
  #   )
  # ]

  ```

  ```ruby Ruby theme={null}
  # create an ongoing code
  seam.access_codes.create(
    device_id: some_lock.device_id, code: '123456', name: 'Personal Access Code'
  )

  # create a timebound code

  seam.access_codes.create(
  device_id: some_lock.device_id,
  code: '888888',
  name: 'My Temp Access Code',
  starts_at: '2028-08-12T19:23:42+0000',
  ends_at: '2028-08-13T19:23:42+0000'
  )

  seam.access_codes.list(device_id: some_lock.device_id)

  # [<Seam::AccessCode:0x00730

  # code="888888"

  # name="My Temp Access Code"

  # type="time_bound"

  # errors=[]

  # warnings=[]

  # access_code_id="ce2c298c-364f-4b13-aa12-712f3976288e"

  # ends_at=2028-08-13 19:24:00 UTC

  # starts_at=2028-08-12 19:24:00 UTC>, <Seam::AccessCode:0x00758

  # code="123456"

  # name="Personal Access Code"

  # type="ongoing"

  # errors=[]

  # warnings=[]

  # access_code_id="75f49550-fc9b-481a-a158-5bc53ac9bb34">, <Seam::AccessCode:0x00780

  # code="086355"

  # name="some-code2"

  # type="ongoing"

  # errors=[]

  # warnings=[]

  # access_code_id="5243e5f3-528a-4378-ba3c-21447bf844a8">, <Seam::AccessCode:0x007a8

  # code="376525"

  # name="some-code"

  # type="ongoing"

  # errors=[]

  # warnings=[]

  # access_code_id="91a08a3d-a0bb-4ff0-bfb4-ced164353988">]

  ```
</CodeGroup>

###

## Next Steps

Now that you've completed this guide, you can try to connect a real Yale device. To do so, make sure to switch to a non-sandbox workspace and API key as real devices cannot be connected to sandbox workspaces.

In addition, if you'd like to explore other aspects of Seam, here is a list of helpful resources:

* [Schlage Getting Started Guide](../schlage-locks/get-started-with-schlage-locks)
* [August Getting Started Guide](../august-locks/get-started-with-august-locks)
* [SmartThings Getting Started Guide](../smartthings-hubs-+-devices/get-started-with-smartthings-hubs-+-smart-locks)
* [Receiving webhook](/developer-tools/webhooks) for [device events](/api/events/list)
* [Core Concepts](/core-concepts/overview)

If you have any questions or want to report an issue, email us at [support@seam.co](mailto:support@seam.co).


# Yale Locks
Source: https://docs.seam.co/device-and-system-integration-guides/yale-locks/index

Guide for using Yale door locks with Seam

<img alt="Yale logo" />

## Overview

Yale manufacturers some of the most advanced smart locks on the market such as the Yale [Assure](https://amzn.to/452zo6n) and [Nextouch](https://amzn.to/3DAeRdP) locks. With a unique interchangeable network module, Yale Locks are designed to be incredibly versatile, allowing for compatibility with a range of communication standards such as Z-wave, Wi-Fi, Bluetooth, and Zigbee. This adaptability ensures that they seamlessly fit into various smart home ecosystems.

***

## Supported Devices

<DeviceList />

The Seam integration is tailored for Yale Locks that are connected via the following platforms:

* [**Yale Home**](https://www.yalehome.com/au/en/products/smart-products/yale-home-app) **or** [**Yale Access**](https://www.yalehome.com/us/en/products/smart-technology/yale-access) **apps**: Some Yale locks come with built-in WiFi support, enabling them to connect directly to the Yale Home app (for global implementations) or Yale Access app (for North American implementations). However, for locks without integrated WiFi, you must install the [Yale Access Upgrade Kit](https://amzn.to/3OyUVOT) for compatibility with these apps.\
  <img alt="" />\
  [**Yale Access Upgrade Kit**](https://www.amazon.com/Yale-Bluetooth-Upgrade-Assure-Levers/dp/B07GPXN936?hvadid=309748512713\&hvpos=\&hvnetw=g\&hvrand=898690352114198212\&hvpone=\&hvptwo=\&hvqmt=\&hvdev=c\&hvdvcmdl=\&hvlocint=\&hvlocphy=9031939\&hvtargid=pla-628163958927\&psc=1\&linkCode=sl1\&tag=seam0f-20\&linkId=2a3f40625fb6f9267c822adfd793a950\&language=en_US\&ref_=as_li_ss_tl)

<Info>
  Seam does not currently support integration with the Yale Smart Living app
  (for implementations in Europe, the Middle East, India, and Africa) or the
  Yale Connect app (mainly for implementations in Latin America).
</Info>

* **Z-Wave with** [**Aeotec SmartThings**](https://amzn.to/44OulH1): To use Yale Locks with these Z-Wave based hubs, the lock must have the [Yale Z-Wave network module](https://amzn.to/3DC9nis) installed. This module ensures seamless communication between the lock and the hub, allowing for integration into broader smart home setups.\
  <img alt="" />\
  [**Yale Z-Wave Network Module**](https://www.amazon.com/Yale-Z-wave-Module-Electronic-AYR202-ZWV-USA/dp/B07B1G5LR9?crid=1M97DIL3OHT0E\&keywords=yale+z-wave+plus+module\&qid=1690480444\&sprefix=yale+z-wave+plus+module,aps,318\&sr=8-1\&ufe=app_do:amzn1.fos.f5122f16-c3e8-4386-bf32-63e904010ad0\&linkCode=sl1\&tag=seam0f-20\&linkId=62ce481be465b16a59d4e8e1f69e4965\&language=en_US\&ref_=as_li_ss_tl)

When purchasing a Yale Lock or a network module separately, always verify the specific compatibility needs for your desired setup.

For detailed information about the Yale devices that Seam supports, see our [Yale Supported Devices page](https://www.seam.co/manufacturers/yale).

***

## Supported Features

We support the following features:

* [Triggering web unlock actions](/api/locks/unlock_door)
* [Programming access codes](/low-level-apis/smart-locks/access-codes) on door locks that have a keypad

***

### Device Provider Key

Seam identifies these devices with the `yale` device provider key. By default, a [Connect Webview](/core-concepts/connect-webviews) displays all of the stable providers that Seam supports, so your users can connect their Yale devices without you specifying a provider list. To narrow what a Connect Webview displays, see [Customize the Brands to Display in Your Connect Webviews](/core-concepts/connect-webviews/customizing-connect-webviews#customize-the-brands-to-display-in-your-connect-webviews).

***

## Troubleshooting

### Yale Home and Yale Access-Specific Access Code Errors

Since August and Yale are both using the same app to control the locks, you might see this `august_*` prefix on your errors.

`august_device_programming_delay`

Yale has acknowledged a request to program the code, but the access code has not yet been fully moved to the device. The device likely has a flaky internet connection. We will continue to try and set the code on the device.

`august_device_slots_full`

All access code slots on the device are full. Please remove some codes from the lock to resolve this.

`august_lock_bad_access_code_format`

The access code format is not correct. Please delete the code and try programming it again.

`august_lock_missing_keypad`

The Yale lock is missing a keypad. You could install an [August keypad](https://amzn.to/3rOdSUN) to add key code functionality to your door lock.

`august_lock_temporarily_offline`

August lock was temporarily offline while setting/removing a code, the code should be set/remove when it comes back online.

### SmartThings Hub-Specific Access Code Errors

`smartthings_failed_to_set_after_multiple_retries`

When you encounter this error, it means that Seam has failed to set code on device after multiple retries. This may be due to a conflict with an existing code on the device that was created by a user, or by other software that may be used to program codes. To fix this, delete any conflicting codes. Please also make sure that other applications like like Rboy or Operto are disabled on the device.

`smartthings_no_free_slots_available`

When you encounter this error, it means that here are no more free slots available on the device. You will need to delete existing codes before more codes can be added to the device.

***

## Where to Order

Here are a few recommended vendors you can use to order Yale locks. Some of these vendors can even help with installation services.

<CardGroup>
  <Card title="Amazon - Yale Locks" href="https://amzn.to/3q5R5TM" />

  <Card title="GoKeyless - Yale Locks" href="https://www.gokeyless.com/pa_brand/yale-home/" />
</CardGroup>


# Sandbox Yale Locks
Source: https://docs.seam.co/device-and-system-integration-guides/yale-locks/yale-sample-data

Add virtual Yale locks to your Seam sandbox workspace using these sample credentials and two-factor codes to test your integration.

Use any of the following set of credentials to add virtual [Yale locks](/device-and-system-integration-guides/yale-locks) to your Seam [sandbox workspace](/core-concepts/workspaces#sandbox-workspaces):

| Email Address                                 | Password | Two Factor Code |
| --------------------------------------------- | -------- | --------------- |
| [jane@example.com](mailto:jane@example.com)   | 1234     | 123456          |
| [john@example.com](mailto:john@example.com)   | 1234     | 123456          |
| [sam@example.com](mailto:sam@example.com)     | 1234     | 123456          |
| [frodo@example.com](mailto:frodo@example.com) | 1234     | 123456          |


# Implementing Access Codes
Source: https://docs.seam.co/device-manufacturer-guidance/building-a-seam-compatible-smart-lock-api/implementing-access-codes

How to create, update, list, and track PIN codes on smart locks through your API.

Seam relies on access codes to support hospitality, multifamily, coworking, and STR use cases. Your API should let Seam create user-defined PIN codes, manage their validity windows, and receive events when codes are used or fail.

***

### Creating an access code

Seam specifies the PIN value and validity window (if supported). Your API should return an immediate acknowledgement and send a status event when the code is fully applied to the device. If the request is invalid or the device cannot accept a new code, your API should return [an error response](#common-error-responses) immediately instead of a pending status.

#### Create code request

`POST https://devicecloud.example.com/locks/<LOCK_ID>/access_codes`

```json theme={null}
{
  "name": "Jane Lo",
  "code": "4829",
  "starts_at": "2025-05-22T15:00:00Z",
  "ends_at": "2025-05-25T11:00:00Z"
}
```

#### Expected synchronous response

```json theme={null}
{
  "access_code_id": "ac_55301",
  "name": "Jane Lo",
  "status": "pending",
  "code": "4829",
  "starts_at": "2025-05-21T15:00:00Z",
  "ends_at": "2025-05-24T11:00:00Z"
}
```

If the lock is offline, you may return a pending state or reject immediately:

```json theme={null}
{
  "error_code": "DEVICE_OFFLINE",
  "message": "The device is currently offline and cannot receive new access codes."
}
```

#### Access code applied event

Once the device successfully stores the PIN, your API should send a webhook event.

```json theme={null}
{
  "event_type": "access_code.created",
  "access_code": {
    "access_code_id": "ac_55301",
    "lockk_id": "lock_123",
    "code": "4829",
    "starts_at": "2025-05-21T16:00:00Z",
    "ends_at": "2025-05-24T12:00:00Z",
    "status": "active"
  },
  "status": "success",
  "timestamp": "2025-05-22T14:59:12Z"
}
```

***

### Updating an access code

If your platform allows modification, Seam may update the validity window or replace the PIN value.

If the request is invalid or the device cannot accept changes, your API should return [an error response](#common-error-responses) immediately instead of a pending status.

#### Update request

`PATCH https://devicecloud.example.com/access_codes/<ACCESS_CODE_ID>`

```jsonnet theme={null}
{
  "starts_at": "2025-05-22T16:00:00Z",
  "ends_at": "2025-05-25T12:00:00Z"
}
```

#### Update response

```json theme={null}
{
  "access_code_id": "ac_55301",
  "status": "pending",
  "starts_at": "2025-05-22T16:00:00Z",
  "ends_at": "2025-05-25T12:00:00Z"
}
```

#### Update applied event

```json theme={null}
{
  "event_type": "access_code.updated",
  "access_code": {
    "access_code_id": "ac_55301",
    "lock_id": "lock_123",
    "code": "4829",
    "starts_at": "2025-05-22T16:00:00Z",
    "ends_at": "2025-05-25T12:00:00Z",
    "status": "active"
  },
  "status": "success",
  "timestamp": "2025-05-22T16:01:12Z"
}
```

***

### Deleting an access code

Seam may remove a PIN code when a reservation ends or a user revokes access.

#### Delete request

`DELETE https://devicecloud.example.com/access_codes/<ACCESS_CODE_ID>`

#### Delete response

```json theme={null}
{
  "access_code_id": "ac_55301",
  "status": "pending"
}
```

#### Delete applied event

```json theme={null}
{
  "event_type": "access_code.deleted",
  "access_code_id": "ac_55301",
  "status": "success",
  "timestamp": "2025-05-25T11:02:44Z"
}
```

***

### Listing access codes

Your API should expose an endpoint to list all codes currently on a lock. Seam uses this to prevent duplicates and maintain state accuracy.

#### List request

`GET https://devicecloud.example.com/locks/<LOCK_ID>/access_codes`

```json theme={null}
{
  "access_codes": [
    {
      "access_code_id": "ac_55301",
      "lock_id": "lock_1234",
      "code": "4829",
      "starts_at": "2025-05-22T15:00:00Z",
      "ends_at": "2025-05-25T11:00:00Z",
      "status": "active"
    },
    {
      "access_code_id": "ac_99218",
      "lock_id": "lock_1234",
      "code": "9910",
      "starts_at": null,
      "ends_at": null,
      "status": "active"
    }
  ]
}
```

***

### Access code usage events

When an access code is used, your API should send a webhook event that includes the specific code.

#### Successful code usage

```json theme={null}
{
  "event_type": "access_code.used",
  "lock_id": "lock_491829",
  "access_code_id": "ac_55301",
  "timestamp": "2025-05-23T08:15:32Z"
}
```

***

#### Incorrect PIN attempts

If supported, your API should notify Seam when someone enters an incorrect PIN.

Being able to see incorrect pin that was set is useful for debugging access code issues.

```json theme={null}
{
  "event_type": "access_code.incorrect_attempt",
  "lock_id": "lock_491829",
  "pin": "3434",
  "timestamp": "2025-05-23T08:16:02Z"
}
```

***

### Common error responses

Your API should clearly surface code-related failures, including:

* invalid PIN format
* conflicting PIN on device
* device unable to store new codes
* device offline or out of sync

#### Example: conflicting PIN error

```
{
  "error_code": "PIN_CONFLICT",
  "message": "This PIN is already in use on the device."
}
```

***


# Implementing Authentication
Source: https://docs.seam.co/device-manufacturer-guidance/building-a-seam-compatible-smart-lock-api/implementing-authentication

A guide to implementing OAuth2 so Seam can securely connect to your platform and access user devices.

A Seam integration starts when a user signs in to their device provider and gives your platform permission to access their account. The easiest way to support this is through [OAuth2](https://oauth.net/2/), because it gives users a familiar login screen and lets your API issue secure, long-lasting tokens without exposing passwords.

***

## OAuth2 with Access + Refresh Tokens

Your API should use the standard [OAuth2 Authorization Code flow](https://oauth.net/2/).

### 1. Authorization request launches the flow

As the first step, Seam makes a GET request to your authorization URL. This should show the user a login screen from your service.

#### Example authorization request

```http theme={null}
GET https://api.provider.com/oauth/authorize?
  response_type=code&
  client_id=seam_prod_123&
  redirect_uri=https://example.com/oauth_redirect&
  scope=locks.read%20locks.write&
  prompt=login&
  state=xyz123
```

**Key expectations:**

* `prompt=login` must force the user to re-authenticate even if they have an existing session.
* `redirect_uri` should match one of the URIs Seam registers with your platform.
* `state` must be returned unchanged to prevent CSRF.

***

### 2. User login + consent screen

After Seam sends the authorization request in [step 1](#1-authorization-request-launches-the-flow), your service should display a login and consent screen. The user signs in, reviews what Seam will be able to access, and decides whether to continue.

<Columns>
  <div>
    <img alt="Example login screen from Google" />
  </div>

  <div>
    <img alt="Example consent screen from Google" />
  </div>
</Columns>

Your UI should:

* ask the user to log in
* clearly show what Seam will access
* allow them to approve or deny

This step should feel identical to signing into your own product.

***

### 3. Redirect back to Seam with a code

After approval, redirect the browser back to the provided redirect URL:

```
https://example.com/oauth_redirect
```

Your service must append the authorization code (`code`) and `state`:

```http theme={null}
https://example.com/oauth_redirect?
  code=abc123_code_from_provider&
  state=xyz123
```

**Key expectations:**

* the redirect URL must exactly match one that Seam registered with your platform.
* `code` is the temporary value Seam will exchange for tokens.
* `state` must match what Seam originally sent in [Step 1](#1-authorization-request-launches-the-flow).

***

### 4. Exchange the code for tokens

Seam will exchange the authorization code for tokens:

```http theme={null}
POST https://api.provider.com/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&
code=abc123_code_from_callback&
redirect_uri=https://connect.getseam.com/oauth/callback&
client_id=seam_prod_123&
client_secret=shhh_very_secret
```

**Expected response:**

```json theme={null}
{
  "access_token": "ya29.a0ARt76ExampleAccess",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "1//0exampleRefreshToken",
  "user_id": "provider_user_491829"
}
```

**Best practices:**

* `access_token` expires quickly (`1h` is typical)
* `refresh_token` lasts long and is stable
* `user_id` must be stable across all future authentications

***

### 5. Calling your API with the access token

Seam can call your APIs using the access token. A common way is to do it using the the standard `Authorization` header:

```http theme={null}
GET https://api.provider.com/v1/locks/123
Authorization: Bearer ya29.a0ARt76ExampleAccess
```

***

### 6. Refreshing tokens over time

Seam refreshes tokens frequently, sometimes from multiple workflows running at once.

<pre>
  <code>
    <strong>POST [https://api.provider.com/oauth/token](https://api.provider.com/oauth/token)</strong>Content-Type:
    application/x-www-form-urlencoded grant\_type=refresh\_token&
    refresh\_token=1//0exampleRefreshToken& client\_id=seam\_prod\_123&
    client\_secret=shhh\_very\_secret
  </code>
</pre>

**Expected response:**

```json theme={null}
{
  "access_token": "ya29.newAccessTokenHere",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "1//0exampleRefreshToken",
  "user_id": "provider_user_491829"
}
```

#### Key requirements

* issue a new access token
* keep existing unexpired access tokens valid
* keep the refresh token usable until Seam rotates it

***

## Additional integration requirements

### Stable User Identifier

Seam needs a permanent, account-level ID in every OAuth response so it can reconnect accounts and avoid duplicates. This ID must:

* remain the same for the lifetime of the account
* not depend on email addresses
* not change when tokens or sessions rotate

**Example access token response:**

```json theme={null}
{
  "user_id": "provider_user_491829", // stable account identifier
  "access_token": "ya29.a0ARt76ExampleAccess",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "1//0exampleRefreshToken"
}
```

***

### Multiple Redirect URLs

Seam generally likes to use separate redirect URIs for production, staging, and local development. It's preferable if your provider allows registering multiple URLs.

**Typical examples:**

```
https://connect.getseam.com/oauth/callback
https://staging.connect.getseam.com/oauth/callback
http://localhost:3020/oauth/callback
```

***

### Token Stability Requirements

Seam may refresh tokens from multiple workflows at the same time, so refreshing can’t interrupt active requests.

**Requirements:**

* issue a new access token during refresh
* let previously issued, unexpired access tokens keep working
* keep the refresh token valid until Seam rotates it
* do not force the user to sign in again or return 401s after refresh

This protects long-running provisioning jobs, onboarding polling, and parallel credential updates from unexpected failures.

***


# Implementing Lock Actions
Source: https://docs.seam.co/device-manufacturer-guidance/building-a-seam-compatible-smart-lock-api/implementing-lock-actions

How to process lock and unlock requests and send events that confirm the final outcome.

Seam must be able to send lock and unlock commands and receive clear confirmation of what happened. Your API should execute commands quickly, return an immediate status, and emit events that describe how the action occurred.

#### Lock/unlock command request

Seam calls your API to initiate a lock or unlock operation.

`POST https://devicecloud.example.com/locks/<LOCK_ID>/actions`

```json theme={null}
{
  "action": "unlock",
  "custom_id": "req_98aa221" // optional but recommended, allow custom ID to be included.
}
```

#### Expected synchronous response

Your API should return an immediate success or failure result indicating whether the command was accepted on your end.

```json theme={null}
{
  "action_id": "act_23423",
  "custom_id": "req_98aa221",
  "status": "pending",
  "lock_id": "lock_491829",
  "action": "unlock"
}
```

If the command is rejected immediately due to a known condition:

```json theme={null}
{
  "error_code": "DEVICE_OFFLINE",
  "message": "The device is currently offline and cannot accept commands."
}
```

***

### Action completion events

After the device processes the command, your platform should send an event confirming the final result.

#### Successful unlock event

```json theme={null}
{
  "event_type": "lock.action_completed",
  "device_id": "lock_491829",
  "action_id": "act_39102",
  "custom_id": "req_39102", // be able to trace the action to the event
  "action": "unlock",
  "status": "success",
  "performed_via": "pin_code",
  "timestamp": "2025-05-22T10:45:12Z"
}
```

#### Successful lock event

```json theme={null}
{
  "event_type": "lock.action_completed",
  "device_id": "lock_491829",
  "action_id": "act_99921",
  "custom_id": "req_39102", // be able to trace the action to the event
  "action": "lock",
  "status": "success",
  "performed_via": "mobile_app",
  "timestamp": "2025-05-22T10:50:31Z"
}
```

***

### Action attribution

Each event should specify how the operation was performed. This makes it possible to correlate user intent with actual device behavior.

Common values for `performed_via`:

* `pin_code`
* `mobile_app`
* `remote_api`
* `bluetooth_key`
* `fob_card`
* `manual_turn`

#### Example:

```json theme={null}
{
  "performed_via": "fob_card"
}
```

***

### Failure modes

Your API should clearly represent lock failures when the device cannot complete the action.

#### Examples of device-side failures

* lock jammed
* bolt obstruction
* bolt not fully extended
* mechanism error
* firmware unable to accept commands

#### Failure event example

```json theme={null}
{
  "event_type": "lock.action_completed",
  "device_id": "lock_491829",
  "action_id": "act_39102",
  "action": "unlock",
  "status": "failed",
  "error_code": "LOCK_JAMMED",
  "message": "The deadbolt could not retract.",
  "timestamp": "2025-05-22T10:46:02Z"
}
```

#### Synchronous error example

If the failure is detected immediately:

```json theme={null}
{
  "error_code": "BOLT_OBSTRUCTED",
  "message": "The lock mechanism is obstructed."
}
```


# Implementing your Device Model & Discovery
Source: https://docs.seam.co/device-manufacturer-guidance/building-a-seam-compatible-smart-lock-api/implementing-your-device-model-and-discovery

How to structure your device schema and expose the endpoints Seam uses to list and sync a user’s locks.

A clean, predictable device model helps Seam present accurate information to end users and orchestrate smart-lock behavior across hospitality, multifamily, STR, and coworking environments. The fields listed below form the baseline for a Seam-compatible integration.

***

### Device Object Schema

Your API should expose a device resource with a stable, predictable structure. This lets Seam identify devices, correlate events, and display meaningful details to the user.

A typical device object includes:

* `device_id`: unique, stable identifier
* `device_type`: smart\_lock, hub, or bridge
* `device_model`: hardware model identifier
* `online`: whether your cloud can reach the device
* `battery_level`: percentage 0–100
* `signal_quality`: optional, recommended
* `location`: latitude/longitude if available
* `timezone`: IANA timezone string
* `bridge_id`: parent hub/bridge if applicable
* `lock_state`: locked, unlocked, or unknown
* `door_state`: open, closed, or ajar (if supported)

#### Device example

```json theme={null}
{
  "device_id": "lock_491829",
  "device_type": "smart_lock",
  "device_model": "LockPro X200",
  "online": true,
  "battery_level": 72,
  "signal_quality": -68,
  "location": { "latitude": 37.7859, "longitude": -122.4011 },
  "timezone": "America/Los_Angeles",
  "bridge_id": "bridge_99211",
  "lock_state": "locked",
  "door_state": "closed",
  "device_time": "2025-05-22T10:35:12Z",
  "updated_at": "2025-05-22T10:35:12Z"
}
```

***

### Listing door locks

After a lock owner logs in through OAuth, Seam lists all locks associated with their account so the user can select which devices to connect. Your API should return a JSON list of all accessible locks.

#### List All Locks Example

`GET https://devicecloud.example.com/locks`

```json theme={null}
{
  "locks": [
    {
      "lock_id": "3043fde0-3c6d-4913-981f-2607f05fe74e",
      "name": "Office Front Door",
      "model": "example_model",
      "address": "123 Amy Lane, CA, 94110, United States"
    },
    {
      "lock_id": "1c33d4cf-e178-4c06-8a9a-aadd6dc5a804",
      "name": "Back Door",
      "model": "example_model",
      "address": "999 Louis Lane, CA, 94110, United States"
    }
  ]
}
```

***

### Getting a single lock

Seam may request information about a specific lock to display full details or perform deeper synchronization.

#### Get a Lock Example

`GET https://devicecloud.example.com/locks/<LOCK_ID>`

```json theme={null}
{
  "lock_id": "3043fde0-3c6d-4913-981f-2607f05fe74e",
  "name": "Office Front Door",
  "model": "example_model",
  "address": "123 Amy Lane, CA, 94110, United States"
}
```

***

### Connectivity reporting

To keep device state fresh, your platform should send webhook events whenever connectivity changes.

* Send an event when the device goes offline
* Send another when it comes back online
* Report hub or bridge status separately

#### Online event example

```
{
  "event_type": "device.online",
  "device_id": "lock_491829",
  "timestamp": "2025-05-22T10:48:18Z"
}
```

#### Offline event example

```
{
  "event_type": "device.offline",
  "device_id": "lock_491829",
  "timestamp": "2025-05-22T10:45:01Z"
}
```

***

### Power & battery reporting

Your API should report battery percentage and emit events when power levels change.

#### Battery level example

```
{
  "battery_level": 72
}
```

#### Low-battery event

```
{
  "event_type": "battery.low",
  "device_id": "lock_491829",
  "battery_level": 15,
  "timestamp": "2025-05-22T11:02:44Z"
}
```

#### Battery replaced / charged

```
{
  "event_type": "battery.replaced",
  "device_id": "lock_491829",
  "battery_level": 100,
  "timestamp": "2025-05-22T12:10:15Z"
}
```

***

### Time & timezone reporting

Accurate time lets Seam validate access-code schedules and align audit logs. Accurate timezone data is especially important during daylight-savings transitions.

#### Required fields

* `device_time`: the current time reported by the device
* `timezone`: an IANA timezone string

#### Device-time example

```
{
  "created_at": "2025-05-22T10:30:12Z",
  "device_time": "2025-05-22T10:31:47Z",
  "timezone": "America/Los_Angeles",
  "device_model": "LockPro X200"
}
```

Seam compares `device_time` with server time to detect clock drift and identify devices that may evaluate schedules incorrectly.

#### Guidance for manufacturers

If scheduling is evaluated on-device, the reported device time and timezone must be kept accurate and updated reliably.

***

***


# Building a Seam-Compatible Smart Lock API
Source: https://docs.seam.co/device-manufacturer-guidance/building-a-seam-compatible-smart-lock-api/index

A practical guide for device manufacturers on building a robust smart lock API.

This guide outlines the technical expectations for building a smart-lock API that integrates cleanly with Seam. It covers authentication, API behavior, events, device reporting, and lock-specific features. Use this as a reference when designing or updating your API.

A Seam-compatible API delivers consistent, real-time device behavior through a predictable and modern integration surface. The following pages break down how to design each part of your API so Seam can integrate your smart locks reliably at scale.

#### What’s in this guide

* [Implementing Authentication](/device-manufacturer-guidance/building-a-seam-compatible-smart-lock-api/implementing-authentication): how to use OAuth2 with stable account identifiers
* [Implementing Your Device Model & Discovery](/device-manufacturer-guidance/building-a-seam-compatible-smart-lock-api/implementing-your-device-model-and-discovery): how to report connectivity, power, and state, and expose list/read endpoints
* [Implementing Lock Actions](/device-manufacturer-guidance/building-a-seam-compatible-smart-lock-api/implementing-lock-actions): how to accept lock/unlock commands and report final results
* [Implementing Access Codes](/device-manufacturer-guidance/building-a-seam-compatible-smart-lock-api/implementing-access-codes): how to support code creation, schedules, deletion, and usage events
* [Webhooks & Events](/device-manufacturer-guidance/building-a-seam-compatible-smart-lock-api/webhooks-and-events): how to publish real-time updates to Seam


# Webhooks & Events
Source: https://docs.seam.co/device-manufacturer-guidance/building-a-seam-compatible-smart-lock-api/webhooks-and-events

Send real-time device updates to Seam through a single webhook endpoint per environment to keep lock state, access codes, and connectivity accurate.

How to send real-time device updates to Seam through a single webhook endpoint. Seam uses webhook events to keep device state accurate without polling and to correlate lock actions, access-code changes, and connectivity updates.

***

## Webhook registration

Seam registers one webhook URL per environment (production, staging, or development).

Your API should deliver all events to the provided URL.

Correct behavior:

* one webhook URL per Seam environment
* no per-user or per-account webhook registration
* Seam maps each incoming event to the correct connected account internally

Your API should allow Seam to register this URL and specify which event types it wants to receive.

#### Webhook registration request

`POST https://devicecloud.example.com/webhooks`

```json theme={null}
{
  "url": "https://webhooks.seam.co/provider_events",
  "events": [
    "device.added",
    "device.removed",
    "device.online",
    "device.offline",
    "device.low_battery",
    "lock.action_completed",
    "access_code.created",
    "access_code.updated",
    "access_code.deleted",
    "access_code.used",
    "access_code.incorrect_attempt"
  ]
}
```

#### Webhook registration response

```json theme={null}
{
  "webhook_id": "wh_11828",
  "status": "active"
}
```

***

## Event Delivery

Your API should POST events to the registered webhook URL as they occur.

#### Example delivery

`POST https://webhooks.seam.co/provider_events`

```json theme={null}
{
  "event_type": "device.online",
  "device_id": "lock_491829",
  "timestamp": "2025-05-22T10:48:18Z"
}
```

A 2xx response means the event was accepted.

### Retry behavior

Your API should retry event delivery when Seam returns a non-2xx status.

#### Recommended approach

* Exponential backoff
* Retries for at least 24 hours
* Payload unchanged
* Maintain chronological order when possible

***

## Event Examples

### Device connectivity events

#### Device online

```json theme={null}
{
  "event_type": "device.online",
  "device_id": "lock_491829",
  "timestamp": "2025-05-22T10:48:18Z"
}
```

#### Device offline

```json theme={null}
{
  "event_type": "device.offline",
  "device_id": "lock_491829",
  "timestamp": "2025-05-22T10:45:01Z"
}
```

#### Bridge or hub offline

```json theme={null}
{
  "event_type": "bridge.offline",
  "bridge_id": "bridge_99211",
  "timestamp": "2025-05-22T10:45:01Z"
}
```

#### Device time is wrong

```json theme={null}
{
  "event_type": "device.time_wrong",
  "device_id": "lock_491829",
  "timestamp": "2025-05-22T10:45:01Z"
}
```

***

### Lock action events

#### Successful action

```json theme={null}
{
  "event_type": "lock.action_completed",
  "device_id": "lock_491829",
  "action_id": "act_39102",
  "action": "unlock",
  "status": "success",
  "performed_via": "pin_code",
  "timestamp": "2025-05-22T10:45:12Z"
}
```

#### Failed action

```json theme={null}
{
  "event_type": "lock.action_completed",
  "device_id": "lock_491829",
  "action_id": "act_39102",
  "action": "unlock",
  "status": "failed",
  "error_code": "LOCK_JAMMED",
  "message": "The deadbolt could not retract.",
  "timestamp": "2025-05-22T10:46:02Z"
}
```

***

### Access code lifecycle events

#### Code created

```json theme={null}
{
  "event_type": "access_code.created",
  "device_id": "lock_491829",
  "access_code_id": "ac_55301",
  "code": "4829",
  "status": "success",
  "starts_at": "2025-05-22T15:00:00Z",
  "ends_at": "2025-05-25T11:00:00Z",
  "timestamp": "2025-05-22T14:59:12Z"
}
```

#### Code updated

```json theme={null}
{
  "event_type": "access_code.updated",
  "access_code_id": "ac_55301",
  "status": "success",
  "timestamp": "2025-05-22T16:01:12Z"
}
```

#### Code deleted

```json theme={null}
{
  "event_type": "access_code.deleted",
  "access_code_id": "ac_55301",
  "status": "success",
  "timestamp": "2025-05-25T11:02:44Z"
}
```

***

### Access code usage events

#### Successful usage

```json theme={null}
{
  "event_type": "access_code.used",
  "device_id": "lock_491829",
  "access_code_id": "ac_55301",
  "timestamp": "2025-05-23T08:15:32Z"
}
```

#### Incorrect PIN attempt

```json theme={null}
{
  "event_type": "access_code.incorrect_attempt",
  "device_id": "lock_491829",
  "timestamp": "2025-05-23T08:16:02Z"
}
```

***

## Event format consistency

All events should follow a standard shape:

```json theme={null}
{
  "event_type": "string",
  "device_id": "string or null",
  "timestamp": "ISO-8601 timestamp",
  "data": {}
}
```

***


# Creating Access Code CRUD Endpoints
Source: https://docs.seam.co/device-manufacturer-guidance/creating-a-seam-compatible-intercom-api/creating-access-code-crud-endpoints

Build the access code CRUD endpoints your intercom API needs so Seam can list, retrieve, and remove access codes programmed on your intercoms.

## Overview

Access Codes CRUD endpoints Seam to list access codes created on an intercom.

### Listing Access Codes

After an Intercom Owner logs in and , Seam lists all the access codes that have been programmed and allows them to enable delivery on them. Your Intercom system should return a JSON list of intercoms.

### Getting an Access Code

Seam may request intercom information to display information about the intercom to the connecting user.

### Removing an Access Code

Seam unlocks doors to let in delivery people. If a door is disconnected or you're unable to unlock the door, return HTTP status code `500` with some details (see example below)


# Creating Intercom CRUD Endpoints
Source: https://docs.seam.co/device-manufacturer-guidance/creating-a-seam-compatible-intercom-api/creating-intercom-crud-endpoints

Build the intercom CRUD endpoints your API needs so Seam can list intercoms, retrieve their details, and trigger them to open doors.

## Overview

Intercom CRUD endpoints Seam to list intercoms owned by an Intercom Owner and trigger the intercom to open a door.

### Listing Intercoms

After an Intercom Owner logs in, Seam lists all the intercoms they own and allows them to enable delivery on them. Your Intercom system should return a JSON list of intercoms.

### Getting an Intercom

Seam may request intercom information to display information about the intercom to the connecting user.

### Unlocking an Intercom Door

Seam unlocks doors to let in delivery people. If a door is disconnected or you're unable to unlock the door, return HTTP status code `500` with some details (see example below)

### Other Intercom Features

You may want to include additional features for your intercom, such as configuring settings that are useful for delivery or apartment management. If you add additional endpoints, you should keep a similar URL format `/intercoms/<INTERCOM_ID>/<SOME_PROPERTY_OR_FUNCTION>`


# Creating OAuth Endpoints
Source: https://docs.seam.co/device-manufacturer-guidance/creating-a-seam-compatible-intercom-api/creating-oauth-endpoints

How to create a Seam-Compatible OAuth endpoint.

This guide will you implement the two endpoints required for OAuth 2.0 with the Authorization Code Flow, `/authorize` and `/oauth/token`. We'll also go over some OAuth concepts to make it as easy as possible.

## Terminology

* **Resource Owner** **(Intercom Owner):** The person, installer, company or end-user who owns the intercoms or can grant access to a building. This person will sign in to your server.
* **Resource/Authorization Server (Your Server)**: The server granting access to the intercom, that's what we're creating here!
* **Client (Seam)**: Application requesting access to the intercom on behalf of the Intercom Owner. This is Seam! We're a client requesting access on behalf of the intercom owner, so that the intercom owner can get delivery services.

<Info>
  If you use an external authorization provider like Auth0 or Clerk, you'll have
  a separate Resource and Authorization server. We can handle this! Contact
  `integrations@getseam.com`
</Info>

## Endpoints

### Overview

* **/authorize** - This endpoint provides a web page for the Intercom Owner to sign into
* **/oauth/token** - Client (Seam) calls this after the user signs in

### GET /authorize

This endpoint can return the HTML for a webpage for a user to sign into (expand this box to see an example!). You can use your own internal endpoints to validate the user, then, using your database, create an authorization code that we'll use in a later step. The authorization code just represents that a user successfully logged in. It can be a UUID or a random string. To avoid storing codes in your database, you may consider using a signed JWT for the authorization code.\
\
It is very important that you validate that the `redirect_uri` goes to `*.integrations.getseam.com`, or a malicious actor could gain access to your system by redirecting the Intercom Owner to their domain.

### POST /oauth/token

Seam sends you an Authorization code it got from `/authorize`, as well as a Client ID of "seam" and Client Secret, which we will provide you. While testing your login flow, you can use "seamsecret" as your Client Secret.

You should return an Access Token, which can be a long random string, UUID, or signed JWT. You'll use this access token to allow seam to access Devices and Access Codes.

Seam will attach the access token in it's `Authorization` header like so: `Authorization: Bearer <access_token>`

## Resources

* [Auth0 Authorization Code Flow documentation](https://auth0.com/docs/get-started/authentication-and-authorization-flow/authorization-code-flow)


# Creating the Health Endpoint
Source: https://docs.seam.co/device-manufacturer-guidance/creating-a-seam-compatible-intercom-api/creating-the-health-endpoint

Build a health endpoint for your intercom API so Seam can check that your service is up and running.

## Overview

Health endpoint for checking that the Service is up and running.

### Checking System Health


# Creating a Seam-Compatible Intercom API
Source: https://docs.seam.co/device-manufacturer-guidance/creating-a-seam-compatible-intercom-api/index

Make your intercom system Seam-compatible by building an HTTP REST API with OAuth and CRUD endpoints to receive deliveries from major providers.

Seam integrates with Intercom systems to enable them to receive deliveries from major delivery providers. After making your intercom API seam-compatible, you don’t need to do any additional effort to be compatible with major US delivery providers, a major selling point for US intercom systems.

To make your system compatible, you should create a HTTP REST API with OAuth for authentication and CRUD-style endpoints for listing intercoms, unlocking doors, and managing access codes. This guide will walk you through creating that API, and have examples for requests/responses. If you need any support, contact `integrations@getseam.com`

<Info>
  Seam can integrate with systems that use Authentication systems other than
  OAuth, to inquire about alternateAuthentication mechanism, briefly describe
  your system in an email to `integrations@getseam.com`
</Info>

<Info>
  No access codes on your intercom system? That's OK, as long as the system can
  be remotely unlocked most delivery providers are still compatible, just skip
  the access code CRUD endpoints.
</Info>

## Get Started

There are three links below, each link will walk you through the endpoints you'll need to create for Seam to interact with your system.

You'll need to host these endpoints on a publicly accessible server. We recommend something like `devicecloud.companyname.com`. If you already have a server and a domain, you can use a *base path* on your existing server, e.g. `companyname.com/somebasepath/...`. Seam will prepend the *base path* to all of our requests.

1. [Creating OAuth Endpoints](/device-manufacturer-guidance/creating-a-seam-compatible-intercom-api/creating-oauth-endpoints)
2. [Creating Intercom Endpoints](/device-manufacturer-guidance/creating-a-seam-compatible-intercom-api/creating-intercom-crud-endpoints)
3. [Creating Access Code Endpoints](/device-manufacturer-guidance/creating-a-seam-compatible-intercom-api/creating-access-code-crud-endpoints)
4. [Health Endpoint](../creating-a-seam-compatible-intercom-api/creating-the-health-endpoint)
5. Example Project in Python (coming soon)


# Go Live!
Source: https://docs.seam.co/go-live

Follow this guide to get your production API keys and customize your Connect Webviews.

## Create a Production Workspace

When you first sign up for Seam, [Seam Console](/core-concepts/seam-console/index) automatically creates a [sandbox workspace](/core-concepts/workspaces/index#sandbox-workspaces) for you. Sandbox workspaces are great for testing with virtual devices, but once you are ready to connect a real device, you must first create a [production workspace](/core-concepts/workspaces/index#production-workspaces).

1. In the upper-left corner of [Seam Console](https://console.seam.co/), click the workspace switcher.<img alt="Use the Seam Console workspace switcher to switch between workspaces and create new workspaces." />
2. Click **New Workspace**.
3. In the **Add a Workspace** dialog, type a name for your new workspace and your company name.
4. Disable **Sandbox mode**.
5. Click **Create Workspace**.

## Create a Production API Key

Once you have switched to your production (non-sandbox) workspace (for example, "My Production Workspace"), you must create a production API key.

1. In the top navigation pane of [Seam Console](https://console.seam.co/), click **Developer**.
2. In the left navigation pane, click **API Keys**.
3. In the upper-right corner of the **API Keys** page, click **Add API Key**.
4. In the **Add API Key** dialog, type a name for your new production API key and then click **Create API Key**.
5. Copy the newly-created API key and store it for future use.

<Info>
  Production API keys do not include the `test` token, while API keys for
  sandbox workspaces do include this `test` token. In addition, if you
  accidentally commit your API key to a GitHub repo, the `seam_` prefix is
  detected, and you are notified.
</Info>

## Customize Your Connect Webviews

You can customize your [Connect Webviews](/core-concepts/connect-webviews/index). Seam Connect Webviews are fully-embedded client-side components that you add to your app if you want to enable your users to import their own devices using your app. Your users interact with your Connect Webviews to link their device accounts with your app. That is, Connect Webviews walk your users through the process of logging in to their device accounts.

1. In the top navigation pane of [Seam Console](https://console.seam.co/), click **Developer**.
2. In the left navigation pane, click **Connect Webviews**.
3. On the **Webviews** page, click **Configure your webivew**.
4. In the **Customize your Webview** area, add a logo, choose a logo shape, update the primary button style, or change the inviter name that your Connect Webviews display to your users.


# Seam Documentation
Source: https://docs.seam.co/index

Seam makes it easy to integrate IoT devices and systems with your applications!

Connect your IoT devices and systems using Seam! From smart locks and thermostats, to whole building access control systems, Seam integrates hundreds of device types and puts them behind a standardized, intuitive API.

Grant access. Unlock doors. Set temperatures. Monitor noise. Get started with Seam!

<iframe title="YouTube video" />

<iframe title="YouTube video" />

<iframe title="YouTube video" />

***

## Getting Started

<CardGroup>
  <Card title="Quick Start (5 mins)" href="/quickstart">
    Learn how to connect a device and issue your first API call. →
  </Card>

  <Card title="Get an API Key (free)" href="https://console.seam.co/">
    Sign up for Seam Console and get your API key. →
  </Card>

  <Card title="Install a Seam SDK (free)" href="/api/installation">
    Develop your IoT apps in your favorite language. →
  </Card>
</CardGroup>

***

## Device and System APIs

Explore our device API guides to start connecting and controlling specific device and system categories.

<CardGroup>
  <Card title="Grant Access" href="/use-cases/granting-access">
    Grant access to any space with Access Grants →
  </Card>

  <Card title="Door Locks API" href="/low-level-apis/smart-locks">
    Get started →
  </Card>

  <Card title="Thermostats API" href="/capability-guides/thermostats">
    Get started →
  </Card>

  <Card title="Noise Sensors API" href="/capability-guides/noise-sensors">
    Get started →
  </Card>

  <Card title="Access Control Systems API" href="/low-level-apis/access-systems">
    Get started →
  </Card>
</CardGroup>

***

## Device and System Integration Guides

Explore our in-depth guides to get started with specific devices or systems.

<CardGroup>
  <Card title="August Locks" href="/device-and-system-integration-guides/august-locks/get-started-with-august-locks">
    Connect and control August locks. →
  </Card>

  <Card title="Yale Locks" href="/device-and-system-integration-guides/yale-locks/get-started-with-yale-locks">
    Connect and control Yale locks. →
  </Card>

  <Card title="Schlage Locks" href="/device-and-system-integration-guides/schlage-locks/get-started-with-schlage-locks">
    Connect and control Schlage locks. →
  </Card>

  <Card title="Kwikset Locks" href="/device-and-system-integration-guides/kwikset-locks/get-started-with-kwikset-wifi-locks">
    Connect and control Kwikset locks. →
  </Card>

  <Card title="Salto Locks" href="/device-and-system-integration-guides/salto-locks/get-started-with-salto-locks">
    Connect and control Salto locks and devices. →
  </Card>

  <Card title="TTLock" href="/device-and-system-integration-guides/ttlock-locks/get-started-with-ttlock-devices">
    Connect and control TTLock devices. →
  </Card>

  <Card title="Nuki Locks" href="/device-and-system-integration-guides/nuki-locks/get-started-with-nuki-locks">
    Connect and control Nuki devices. →
  </Card>

  <Card title="Minut Sensors" href="/device-and-system-integration-guides/minut-sensors/get-started-with-minut-sensors">
    Connect and control Minut sensors. →
  </Card>

  <Card title="NoiseAware Sensors" href="/device-and-system-integration-guides/noiseaware-sensors/get-started-with-noiseaware-sensors">
    Connect and control NoiseAware sensors. →
  </Card>

  <Card title="2N Intercom" href="/device-and-system-integration-guides/2n-intercom-systems/get-started-with-2n-intercoms">
    Connect and control 2N devices. →
  </Card>

  <Card title="ecobee Thermostats" href="/device-and-system-integration-guides/ecobee-thermostats/get-started-with-ecobee-thermostats">
    Connect and control ecobee thermostats. →
  </Card>

  <Card title="igloohome Locks" href="/device-and-system-integration-guides/igloohome-locks/get-started-with-igloo-locks">
    Connect and control igloohome locks. →
  </Card>
</CardGroup>


# Additional Guest Access Actions
Source: https://docs.seam.co/industry-guides/hospitality-industry-guide/additional-guest-access-actions

Handle common and edge-case hotel guest scenarios with the Seam API, including access sharing, multi-unit access, room changes, lost cards, and check-out.

You can use the Seam API to handle common and edge case guest access scenarios, such as the following:

* [Sharing access with additional guests on the same reservation](#sharing-access)
* [Multi-unit access](#multi-unit-access)
* [Mid-stay room changes](#room-changes)
* [Early check in/late check out](#early-check-in-and-late-check-out)
* [Lost cards](#lost-cards)
* [Check out](#check-out)

***

## Sharing Access

Seam Instant Key supports guest sharing. When you issue an Instant Key, you can configure how many times guests can share it. That is, you configure the desired maximum number of uses for the Instant Key.

Users can forward their Instant Key link—using text or email—to others in their reservation group, like a partner or family member. Then, people in the reservation group can use the shared Instant Key, up to the configured maximum number of uses (`max_use_count`).

<img alt="A guest can share their Instant Key with other members within their party." />

***

## Multi-unit Access

Some guests may need access to multiple rooms or amenities (for example, a suite and a gym). You can grant access to multiple sets of doors simply by specifying the desired `acs_entrance_ids` when creating an Access Grant for the guest. Alternately, you can assign the desired set of entrances to a space resource and then specify one or more `space_ids` when creating the Access Grant.

**Code:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  await seam.accessGrants.create({
    user_identity_id: janeUser.user_identity_id,
    acs_entrance_ids: [
      '48ebfb50-c531-43c5-b9ea-409f26dabbd7',
      'f74e4879-5991-4e2f-a368-888983dcfbfc',
    ],
    space_ids: [
      'c1eb6eb5-58f0-4ba3-8166-f21445ae9427',
      '2b19ddaa-44db-404b-aa2e-d99fa58020c8',
    ],
    requested_access_methods: [{ mode: 'mobile_key' }],
    starts_at: '2025-07-13T15:00:00.000Z',
    ends_at: '2025-07-16T11:00:00.000Z',
  })
  ```

  ```bash cURL theme={null}
  curl -X 'POST' \
    'https://connect.getseam.com/access_grants/create' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d "{
      \"user_identity_id\": \"$(jq -r '.user_identity.user_identity_id' <<< ${jane_user})\",
      \"acs_entrance_ids\": [
        \"48ebfb50-c531-43c5-b9ea-409f26dabbd7\",
        \"f74e4879-5991-4e2f-a368-888983dcfbfc\"
      ],
      \"space_ids\": [
        \"c1eb6eb5-58f0-4ba3-8166-f21445ae9427\",
        \"2b19ddaa-44db-404b-aa2e-d99fa58020c8\"
      ],
      \"requested_access_methods\": [
        {\"mode\": \"mobile_key\"}
      ],
      \"starts_at\": \"2025-07-13T15:00:00.000Z\",
      \"ends_at\": \"2025-07-16T11:00:00.000Z\"
  }"
  ```

  ```python Python theme={null}
  seam.access_grants.create(
    user_identity_id=jane_user.user_identity_id,
    acs_entrance_ids=[
      "48ebfb50-c531-43c5-b9ea-409f26dabbd7",
      "f74e4879-5991-4e2f-a368-888983dcfbfc"
    ],
    space_ids=[
      "c1eb6eb5-58f0-4ba3-8166-f21445ae9427",
      "2b19ddaa-44db-404b-aa2e-d99fa58020c8"
    ],
    requested_access_methods=[
      {"mode": "mobile_key"}
    ],
    starts_at="2025-07-13T15:00:00.000Z",
    ends_at="2025-07-16T11:00:00.000Z"
  )
  ```

  ```ruby Ruby theme={null}
  seam.access_grants.create(
    user_identity_id: jane_user.user_identity_id,
    acs_entrance_ids: %w[48ebfb50-c531-43c5-b9ea-409f26dabbd7 f74e4879-5991-4e2f-a368-888983dcfbfc],
    space_ids: %w[48ebfb50-c531-43c5-b9ea-409f26dabbd7 2b19ddaa-44db-404b-aa2e-d99fa58020c8],
    requested_access_methods: [
      {"mode": "mobile_key"}
    ],
    starts_at: "2025-07-13T15:00:00.000Z",
    ends_at: "2025-07-16T11:00:00.000Z"
  )
  ```

  ```php PHP theme={null}
  $seam->access_grants->create(
    user_identity_id: $jane_user->user_identity_id,
    acs_entrance_ids: [
      "48ebfb50-c531-43c5-b9ea-409f26dabbd7",
      "f74e4879-5991-4e2f-a368-888983dcfbfc",
    ],
    space_ids: [
      "c1eb6eb5-58f0-4ba3-8166-f21445ae9427",
      "2b19ddaa-44db-404b-aa2e-d99fa58020c8"
    ],
    requested_access_methods: [
      ["mode" => "mobile_key"],
    ],
    starts_at: "2025-07-13T15:00:00.000Z",
    ends_at: "2025-07-16T11:00:00.000Z"
  );
  ```

  ```csharp C# theme={null}
  // Coming Soon!
  ```
</CodeGroup>

**Output:**

<CodeGroup>
  ```json JavaScript theme={null}
  {
    "access_grant_id": "ef83cca9-5fdf-4ac2-93f3-c21c5a8be54b",
    "display_name": "My Access Grant",
    "user_identity_id": "43947360-cdc8-4db6-8b22-e079416d1d8b",
    "starts_at": "2025-07-13T15:00:00.000Z",
    "ends_at": "2025-07-16T11:00:00.000Z",
    ...
  }
  ```

  ```json cURL theme={null}
  {
    "access_grant": {
      "access_grant_id": "ef83cca9-5fdf-4ac2-93f3-c21c5a8be54b",
      "display_name": "My Access Grant",
      "user_identity_id": "43947360-cdc8-4db6-8b22-e079416d1d8b",
      "starts_at": "2025-07-13T15:00:00.000Z",
      "ends_at": "2025-07-16T11:00:00.000Z",
      ...
    }
  }
  ```

  ```python Python theme={null}
  AccessGrant(
    access_grant_id="ef83cca9-5fdf-4ac2-93f3-c21c5a8be54b",
    display_name="My Access Grant",
    user_identity_id="43947360-cdc8-4db6-8b22-e079416d1d8b",
    starts_at="2025-07-13T15:00:00.000Z",
    ends_at="2025-07-16T11:00:00.000Z",
    ...
  )
  ```

  ```ruby Ruby theme={null}
  {
    "access_grant_id" => "ef83cca9-5fdf-4ac2-93f3-c21c5a8be54b",
    "display_name" => "My Access Grant",
    "user_identity_id" => "43947360-cdc8-4db6-8b22-e079416d1d8b",
    "starts_at" => "2025-07-13T15:00:00.000Z",
    "ends_at" => "2025-07-16T11:00:00.000Z",
    ...
  }
  ```

  ```php PHP theme={null}
  [
    "access_grant_id" => "ef83cca9-5fdf-4ac2-93f3-c21c5a8be54b",
    "display_name" => "My Access Grant",
    "user_identity_id" => "43947360-cdc8-4db6-8b22-e079416d1d8b",
    "starts_at" => "2025-07-13T15:00:00.000Z",
    "ends_at" => "2025-07-16T11:00:00.000Z",
    ...
  ];
  ```

  ```json C# theme={null}
  // Coming Soon!
  ```
</CodeGroup>

***

## Room Changes

If a guest is moved to a different room during their stay, you can create a new Access Grant to update their access. Note that, for some access systems with encoded plastic cards, the guest must tap the card on an online reader to apply the changes.

***

## Early Check-In and Late Check-Out

If a guest arrives early or extends their stay, you can adjust the access schedule for access systems that support this feature, such as Salto KS. Update the `starts_at` or `ends_at` property in the Access Grant for the user.

**Code:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  await seam.accessGrants.update({
    user_identity_id: janeUser.user_identity_id,
    starts_at: '2025-07-14T15:00:00.000Z',
    ends_at: '2025-07-17T11:00:00.000Z',
  })
  ```

  ```bash cURL theme={null}
  curl -X 'POST' \
    'https://connect.getseam.com/access_grants/update' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d "{
      \"user_identity_id\": \"$(jq -r '.user_identity.user_identity_id' <<< ${jane_user})\",
      \"starts_at\": \"2025-07-14T15:00:00.000Z\",
      \"ends_at\": \"2025-07-17T11:00:00.000Z\"
  }"
  ```

  ```python Python theme={null}
  seam.access_grants.update(
    user_identity_id=jane_user.user_identity_id,
    starts_at="2025-07-14T15:00:00.000Z",
    ends_at="2025-07-17T11:00:00.000Z"
  )
  ```

  ```ruby Ruby theme={null}
  seam.access_grants.update(
    user_identity_id: jane_user.user_identity_id,
    starts_at: "2025-07-14T15:00:00.000Z",
    ends_at: "2025-07-17T11:00:00.000Z"
  )
  ```

  ```php PHP theme={null}
  $seam->access_grants->update(
    user_identity_id: $jane_user->user_identity_id,
    starts_at: "2025-07-14T15:00:00.000Z",
    ends_at: "2025-07-17T11:00:00.000Z"
  );
  ```

  ```csharp C# theme={null}
  // Coming Soon!
  ```
</CodeGroup>

**Output:**

<CodeGroup>
  ```json JavaScript theme={null}
  {
    "access_grant_id": "ef83cca9-5fdf-4ac2-93f3-c21c5a8be54b",
    "display_name": "My Access Grant",
    "user_identity_id": "43947360-cdc8-4db6-8b22-e079416d1d8b",
    "starts_at": "2025-07-14T15:00:00.000Z",
    "ends_at": "2025-07-17T11:00:00.000Z",
    ...
  }
  ```

  ```json cURL theme={null}
  {
    "access_grant": {
      "access_grant_id": "ef83cca9-5fdf-4ac2-93f3-c21c5a8be54b",
      "display_name": "My Access Grant",
      "user_identity_id": "43947360-cdc8-4db6-8b22-e079416d1d8b",
      "starts_at": "2025-07-14T15:00:00.000Z",
      "ends_at": "2025-07-17T11:00:00.000Z",
      ...
    }
  }
  ```

  ```python Python theme={null}
  AccessGrant(
    access_grant_id="ef83cca9-5fdf-4ac2-93f3-c21c5a8be54b",
    display_name="My Access Grant",
    user_identity_id="43947360-cdc8-4db6-8b22-e079416d1d8b",
    starts_at="2025-07-14T15:00:00.000Z",
    ends_at="2025-07-17T11:00:00.000Z",
    ...
  )
  ```

  ```ruby Ruby theme={null}
  {
    "access_grant_id" => "ef83cca9-5fdf-4ac2-93f3-c21c5a8be54b",
    "display_name" => "My Access Grant",
    "user_identity_id" => "43947360-cdc8-4db6-8b22-e079416d1d8b",
    "starts_at" => "2025-07-14T15:00:00.000Z",
    "ends_at" => "2025-07-17T11:00:00.000Z",
    ...
  }
  ```

  ```php PHP theme={null}
  [
    "access_grant_id" => "ef83cca9-5fdf-4ac2-93f3-c21c5a8be54b",
    "display_name" => "My Access Grant",
    "user_identity_id" => "43947360-cdc8-4db6-8b22-e079416d1d8b",
    "starts_at" => "2025-07-14T15:00:00.000Z",
    "ends_at" => "2025-07-17T11:00:00.000Z",
    ...
  ];
  ```

  ```json C# theme={null}
  // Coming Soon!
  ```
</CodeGroup>

Mobile keys update automatically to match the new time window. If a Seam Instant Key is within its validity period, it also updates automatically to match the new time window. If the Instant Key has expired, you can [generate a new one](/api/user_identities/generate_instant_key) and share the new Instant Key link with the guest. Note that, for some access systems with encoded plastic cards, the guest must tap the card on an online reader to apply the changes.

***

## Lost Cards

Once you have encoded an access method onto a card, you cannot reuse the access method for another card. If a guest loses their key card, you can create a new access method and encode it onto a new card.

**Code:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  // Create a new Access Grant.
  await seam.accessGrants.create({
    user_identity_id: janeUser.user_identity_id,
    acs_entrance_ids: [
      '48ebfb50-c531-43c5-b9ea-409f26dabbd7',
      'f74e4879-5991-4e2f-a368-888983dcfbfc',
    ],
    requested_access_methods: [{ mode: 'card' }],
    starts_at: '2025-07-13T15:00:00.000Z',
    ends_at: '2025-07-16T11:00:00.000Z',
  })

  // Encode the new card.
  const encoder = (
    await seam.acs.encoders.list({
      acs_system_ids: [hotel_a.acs_system_id],
    })
  )[0]

  const encodingActionAttempt = await seam.accessMethods.encode({
    access_method_id: 'ef3a5e10-5a76-4382-96f7-627f810ef849',
    acs_encoder_id: encoder.acs_encoder_id,
  })

  // To confirm that the encoding succeeded,
  // poll the returned action attempt
  // until its status is success.
  await seam.actionAttempts.get({
    action_attempt_id: encodingActionAttempt.action_attempt_id,
  })
  ```

  ```bash cURL theme={null}
  # Create a new Access Grant.
  curl -X 'POST' \
    'https://connect.getseam.com/access_grants/create' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d "{
      \"user_identity_id\": \"$(jq -r '.user_identity.user_identity_id' <<< ${jane_user})\",
      \"acs_entrance_ids\": [
        \"48ebfb50-c531-43c5-b9ea-409f26dabbd7\",
        \"f74e4879-5991-4e2f-a368-888983dcfbfc\"
      ],
      \"requested_access_methods\": [
        {\"mode\": \"card\"}
      ],
      \"starts_at\": \"2025-07-13T15:00:00.000Z\",
      \"ends_at\": \"2025-07-16T11:00:00.000Z\"
  }"

  # Encode the new card.
  encoder=$(curl -X 'POST' \
    'https://connect.getseam.com/acs/encoders/list' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d "{
    \"acs_system_id\": \"$(jq -r '.acs_system.acs_system_id' <<< ${hotel_a})\"
  }" | jq -r '.acs_encoders[0]')

  encoding_action_attempt=$(curl -X 'POST' \
    'https://connect.getseam.com/access_methods/encode' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d "{
    \"access_method_id\": \"ef3a5e10-5a76-4382-96f7-627f810ef849\",
    \"acs_encoder_id\": \"$(jq -r '.acs_encoder_id' <<< ${encoder})\"
  }")

  # To confirm that the encoding succeeded,
  # poll the returned action attempt
  # until its status is success.
  curl -X 'POST' \
    'https://connect.getseam.com/action_attempts/get' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d "{
    \"action_attempt_id\": \"$(jq -r '.action_attempt.action_attempt_id' <<< ${encoding_action_attempt})\"
  }"
  ```

  ```python Python theme={null}
  # Create a new Access Grant.
  seam.access_grants.create(
    user_identity_id=jane_user.user_identity_id,
    acs_entrance_ids=[
      "48ebfb50-c531-43c5-b9ea-409f26dabbd7",
      "f74e4879-5991-4e2f-a368-888983dcfbfc"
    ],
    requested_access_methods=[
      {"mode": "card"}
    ],
    starts_at="2025-07-13T15:00:00.000Z",
    ends_at="2025-07-16T11:00:00.000Z"
  )

  # Encode the new card.
  encoder = seam.acs.encoders.list(
    acs_system_ids = [hotel_a.acs_system_id]
  )[0]

  encoding_action_attempt = seam.access_methods.encode(
    access_method_id = "ef3a5e10-5a76-4382-96f7-627f810ef849",
    acs_encoder_id = encoder.acs_encoder_id
  )

  # To confirm that the encoding succeeded,
  # poll the returned action attempt
  # until its status is success.
  seam.action_attempts.get(
    action_attempt_id = encoding_action_attempt.action_attempt_id
  )
  ```

  ```ruby Ruby theme={null}
  # Create a new Access Grant.
  seam.access_grants.create(
    user_identity_id: jane_user.user_identity_id,
    acs_entrance_ids: %w[48ebfb50-c531-43c5-b9ea-409f26dabbd7 f74e4879-5991-4e2f-a368-888983dcfbfc],
    requested_access_methods: [
      {"mode": "card"}
    ],
    starts_at: "2025-07-13T15:00:00.000Z",
    ends_at: "2025-07-16T11:00:00.000Z"
  )

  # Encode the new card.
  encoder = (seam.acs.encoders.list(
    acs_system_ids: [hotel_a.acs_system_id]
  ))[0]

  encoding_action_attempt = seam.access_methods.encode(
    access_method_id: "ef3a5e10-5a76-4382-96f7-627f810ef849",
    acs_encoder_id: encoder.acs_encoder_id
  )

  # To confirm that the encoding succeeded,
  # poll the returned action attempt
  # until its status is success.
  seam.action_attempts.get(
    action_attempt_id: encoding_action_attempt.action_attempt_id
  )
  ```

  ```php PHP theme={null}
  // Create a new Access Grant.
  $seam->access_grants->create(
    user_identity_id: $jane_user->user_identity_id,
    acs_entrance_ids: [
      "48ebfb50-c531-43c5-b9ea-409f26dabbd7",
      "f74e4879-5991-4e2f-a368-888983dcfbfc",
    ],
    requested_access_methods: [
      ["mode" => "card"],
    ],
    starts_at: "2025-07-13T15:00:00.000Z",
    ends_at: "2025-07-16T11:00:00.000Z"
  );

  // Encode the access method onto a card.
  $encoder = $seam->acs->encoders->list(
    acs_system_ids: [$hotel_a->acs_system_id]
  )[0];

  $encoding_action_attempt = $seam->access_methods->encode(
    access_method_id: "ef3a5e10-5a76-4382-96f7-627f810ef849",
    acs_encoder_id: $encoder->acs_encoder_id
  );

  // To confirm that the encoding succeeded,
  // poll the returned action attempt
  // until its status is success.
  $seam->action_attempts->get(
    action_attempt_id: $encoding_action_attempt->action_attempt_id
  );
  ```

  ```csharp C# theme={null}
  // Coming Soon!
  ```
</CodeGroup>

**Output:**

<CodeGroup>
  ```json JavaScript theme={null}
  {
    "access_grant_id": "ef83cca9-5fdf-4ac2-93f3-c21c5a8be54b",
    "display_name": "My Access Grant",
    "user_identity_id": "43947360-cdc8-4db6-8b22-e079416d1d8b",
    "starts_at": "2025-07-13T15:00:00.000Z",
    "ends_at": "2025-07-16T11:00:00.000Z",
    "requested_access_methods": [
      {
        "display_name": "Plastic Card",
        "mode": "card",
        "created_access_method_ids": ["ef3a5e10-5a76-4382-96f7-627f810ef849"],
        ...
      }
    ],
    ...
  }

  {
    "status": "success",
    "action_attempt_id": "4f80761b-2bfa-401a-9f73-a08439c970f7",
    "action_type": "ENCODE_ACCESS_METHOD",
    "result": {
      "access_method_id": "ef3a5e10-5a76-4382-96f7-627f810ef849",
      "card_number": "1234abc",
      "is_issued": true,
      "issued_at": "2025-07-14T11:00:00.000Z",
      ...
    },
    "error": null
  }
  ```

  ```json cURL theme={null}
  {
    "access_grant": {
      "access_grant_id": "ef83cca9-5fdf-4ac2-93f3-c21c5a8be54b",
      "display_name": "My Access Grant",
      "user_identity_id": "43947360-cdc8-4db6-8b22-e079416d1d8b",
      "starts_at": "2025-07-13T15:00:00.000Z",
      "ends_at": "2025-07-16T11:00:00.000Z",
      "requested_access_methods": [
        {
          "display_name": "Plastic Card",
          "mode": "card",
          "created_access_method_ids": ["ef3a5e10-5a76-4382-96f7-627f810ef849"],
          ...
        }
      ],
      ...
    }
  }

  {
    "action_attempt":
      {
        "status": "success",
        "action_attempt_id": "4f80761b-2bfa-401a-9f73-a08439c970f7",
        "action_type": "ENCODE_ACCESS_METHOD",
        "result": {
          "access_method_id": "ef3a5e10-5a76-4382-96f7-627f810ef849",
          "card_number": "1234abc",
          "is_issued": true,
          "issued_at": "2025-07-14T11:00:00.000Z",
          ...
        },
        "error": null
      },
    "ok": true
  }
  ```

  ```python Python theme={null}
  AccessGrant(
    access_grant_id="ef83cca9-5fdf-4ac2-93f3-c21c5a8be54b",
    display_name="My Access Grant",
    user_identity_id="43947360-cdc8-4db6-8b22-e079416d1d8b",
    starts_at="2025-07-13T15:00:00.000Z",
    ends_at="2025-07-16T11:00:00.000Z",
    requested_access_methods=[
      {
        "display_name": "Plastic Card",
        "mode": "card",
        "created_access_method_ids": ["ef3a5e10-5a76-4382-96f7-627f810ef849"],
        ...
      }
    ],
    ...
  )

  ActionAttempt(
    status='success',
    action_attempt_id='4f80761b-2bfa-401a-9f73-a08439c970f7',
    action_type='ENCODE_ACCESS_METHOD',
    result={
      access_method_id='ef3a5e10-5a76-4382-96f7-627f810ef849',
      card_number='1234abc',
      is_issued=True,
      issued_at='2025-07-14T11:00:00.000Z',
      ...
    },
    error=null
  )
  ```

  ```ruby Ruby theme={null}
  {
    "access_grant_id" => "ef83cca9-5fdf-4ac2-93f3-c21c5a8be54b",
    "display_name" => "My Access Grant",
    "user_identity_id" => "43947360-cdc8-4db6-8b22-e079416d1d8b",
    "starts_at" => "2025-07-13T15:00:00.000Z",
    "ends_at" => "2025-07-16T11:00:00.000Z",
    "requested_access_methods" => [
      {
        "display_name": "Plastic Card",
        "mode": "card",
        "created_access_method_ids": ["ef3a5e10-5a76-4382-96f7-627f810ef849"],
        ...
      }
    ],
    ...
  }

  {
    "status" => "success",
    "action_attempt_id" => "4f80761b-2bfa-401a-9f73-a08439c970f7",
    "action_type" => "ENCODE_ACCESS_METHOD",
    "result" => {
      "access_method_id": "ef3a5e10-5a76-4382-96f7-627f810ef849"
      "card_number": "1234abc"
      "is_issued": true,
      issued_at="2025-07-13T14:00:00.000Z"
      ...
    }
    error=nil
  }
  ```

  ```php PHP theme={null}
  [
    "access_grant_id" => "ef83cca9-5fdf-4ac2-93f3-c21c5a8be54b",
    "display_name" => "My Access Grant",
    "user_identity_id" => "43947360-cdc8-4db6-8b22-e079416d1d8b",
    "starts_at" => "2025-07-13T15:00:00.000Z",
    "ends_at" => "2025-07-16T11:00:00.000Z",
    "requested_access_methods" => [
      {
        "display_name": "Plastic Card",
        "mode": "card",
        "created_access_method_ids": ["ef3a5e10-5a76-4382-96f7-627f810ef849"],
        ...
      }
    ],
    ...
  ];

  [
    "status" => "success",
    "action_attempt_id" => "4f80761b-2bfa-401a-9f73-a08439c970f7",
    "action_type" => "ENCODE_ACCESS_METHOD",
    "result" => {
      "access_method_id": "ef3a5e10-5a76-4382-96f7-627f810ef849"
      "card_number": "1234abc"
      "is_issued": true,
      issued_at="2025-07-13T14:00:00.000Z"
      ...
    }
    error=nil
  ];
  ```

  ```json C# theme={null}
  // Coming Soon!
  ```
</CodeGroup>

***

## Check Out

For some access systems, such as Salto KS, you can specify an ending time for a guest's access. Set the `ends_at` parameter when creating an Access Grant.

**Code:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  await seam.accessGrants.create({
    user_identity_id: janeUser.user_identity_id,
    acs_entrance_ids: [
      '48ebfb50-c531-43c5-b9ea-409f26dabbd7',
      'f74e4879-5991-4e2f-a368-888983dcfbfc',
    ],
    requested_access_methods: [{ mode: 'mobile_key' }],
    starts_at: '2025-07-13T15:00:00.000Z',
    ends_at: '2025-07-16T11:00:00.000Z',
  })
  ```

  ```bash cURL theme={null}
  curl -X 'POST' \
    'https://connect.getseam.com/access_methods/get' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d "{
      \"user_identity_id\": \"$(jq -r '.user_identity.user_identity_id' <<< ${jane_user})\",
      \"acs_entrance_ids\": [
        \"48ebfb50-c531-43c5-b9ea-409f26dabbd7\",
        \"f74e4879-5991-4e2f-a368-888983dcfbfc\"
      ],
      \"requested_access_methods\": [
        {\"mode\": \"mobile_key\"}
      ],
      \"starts_at\": \"2025-07-13T15:00:00.000Z\",
      \"ends_at\": \"2025-07-16T11:00:00.000Z\"
  }"
  ```

  ```python Python theme={null}
  seam.access_grants.create(
    user_identity_id=jane_user.user_identity_id,
    acs_entrance_ids=[
      "48ebfb50-c531-43c5-b9ea-409f26dabbd7",
      "f74e4879-5991-4e2f-a368-888983dcfbfc"
    ],
    requested_access_methods=[
      {"mode": "mobile_key"}
    ],
    starts_at="2025-07-13T15:00:00.000Z",
    ends_at="2025-07-16T11:00:00.000Z"
  )
  ```

  ```ruby Ruby theme={null}
  seam.access_grants.create(
    user_identity_id: jane_user.user_identity_id,
    acs_entrance_ids: %w[48ebfb50-c531-43c5-b9ea-409f26dabbd7 f74e4879-5991-4e2f-a368-888983dcfbfc],
    requested_access_methods: [
      {"mode": "mobile_key"}
    ],
    starts_at: "2025-07-13T15:00:00.000Z",
    ends_at: "2025-07-16T11:00:00.000Z"
  )
  ```

  ```php PHP theme={null}
  $seam->access_grants->create(
    user_identity_id: $jane_user->user_identity_id,
    acs_entrance_ids: [
      "48ebfb50-c531-43c5-b9ea-409f26dabbd7",
      "f74e4879-5991-4e2f-a368-888983dcfbfc",
    ],
    requested_access_methods: [
      ["mode" => "mobile_key"],
    ],
    starts_at: "2025-07-13T15:00:00.000Z",
    ends_at: "2025-07-16T11:00:00.000Z"
  );
  ```

  ```csharp C# theme={null}
  // Coming Soon!
  ```
</CodeGroup>

**Output:**

<CodeGroup>
  ```json JavaScript theme={null}
  {
    "access_grant_id": "ef83cca9-5fdf-4ac2-93f3-c21c5a8be54b",
    "display_name": "My Access Grant",
    "user_identity_id": "43947360-cdc8-4db6-8b22-e079416d1d8b",
    "starts_at": "2025-07-13T15:00:00.000Z",
    "ends_at": "2025-07-16T11:00:00.000Z",
    "instant_key_url": "https://ik.seam.co/ABCXYZ",
    ...
  }
  ```

  ```json cURL theme={null}
  {
    "access_grant": {
      "access_grant_id": "ef83cca9-5fdf-4ac2-93f3-c21c5a8be54b",
      "display_name": "My Access Grant",
      "user_identity_id": "43947360-cdc8-4db6-8b22-e079416d1d8b",
      "starts_at": "2025-07-13T15:00:00.000Z",
      "ends_at": "2025-07-16T11:00:00.000Z",
      "instant_key_url": "https://ik.seam.co/ABCXYZ",
      ...
    }
  }
  ```

  ```python Python theme={null}
  AccessGrant(
    access_grant_id="ef83cca9-5fdf-4ac2-93f3-c21c5a8be54b",
    display_name="My Access Grant",
    user_identity_id="43947360-cdc8-4db6-8b22-e079416d1d8b",
    starts_at="2025-07-13T15:00:00.000Z",
    ends_at="2025-07-16T11:00:00.000Z",
    instant_key_url="https://ik.seam.co/ABCXYZ",
    ...
  )
  ```

  ```ruby Ruby theme={null}
  {
    "access_grant_id" => "ef83cca9-5fdf-4ac2-93f3-c21c5a8be54b",
    "display_name" => "My Access Grant",
    "user_identity_id" => "43947360-cdc8-4db6-8b22-e079416d1d8b",
    "starts_at" => "2025-07-13T15:00:00.000Z",
    "ends_at" => "2025-07-16T11:00:00.000Z",
    "instant_key_url" => "https://ik.seam.co/ABCXYZ",
    ...
  }
  ```

  ```php PHP theme={null}
  [
    "access_grant_id" => "ef83cca9-5fdf-4ac2-93f3-c21c5a8be54b",
    "display_name" => "My Access Grant",
    "user_identity_id" => "43947360-cdc8-4db6-8b22-e079416d1d8b",
    "starts_at" => "2025-07-13T15:00:00.000Z",
    "ends_at" => "2025-07-16T11:00:00.000Z",
    "instant_key_url" => "https://ik.seam.co/ABCXYZ",
    ...
  ];
  ```

  ```json C# theme={null}
  // Coming Soon!
  ```
</CodeGroup>


# Feature Overview
Source: https://docs.seam.co/industry-guides/hospitality-industry-guide/feature-overview

Explore the hospitality access modes Seam supports, including Instant Keys, mobile keys, encoded and preconfigured plastic cards, and PIN codes.

Seam enables you to grant access using Instant Keys, mobile keys, plastic cards, and PIN codes. Further, Seam supports encoding credentials onto cards for access systems that use a data-on-card model, as well as access systems that use preconfigured cards. This section describes each of the access modes that you can issue with Seam.

<img
  alt="Seam supports common hospitality access methods like mobile keys
(including Instant Keys), encoded key cards, and PIN codes."
/>

***

## Seam Instant Keys

[Instant Key](/use-cases/granting-access/using-instant-keys) is the fastest way to share access. It's a no-code, fully-hosted mobile key solution. With a single API call, you can create a mobile key and send it through text or email, or in your own app. There's no app to install and no account to create. The user just taps a link and gets a lightweight, native-feeling experience. Instant Keys are instant, intuitive, and secure. For issuing Bluetooth mobile keys, this is the most streamlined mobile access experience available today.

### The Instant Key Access Flow

Your PMS app issues an Instant Key and sends it to a hotel guest—with no app download required. The guest taps the Instant Key link on their mobile device and gets a Bluetooth mobile key through iOS App Clip technology or Instant Apps on Android.

<img alt="For a streamlined mobile access experience, use Instant Keys." />

<Info>
  If you want the ability to customize the access flow completely for your
  users, you can use the Seam mobile SDK to integrate our [mobile key
  solution](#integrate-mobile-keys-into-your-mobile-app).
</Info>

***

## Integrate Mobile Keys into Your Mobile App

Seam enables you to build your own custom mobile key app to grant access to hotel guests. The Seam mobile SDK enables you to integrate once, giving you universal access to all supported access systems.

<img alt="Create your own mobile app to present mobile keys to hotel guests." />

<Info>
  If you do not want your hotels' guests to have to download a mobile app, use
  [Seam Instant Keys](#seam-instant-keys).
</Info>

### Hospitality Use Cases for Mobile Keys

In a hotel environment, mobile keys are often part of automated, self-serve scenarios. In addition to credential issuance, these processes may include handling for pre-assigned room allocation, just-in-time room assignment, and walk-in and manual reservations.

Your PMS app can also offer front desk staff the option of issuing mobile keys to arriving guests.

<div>
  <img
    alt="Use the Seam API and mobile SDK to power your hotel PMS app's mobile key
feature for guests."
  />
</div>

### Seam Mobile SDK

Seam provides a mobile SDK for iOS and Android that enables you to develop your mobile access app. For details, see [Mobile Access](/capability-guides/mobile-access/index) and [Integrating into Your Mobile Application](/capability-guides/mobile-access/mobile-device-sdks/index).

***

## Encode Plastic Cards

With Seam, a hospitality PMS app can convert a reservation into an issued access method and then encode it onto a plastic key card.

A common hotel key card scenario is as follows:

A guest arrives at a hotel front desk. The staff member retrieves the guest's reservation and encodes the corresponding access method onto one or more plastic key cards. The access setup for each guest room should include both the room, itself, and the set of all other necessary access points, such as the nearest elevator, the hotel gym, and so on.

Your PMS app can also handle the same credential issuance and card encoding functions at a self-serve kiosk.

<img
  alt="Use the Seam API to power your hotel PMS app's plastic card encoding
feature for guests."
/>


# Granting Access Using Encoded Plastic Key Cards
Source: https://docs.seam.co/industry-guides/hospitality-industry-guide/granting-access-using-encoded-plastic-key-cards

Issue plastic key cards to hotel guests with Seam by creating a user identity and Access Grant, then encoding the access method onto a card.

To issue a plastic key card, identify the user to whom you want to grant access and create a user identity to represent this user. Then, create an Access Grant to specify the entrances and spaces to which you want to grant the user access. The Access Grant creates a card access method. You use the Seam API to encode the access method onto a plastic key card. You can also use the Seam API to scan encoded cards.

This section details the steps in this process and provides accompanying Seam API code samples. See the following instructions:

1. [Create a User Identity](#create-a-user-identity)
2. [Create an Access Grant](#create-an-access-grant)
3. [Encode the Card](#encode-the-card)
4. [Scan the Card](#scan-the-card)

***

## Create a User Identity

Use the Seam API to create a `user_identity`. A user identity represents the hotel guest.

**Code:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  // Create a user identity for your user.
  const janeUser = await seam.userIdentities.create({
    full_name: 'Jane Doe',
    phone_number: '+15555550100',
  })
  ```

  ```bash cURL theme={null}
  # Create a user identity for your user.
  jane_user=$(curl -X 'POST' \
    'https://connect.getseam.com/user_identities/create' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d '{
    "full_name": "Jane Doe",
    "phone_number": "+15555550100"
  }')
  ```

  ```python Python theme={null}
  # Create a user identity for your user.
  jane_user = seam.user_identities.create(
    full_name = "Jane Doe",
    phone_number = "+15555550100"
  )
  ```

  ```ruby Ruby theme={null}
  # Create a user identity for your user.
  jane_user = seam.user_identities.create(
    full_name: "Jane Doe",
    phone_number: "+15555550100"
  )
  ```

  ```php PHP theme={null}
  // Create a user identity for your user.
  $jane_user = $seam->user_identities->create(
    full_name: "Jane Doe",
    phone_number: "+15555550100"
  );
  ```

  ```csharp C# theme={null}
  // Coming soon!
  ```
</CodeGroup>

**Output:**

<CodeGroup>
  ```json JavaScript theme={null}
  {
    "user_identity_id": "43947360-cdc8-4db6-8b22-e079416d1d8b",
    "full_name": "Jane Doe",
    "phone_number": "+15555550100",
    ...
  }
  ```

  ```json cURL theme={null}
  {
    "user_identity": {
      "user_identity_id": "43947360-cdc8-4db6-8b22-e079416d1d8b",
      "full_name": "Jane Doe",
      "phone_number": "+15555550100",
      ...
    },
    "ok": true
  }
  ```

  ```json Python theme={null}
  UserIdentity(
    user_identity_id='43947360-cdc8-4db6-8b22-e079416d1d8b',
    full_name='Jane Doe',
    phone_number='+15555550100',
    ...
  )
  ```

  ```json Ruby theme={null}
  <Seam::Resources::UserIdentity:0x005f0
    user_identity_id="43947360-cdc8-4db6-8b22-e079416d1d8b"
    full_name="Jane Doe"
    phone_number="+15555550100"
    ...
  >
  ```

  ```json PHP theme={null}
  {
    "user_identity_id": "43947360-cdc8-4db6-8b22-e079416d1d8b",
    "full_name": "Jane Doe",
    "phone_number": "+15555550100",
    ...
  }
  ```

  ```json C# theme={null}
  // Coming soon!
  ```
</CodeGroup>

***

## Create an Access Grant

To create an Access Grant, specify the user identity, entrance or space IDs, and starting and ending times. Include `card` as a requested access method.

**Code:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  await seam.accessGrants.create({
    // You can specify the ID of an existing user identity or
    // use the user_identity parameter to create a new one.
    user_identity_id: janeUser.user_identity_id,
    // You can specify acs_entrance_ids, space_ids, or both.
    acs_entrance_ids: [
      '48ebfb50-c531-43c5-b9ea-409f26dabbd7',
      'f74e4879-5991-4e2f-a368-888983dcfbfc',
    ],
    requested_access_methods: [{ mode: 'card' }],
    starts_at: '2025-07-13T15:00:00.000Z',
    ends_at: '2025-07-16T11:00:00.000Z',
  })
  ```

  ```bash cURL theme={null}
  # You can specify the ID of an existing user identity or
  # use the user_identity parameter to create a new one.
  # Also, you can specify acs_entrance_ids, space_ids, or both.
  curl -X 'POST' \
    'https://connect.getseam.com/access_grants/create' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d "{
      \"user_identity_id\": \"$(jq -r '.user_identity.user_identity_id' <<< ${jane_user})\",
      \"acs_entrance_ids\": [
        \"48ebfb50-c531-43c5-b9ea-409f26dabbd7\",
        \"f74e4879-5991-4e2f-a368-888983dcfbfc\"
      ],
      \"requested_access_methods\": [
        {\"mode\": \"card\"}
      ],
      \"starts_at\": \"2025-07-13T15:00:00.000Z\",
      \"ends_at\": \"2025-07-16T11:00:00.000Z\"
  }"
  ```

  ```python Python theme={null}
  seam.access_grants.create(
    # You can specify the ID of an existing user identity or
    # use the user_identity parameter to create a new one.
    user_identity_id=jane_user.user_identity_id,
    # You can specify acs_entrance_ids, space_ids, or both.
    acs_entrance_ids=[
      "48ebfb50-c531-43c5-b9ea-409f26dabbd7",
      "f74e4879-5991-4e2f-a368-888983dcfbfc"
    ],
    requested_access_methods=[
      {"mode": "card"}
    ],
    starts_at="2025-07-13T15:00:00.000Z",
    ends_at="2025-07-16T11:00:00.000Z"
  )
  ```

  ```ruby Ruby theme={null}
  seam.access_grants.create(
    # You can specify the ID of an existing user identity or
    # use the user_identity parameter to create a new one.
    user_identity_id: jane_user.user_identity_id,
    # You can specify acs_entrance_ids, space_ids, or both.
    acs_entrance_ids: %w[48ebfb50-c531-43c5-b9ea-409f26dabbd7 f74e4879-5991-4e2f-a368-888983dcfbfc],
    requested_access_methods: [
      {"mode": "card"}
    ],
    starts_at: "2025-07-13T15:00:00.000Z",
    ends_at: "2025-07-16T11:00:00.000Z"
  )
  ```

  ```php PHP theme={null}
  $seam->access_grants->create(
    // You can specify the ID of an existing user identity or
    // use the user_identity parameter to create a new one.
    user_identity_id: $jane_user->user_identity_id,
    // You can specify acs_entrance_ids, space_ids, or both.
    acs_entrance_ids: [
      "48ebfb50-c531-43c5-b9ea-409f26dabbd7",
      "f74e4879-5991-4e2f-a368-888983dcfbfc",
    ],
    requested_access_methods: [
      ["mode" => "card"],
    ],
    starts_at: "2025-07-13T15:00:00.000Z",
    ends_at: "2025-07-16T11:00:00.000Z"
  );
  ```

  ```csharp C# theme={null}
  // Coming Soon!
  ```
</CodeGroup>

**Output:**

<CodeGroup>
  ```json JavaScript theme={null}
  {
    "access_grant_id": "ef83cca9-5fdf-4ac2-93f3-c21c5a8be54b",
    "display_name": "My Access Grant",
    "user_identity_id": "43947360-cdc8-4db6-8b22-e079416d1d8b",
    "starts_at": "2025-07-13T15:00:00.000Z",
    "ends_at": "2025-07-16T11:00:00.000Z",
    "requested_access_methods": [
      {
        "display_name": "Plastic Card",
        "mode": "card",
        "created_access_method_ids": ["c7d8e9f0-1a2b-3c4d-5e6f-7a8b9c0d1e2f"],
        ...
      }
    ],
    ...
  }
  ```

  ```json cURL theme={null}
  {
    "access_grant": {
      "access_grant_id": "ef83cca9-5fdf-4ac2-93f3-c21c5a8be54b",
      "display_name": "My Access Grant",
      "user_identity_id": "43947360-cdc8-4db6-8b22-e079416d1d8b",
      "starts_at": "2025-07-13T15:00:00.000Z",
      "ends_at": "2025-07-16T11:00:00.000Z",
      "requested_access_methods": [
        {
          "display_name": "Plastic Card",
          "mode": "card",
          "created_access_method_ids": ["c7d8e9f0-1a2b-3c4d-5e6f-7a8b9c0d1e2f"],
          ...
        }
      ],
      ...
    }
  }
  ```

  ```python Python theme={null}
  AccessGrant(
    access_grant_id="ef83cca9-5fdf-4ac2-93f3-c21c5a8be54b",
    display_name="My Access Grant",
    user_identity_id="43947360-cdc8-4db6-8b22-e079416d1d8b",
    starts_at="2025-07-13T15:00:00.000Z",
    ends_at="2025-07-16T11:00:00.000Z",
    requested_access_methods=[
      {
        "display_name": "Plastic Card",
        "mode": "card",
        "created_access_method_ids": ["c7d8e9f0-1a2b-3c4d-5e6f-7a8b9c0d1e2f"],
        ...
      }
    ],
    ...
  )
  ```

  ```ruby Ruby theme={null}
  {
    "access_grant_id" => "ef83cca9-5fdf-4ac2-93f3-c21c5a8be54b",
    "display_name" => "My Access Grant",
    "user_identity_id" => "43947360-cdc8-4db6-8b22-e079416d1d8b",
    "starts_at" => "2025-07-13T15:00:00.000Z",
    "ends_at" => "2025-07-16T11:00:00.000Z",
    "requested_access_methods" => [
      {
        "display_name": "Plastic Card",
        "mode": "card",
        "created_access_method_ids": ["c7d8e9f0-1a2b-3c4d-5e6f-7a8b9c0d1e2f"],
        ...
      }
    ],
    ...
  }
  ```

  ```php PHP theme={null}
  [
    "access_grant_id" => "ef83cca9-5fdf-4ac2-93f3-c21c5a8be54b",
    "display_name" => "My Access Grant",
    "user_identity_id" => "43947360-cdc8-4db6-8b22-e079416d1d8b",
    "starts_at" => "2025-07-13T15:00:00.000Z",
    "ends_at" => "2025-07-16T11:00:00.000Z",
    "requested_access_methods" => [
      {
        "display_name": "Plastic Card",
        "mode": "card",
        "created_access_method_ids": ["c7d8e9f0-1a2b-3c4d-5e6f-7a8b9c0d1e2f"],
        ...
      }
    ],
    ...
  ];
  ```

  ```json C# theme={null}
  // Coming Soon!
  ```
</CodeGroup>

## Encode the Card

As a final step in creating a plastic key card, use the Seam API to encode the access method onto the plastic card. Your app can serve hotel front desk staff as well as self-serve check-in kiosks with built-in physical encoders.

<img alt="Encode the access method onto a plastic key card." />

First, list the available card encoders within the access system and identify the encoder that the person encoding the card should use. Then, initiate the encoding action. The Seam API returns an [action attempt](../../core-concepts/action-attempts) so that your app can track the status of the encoding. When the encoding completes successfully, the action attempt payload includes information about the encoded card, such as the card number and the date and time at which the card was issued (that is, encoded). If the encoding fails, the action attempt reports any encoding errors.

For more details about card encoding, see [Creating and Encoding Card Access Methods](../../low-level-apis/access-systems/working-with-card-encoders-and-scanners/creating-and-encoding-card-access-methods).

**Code:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  // First, get the encoder that you want to use.
  const encoder = (
    await seam.acs.encoders.list({
      acs_system_ids: [hotel_a.acs_system_id],
    })
  )[0]

  // Then, encode the card.
  const encodingActionAttempt = await seam.accessMethods.encode({
    access_method_id: 'c7d8e9f0-1a2b-3c4d-5e6f-7a8b9c0d1e2f',
    acs_encoder_id: encoder.acs_encoder_id,
  })

  // To confirm that the encoding succeeded,
  // poll the returned action attempt
  // until its status is success.
  await seam.actionAttempts.get({
    action_attempt_id: encodingActionAttempt.action_attempt_id,
  })
  ```

  ```bash cURL theme={null}
  # First, get the encoder that you want to use.
  encoder=$(curl -X 'POST' \
    'https://connect.getseam.com/acs/encoders/list' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d "{
    \"acs_system_id\": \"$(jq -r '.acs_system.acs_system_id' <<< ${hotel_a})\"
  }" | jq -r '.acs_encoders[0]')

  # Then, encode the card.
  encoding_action_attempt=$(curl -X 'POST' \
    'https://connect.getseam.com/access_methods/encode' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d "{
    \"access_method_id\": \"c7d8e9f0-1a2b-3c4d-5e6f-7a8b9c0d1e2f\",
    \"acs_encoder_id\": \"$(jq -r '.acs_encoder_id' <<< ${encoder})\"
  }")

  # To confirm that the encoding succeeded,
  # poll the returned action attempt
  # until its status is success.
  curl -X 'POST' \
    'https://connect.getseam.com/action_attempts/get' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d "{
    \"action_attempt_id\": \"$(jq -r '.action_attempt.action_attempt_id' <<< ${encoding_action_attempt})\"
  }"
  ```

  ```python Python theme={null}
  # First, get the encoder that you want to use.
  encoder = seam.acs.encoders.list(
    acs_system_ids = [hotel_a.acs_system_id]
  )[0]

  # Then, encode the card.
  encoding_action_attempt = seam.access_methods.encode(
    access_method_id = "c7d8e9f0-1a2b-3c4d-5e6f-7a8b9c0d1e2f",
    acs_encoder_id = encoder.acs_encoder_id
  )

  # To confirm that the encoding succeeded,
  # poll the returned action attempt
  # until its status is success.
  seam.action_attempts.get(
    action_attempt_id = encoding_action_attempt.action_attempt_id
  )
  ```

  ```ruby Ruby theme={null}
  # First, get the encoder that you want to use.
  encoder = (seam.acs.encoders.list(
    acs_system_ids: [hotel_a.acs_system_id]
  ))[0]

  # Then, encode the card.
  encoding_action_attempt = seam.access_methods.encode(
    access_method_id: "c7d8e9f0-1a2b-3c4d-5e6f-7a8b9c0d1e2f",
    acs_encoder_id: encoder.acs_encoder_id
  )

  # To confirm that the encoding succeeded,
  # poll the returned action attempt
  # until its status is success.
  seam.action_attempts.get(
    action_attempt_id: encoding_action_attempt.action_attempt_id
  )
  ```

  ```php PHP theme={null}
  // First, get the encoder that you want to use.
  $encoder = $seam->acs->encoders->list(
    acs_system_ids: [$hotel_a->acs_system_id]
  )[0];

  // Then, encode the card.
  $encoding_action_attempt = $seam->access_methods->encode(
    access_method_id: "c7d8e9f0-1a2b-3c4d-5e6f-7a8b9c0d1e2f",
    acs_encoder_id: $encoder->acs_encoder_id
  );

  // To confirm that the encoding succeeded,
  // poll the returned action attempt
  // until its status is success.
  $seam->action_attempts->get(
    action_attempt_id: $encoding_action_attempt->action_attempt_id
  );
  ```

  ```csharp C# theme={null}
  // Coming soon!
  ```
</CodeGroup>

**Output:**

<CodeGroup>
  ```json JavaScript theme={null}
  {
    status: 'success',
    action_attempt_id: 'e49a33f7-9596-4b45-8e66-550b72fea134',
    action_type: 'ENCODE_ACCESS_METHOD',
    result: {
      acs_credential_id: 'c7d8e9f0-1a2b-3c4d-5e6f-7a8b9c0d1e2f',
      card_number: '1234abc',
      is_issued: true,
      issued_at: '2025-07-13T14:00:00.000Z',
      ...
    },
    error: null
  }
  ```

  ```json cURL theme={null}
  {
    "action_attempt":
      {
        "status": "success",
        "action_attempt_id": "e49a33f7-9596-4b45-8e66-550b72fea134",
        "action_type": "ENCODE_ACCESS_METHOD",
        "result": {
          "access_method_id": "c7d8e9f0-1a2b-3c4d-5e6f-7a8b9c0d1e2f",
          "card_number": "1234abc",
          "is_issued": true,
          "issued_at": "2025-07-13T14:00:00.000Z",
          ...
        },
        "error": null
      },
    "ok": true
  }
  ```

  ```json Python theme={null}
  ActionAttempt(
    status='success',
    action_attempt_id='e49a33f7-9596-4b45-8e66-550b72fea134',
    action_type='ENCODE_ACCESS_METHOD',
    result={
      access_method_id='c7d8e9f0-1a2b-3c4d-5e6f-7a8b9c0d1e2f',
      card_number='1234abc',
      is_issued=True,
      issued_at='2025-07-13T14:00:00.000Z',
      ...
    },
    error=null
  )
  ```

  ```json Ruby theme={null}
  <Seam::Resources::ActionAttempt:0x00410
    status="success"
    action_attempt_id="e49a33f7-9596-4b45-8e66-550b72fea134"
    action_type="ENCODE_ACCESS_METHOD"
    result={
      acs_credential_id="c7d8e9f0-1a2b-3c4d-5e6f-7a8b9c0d1e2f"
      card_number="1234abc"
      is_issued=true,
      issued_at="2025-07-13T14:00:00.000Z"
      ...
    }
    error=nil
  >
  ```

  ```json PHP theme={null}
  {
    "status": "success",
    "action_attempt_id": "e49a33f7-9596-4b45-8e66-550b72fea134",
    "action_type": "ENCODE_ACCESS_METHOD",
    "result": {
      "acs_credential_id": "c7d8e9f0-1a2b-3c4d-5e6f-7a8b9c0d1e2f",
      "card_number": "1234abc",
      "is_issued": true,
      "issued_at": "2025-07-13T14:00:00.000Z",
      ...
    },
    "error": null
  }
  ```

  ```json C# theme={null}
  // Coming soon!
  ```
</CodeGroup>

***

## Scan the Card

You can scan the card to view its data and confirm that it's up to date with the server. The scan result includes the card's properties, such as its card number, serial number, and other useful details. If discrepancies are detected, Seam provides warnings to indicate that the card is out of date and needs re-encoding.

<img alt="Use the Seam API to scan a plastic card to view its details." />

To scan a card, first initiate the scanning process. This scanning action returns an action attempt that you can poll to track the status. When the scan completes, view the card payload within the action attempt. Note any `action_attempt.result.warnings`. Warning messages show which properties are out of sync.&#x20;

Pay special attention to the following parts of the returned payload:

* `action_attempt.result.warnings` list any properties that Seam has detected are out-of-sync between the card and the encoder.
* `action_attempt.result.acs_credential_on_seam` lists the properties of the access method as stored on the access system server.
* `action_attempt.result.acs_credential_on_encoder` lists the properties of the access method as stored on the card.

For more details, see [Scanning Encoded Cards](../../low-level-apis/access-systems/working-with-card-encoders-and-scanners/scanning-encoded-cards).

**Code:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  // Retrieve a list of all available encoders in a hotel,
  // that is, connected to a single acs_system.
  await seam.acs.encoders.list({
    acs_system_ids: [hotelASystemId],
  })

  // Scan the card using the desired encoder.
  const scanningActionAttempt = await seam.acs.encoders.scanCredential({
    acs_encoder_id: encoder.acs_encoder_id,
  })
  ```

  ```bash cURL theme={null}
  # Retrieve a list of all available encoders in a hotel,
  # that is, connected to a single acs_system.
  curl -X 'POST' \
    'https://connect.getseam.com/acs/encoders/list' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d "{
    \"acs_system_ids\": [\"${hotel_a_system_id}\"]
  }"

  # Scan the card using the desired encoder.
  scanning_action_attempt=$(curl -X 'POST' \
    'https://connect.getseam.com/acs/encoders/scan_credential' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d "{
    \"acs_encoder_id\": \"${acs_encoder_id}\"
  }")
  ```

  ```python Python theme={null}
  # Retrieve a list of all available encoders in a hotel,
  # that is, connected to a single acs_system.
  seam.acs.encoders.list(
    acs_system_ids = [hotel_a_system_id]
  )

  # Scan the card using the desired encoder.
  scanning_action_attempt = seam.acs.encoders.scan_credential(
    acs_encoder_id = encoder.acs_encoder_id
  )
  ```

  ```ruby Ruby theme={null}
  # Retrieve a list of all available encoders in a hotel,
  # that is, connected to a single acs_system.
  seam.acs.encoders.list(
    acs_system_ids: [hotel_a_system_id]
  )

  # Scan the card using the desired encoder.
  scanning_action_attempt = seam.acs.encoders.scan_credential(
    acs_encoder_id: encoder.acs_encoder_id
  )
  ```

  ```php PHP theme={null}
  // Retrieve a list of all available encoders in a hotel,
  // that is, connected to a single acs_system.
  $seam->acs->encoders->list(
    acs_system_ids: [$hotel_a_system_id]
  );

  // Scan the card using the desired encoder.
  $scanning_action_attempt = $seam->acs->encoders->scan_credential(
    acs_encoder_id: $encoder->acs_encoder_id
  );
  ```

  ```csharp C# theme={null}
  // Coming soon!
  ```
</CodeGroup>

**Output:**

<CodeGroup>
  ```json JavaScript theme={null}
  {
    status: 'success',
    action_attempt_id: '0243f349-68bf-4323-9e61-4c40eb72eb1e",
    action_type: 'SCAN_CREDENTIAL',
    result: {
      'warnings': [
        {
          'warning_code': 'acs_credential_on_encoder_out_of_sync',
          'warning_message': 'The following properties are out of sync
                              between acs_credential_on_encoder and
                              acs_credential_on_seam: ends_at'
        }
      ],
      'acs_credential_on_seam': {
        'starts_at': '2025-07-13T15:00:00.000Z',
        'ends_at': '2025-07-16T11:00:00.000Z',
        'card_number': '1234abc',
        'display_name': 'Card 1234abc',
        'access_method': 'card',
        ...
      },
      'acs_credential_on_encoder': {
        'starts_at': '2025-07-13T15:00:00.000Z',
        'ends_at': '2025-07-15T11:00:00.000Z',
        'card_number': '1234abc',
        ...
      }
    },
    error: null
  }
  ```

  ```json cURL theme={null}
  {
    "action_attempt":
      {
        "status": "success",
        "action_attempt_id": "0243f349-68bf-4323-9e61-4c40eb72eb1e",
        "action_type": "SCAN_CREDENTIAL",
        "result": {
          "warnings": [
            {
              "warning_code": "acs_credential_on_encoder_out_of_sync",
              "warning_message": "The following properties are out of sync
                                  between acs_credential_on_encoder and
                                  acs_credential_on_seam: ends_at"
            }
          ],
          "acs_credential_on_seam": {
            "starts_at": "2025-07-13T15:00:00.000Z",
            "ends_at": "2025-07-16T11:00:00.000Z",
            "card_number": "1234abc",
            "display_name": "Card 1234abc",
            "access_method": "card",
            ...
          },
          "acs_credential_on_encoder": {
            "starts_at": "2025-07-13T15:00:00.000Z",
            "ends_at": "2025-07-15T11:00:00.000Z",
            "card_number": "1234abc",
            ...
          }
        },
        "error": null
      },
    "ok": true
  }
  ```

  ```json Python theme={null}
  ActionAttempt(
    status='success',
    action_attempt_id='0243f349-68bf-4323-9e61-4c40eb72eb1e',
    action_type='SCAN_CREDENTIAL',
    result={
      warnings=[
        {
          "warning_code": "acs_credential_on_encoder_out_of_sync",
          "warning_message": "The following properties are out of sync
                              between acs_credential_on_encoder and
                              acs_credential_on_seam: ends_at"
        }
      ],
      acs_credential_on_seam={
        "starts_at": "2025-07-13T15:00:00.000Z",
        "ends_at": "2025-07-16T11:00:00.000Z",
        "card_number": "1234abc",
        "display_name": "Card 1234abc",
        "access_method": "card",
        ...
      },
      acs_credential_on_encoder={
        "starts_at": "2025-07-13T15:00:00.000Z",
        "ends_at": "2025-07-15T11:00:00.000Z",
        "card_number": "1234abc",
        ...
      }
    },
    error=null
  )
  ```

  ```json Ruby theme={null}
  <Seam::Resources::ActionAttempt:0x00410
    status="success"
    action_attempt_id="0243f349-68bf-4323-9e61-4c40eb72eb1e"
    action_type="SCAN_CREDENTIAL"
    result={
      "warnings": [
        {
          "warning_code": "acs_credential_on_encoder_out_of_sync",
          "warning_message": "The following properties are out of sync
                              between acs_credential_on_encoder and
                              acs_credential_on_seam: ends_at"
        }
      ],
      "acs_credential_on_seam": {
        "starts_at": "2025-07-13T15:00:00.000Z",
        "ends_at": "2025-07-16T11:00:00.000Z",
        "card_number": "1234abc",
        "display_name": "Card 1234abc",
        "access_method": "card",
        ...
      },
      "acs_credential_on_encoder": {
        "starts_at": "2025-07-13T15:00:00.000Z",
        "ends_at": "2025-07-15T11:00:00.000Z",
        "card_number": "1234abc",
        ...
      }
    }
    error=nil
  >
  ```

  ```json PHP theme={null}
  {
    "status": "success",
    "action_attempt_id": "0243f349-68bf-4323-9e61-4c40eb72eb1e",
    "action_type": "SCAN_CREDENTIAL",
    "result": {
      "warnings": [
        {
          "warning_code": "acs_credential_on_encoder_out_of_sync",
          "warning_message": "The following properties are out of sync
                              between acs_credential_on_encoder and
                              acs_credential_on_seam: ends_at"
        }
      ],
      "acs_credential_on_seam": {
        "starts_at": "2025-07-13T15:00:00.000Z",
        "ends_at": "2025-07-16T11:00:00.000Z",
        "card_number": "1234abc",
        "display_name": "Card 1234abc",
        "access_method": "card",
        ...
      },
      "acs_credential_on_encoder": {
        "starts_at": "2025-07-13T15:00:00.000Z",
        "ends_at": "2025-07-15T11:00:00.000Z",
        "card_number": "1234abc",
        ...
      }
    },
    "error": null
  }
  ```

  ```json C# theme={null}
  // Coming soon!
  ```
</CodeGroup>


# Granting Access Using Mobile Keys
Source: https://docs.seam.co/industry-guides/hospitality-industry-guide/granting-access-using-mobile-keys

Issue mobile keys to hotel guests with Seam by creating a user identity and Access Grant, then delivering the keys through your own mobile app.

To issue mobile keys, first identify the user to whom you want to grant access and create a user identity to represent this user. Then, create an Access Grant to specify the entrances and spaces to which you want to grant the user access. Through this Access Grant, Seam generates all the necessary mobile keys. You can then deliver the mobile keys to your user in a mobile app that you develop. Your user installs this app on their phone.

<Info>
  Seam also provides [Instant
  Keys](/industry-guides/hospitality-industry-guide/granting-access-using-seam-instant-keys)
  as an app-free alternative to mobile keys. When you create a mobile key, Seam
  automatically also creates an Instant Key.
</Info>

This section details the steps in this process and provides accompanying Seam API code samples. See the following instructions:

1. [Create a User Identity](#create-a-user-identity)
2. [Create an Access Grant](#create-an-access-grant)
3. [Deliver the Mobile Key](#deliver-the-mobile-key)

***

## Create a User Identity

On the server side, use the Seam API to create a `user_identity`. A user identity represents the hotel guest, that is, your mobile app user.

**Code:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  // Create a user identity for your mobile app user.
  const janeUser = await seam.userIdentities.create({
    full_name: 'Jane Doe',
    phone_number: '+15555550100',
  })
  ```

  ```bash cURL theme={null}
  # Create a user identity for your mobile app user.
  jane_user=$(curl -X 'POST' \
    'https://connect.getseam.com/user_identities/create' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d '{
    "full_name": "Jane Doe",
    "phone_number": "+15555550100"
  }')
  ```

  ```python Python theme={null}
  # Create a user identity for your mobile app user.
  jane_user = seam.user_identities.create(
    full_name = "Jane Doe",
    phone_number = "+15555550100"
  )
  ```

  ```ruby Ruby theme={null}
  # Create a user identity for your mobile app user.
  jane_user = seam.user_identities.create(
    full_name: "Jane Doe",
    phone_number: "+15555550100"
  )
  ```

  ```php PHP theme={null}
  // Create a user identity for your mobile app user.
  $jane_user = $seam->user_identities->create(
    full_name: "Jane Doe",
    phone_number: "+15555550100"
  );
  ```

  ```csharp C# theme={null}
  // Coming soon!
  ```
</CodeGroup>

**Output:**

<CodeGroup>
  ```json JavaScript theme={null}
  {
    "user_identity_id": "43947360-cdc8-4db6-8b22-e079416d1d8b",
    "full_name": "Jane Doe",
    "phone_number": "+15555550100",
    ...
  }
  ```

  ```json cURL theme={null}
  {
    "user_identity": {
      "user_identity_id": "43947360-cdc8-4db6-8b22-e079416d1d8b",
      "full_name": "Jane Doe",
      "phone_number": "+15555550100",
      ...
    },
    "ok": true
  }
  ```

  ```json Python theme={null}
  UserIdentity(
    user_identity_id='43947360-cdc8-4db6-8b22-e079416d1d8b',
    full_name='Jane Doe',
    phone_number='+15555550100',
    ...
  )
  ```

  ```json Ruby theme={null}
  <Seam::Resources::UserIdentity:0x005f0
    user_identity_id="43947360-cdc8-4db6-8b22-e079416d1d8b"
    full_name="Jane Doe"
    phone_number="+15555550100"
    ...
  >
  ```

  ```json PHP theme={null}
  {
    "user_identity_id": "43947360-cdc8-4db6-8b22-e079416d1d8b",
    "full_name": "Jane Doe",
    "phone_number": "+15555550100",
    ...
  }
  ```

  ```json C# theme={null}
  // Coming soon!
  ```
</CodeGroup>

***

## Create an Access Grant

To create an Access Grant, specify the user identity, entrance or space IDs, and starting and ending times. Include `mobile_key` as a requested access method.

**Code:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  await seam.accessGrants.create({
    // You can specify the ID of an existing user identity or
    // use the user_identity parameter to create a new one.
    user_identity_id: janeUser.user_identity_id,
    // You can specify acs_entrance_ids, space_ids, or both.
    acs_entrance_ids: [
      '48ebfb50-c531-43c5-b9ea-409f26dabbd7',
      'f74e4879-5991-4e2f-a368-888983dcfbfc',
    ],
    requested_access_methods: [{ mode: 'mobile_key' }],
    starts_at: '2025-07-13T15:00:00.000Z',
    ends_at: '2025-07-16T11:00:00.000Z',
  })
  ```

  ```bash cURL theme={null}
  # You can specify the ID of an existing user identity or
  # use the user_identity parameter to create a new one.
  # Also, you can specify acs_entrance_ids, space_ids, or both.
  curl -X 'POST' \
    'https://connect.getseam.com/access_grants/create' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d "{
      \"user_identity_id\": \"$(jq -r '.user_identity.user_identity_id' <<< ${jane_user})\",
      \"acs_entrance_ids\": [
        \"48ebfb50-c531-43c5-b9ea-409f26dabbd7\",
        \"f74e4879-5991-4e2f-a368-888983dcfbfc\"
      ],
      \"requested_access_methods\": [
        {\"mode\": \"mobile_key\"}
      ],
      \"starts_at\": \"2025-07-13T15:00:00.000Z\",
      \"ends_at\": \"2025-07-16T11:00:00.000Z\"
  }"
  ```

  ```python Python theme={null}
  seam.access_grants.create(
    # You can specify the ID of an existing user identity or
    # use the user_identity parameter to create a new one.
    user_identity_id=jane_user.user_identity_id,
    # You can specify acs_entrance_ids, space_ids, or both.
    acs_entrance_ids=[
      "48ebfb50-c531-43c5-b9ea-409f26dabbd7",
      "f74e4879-5991-4e2f-a368-888983dcfbfc"
    ],
    requested_access_methods=[
      {"mode": "mobile_key"}
    ],
    starts_at="2025-07-13T15:00:00.000Z",
    ends_at="2025-07-16T11:00:00.000Z"
  )
  ```

  ```ruby Ruby theme={null}
  seam.access_grants.create(
    # You can specify the ID of an existing user identity or
    # use the user_identity parameter to create a new one.
    user_identity_id: jane_user.user_identity_id,
    # You can specify acs_entrance_ids, space_ids, or both.
    acs_entrance_ids: %w[48ebfb50-c531-43c5-b9ea-409f26dabbd7 f74e4879-5991-4e2f-a368-888983dcfbfc],
    requested_access_methods: [
      {"mode": "mobile_key"}
    ],
    starts_at: "2025-07-13T15:00:00.000Z",
    ends_at: "2025-07-16T11:00:00.000Z"
  )
  ```

  ```php PHP theme={null}
  $seam->access_grants->create(
    // You can specify the ID of an existing user identity or
    // use the user_identity parameter to create a new one.
    user_identity_id: $jane_user->user_identity_id,
    // You can specify acs_entrance_ids, space_ids, or both.
    acs_entrance_ids: [
      "48ebfb50-c531-43c5-b9ea-409f26dabbd7",
      "f74e4879-5991-4e2f-a368-888983dcfbfc",
    ],
    requested_access_methods: [
      ["mode" => "mobile_key"],
    ],
    starts_at: "2025-07-13T15:00:00.000Z",
    ends_at: "2025-07-16T11:00:00.000Z"
  );
  ```

  ```csharp C# theme={null}
  // Coming Soon!
  ```
</CodeGroup>

**Output:**

<CodeGroup>
  ```json JavaScript theme={null}
  {
    "access_grant_id": "ef83cca9-5fdf-4ac2-93f3-c21c5a8be54b",
    "display_name": "My Access Grant",
    "user_identity_id": "43947360-cdc8-4db6-8b22-e079416d1d8b",
    "starts_at": "2025-07-13T15:00:00.000Z",
    "ends_at": "2025-07-16T11:00:00.000Z",
    "requested_access_methods": [
      {
        "display_name": "Mobile Key",
        "mode": "mobile_key",
        "created_access_method_ids": ["6ba7b810-9dad-11d1-80b4-00c04fd430c8"],
        ...
      }
    ],
    "instant_key_url": "https://ik.seam.co/ABCXYZ",
    ...
  }
  ```

  ```json cURL theme={null}
  {
    "access_grant": {
      "access_grant_id": "ef83cca9-5fdf-4ac2-93f3-c21c5a8be54b",
      "display_name": "My Access Grant",
      "user_identity_id": "43947360-cdc8-4db6-8b22-e079416d1d8b",
      "starts_at": "2025-07-13T15:00:00.000Z",
      "ends_at": "2025-07-16T11:00:00.000Z",
      "requested_access_methods": [
        {
          "display_name": "Mobile Key",
          "mode": "mobile_key",
          "created_access_method_ids": ["6ba7b810-9dad-11d1-80b4-00c04fd430c8"],
          ...
        }
      ],
      "instant_key_url": "https://ik.seam.co/ABCXYZ",
      ...
    }
  }
  ```

  ```python Python theme={null}
  AccessGrant(
    access_grant_id="ef83cca9-5fdf-4ac2-93f3-c21c5a8be54b",
    display_name="My Access Grant",
    user_identity_id="43947360-cdc8-4db6-8b22-e079416d1d8b",
    starts_at="2025-07-13T15:00:00.000Z",
    ends_at="2025-07-16T11:00:00.000Z",
    requested_access_methods=[
      {
        "display_name": "Mobile Key",
        "mode": "mobile_key",
        "created_access_method_ids": ["6ba7b810-9dad-11d1-80b4-00c04fd430c8"],
        ...
      }
    ],
    instant_key_url="https://ik.seam.co/ABCXYZ",
    ...
  )
  ```

  ```ruby Ruby theme={null}
  {
    "access_grant_id" => "ef83cca9-5fdf-4ac2-93f3-c21c5a8be54b",
    "display_name" => "My Access Grant",
    "user_identity_id" => "43947360-cdc8-4db6-8b22-e079416d1d8b",
    "starts_at" => "2025-07-13T15:00:00.000Z",
    "ends_at" => "2025-07-16T11:00:00.000Z",
    "requested_access_methods" => [
      {
        "display_name": "Mobile Key",
        "mode": "mobile_key",
        "created_access_method_ids": ["6ba7b810-9dad-11d1-80b4-00c04fd430c8"],
        ...
      }
    ],
    "instant_key_url" => "https://ik.seam.co/ABCXYZ",
    ...
  }
  ```

  ```php PHP theme={null}
  [
    "access_grant_id" => "ef83cca9-5fdf-4ac2-93f3-c21c5a8be54b",
    "display_name" => "My Access Grant",
    "user_identity_id" => "43947360-cdc8-4db6-8b22-e079416d1d8b",
    "starts_at" => "2025-07-13T15:00:00.000Z",
    "ends_at" => "2025-07-16T11:00:00.000Z",
    "requested_access_methods" => [
      {
        "display_name": "Mobile Key",
        "mode": "mobile_key",
        "created_access_method_ids": ["6ba7b810-9dad-11d1-80b4-00c04fd430c8"],
        ...
      }
    ],
    "instant_key_url" => "https://ik.seam.co/ABCXYZ",
    ...
  ];
  ```

  ```json C# theme={null}
  // Coming Soon!
  ```
</CodeGroup>

***

## Deliver the Mobile Key

Seam provides a mobile SDK for iOS and Android that you can use to develop a mobile key app. Your user installs your mobile app and logs in. To use mobile keys, your user must enable certain phone functions—such as Bluetooth—and give your app permission to use these functions. Then, your mobile app downloads the user's mobile key credentials and presents them to your user.

The Seam mobile SDK uses a scanning model called "unlock with tap" to unlock the nearest granted entrance. Your app starts this scanning process, your user holds their mobile device up to the hotel room door or other access point, and it unlocks.

<img
  alt="Develop a mobile app to deliver the mobile key to your user and to unlock
the door."
/>

<Info>
  Alternately, for a more streamlined experience that does not require an app
  download, use [Seam Instant Keys](/industry-guides/hospitality-industry-guide/granting-access-using-seam-instant-keys).
</Info>


# Granting Access Using Seam Instant Keys
Source: https://docs.seam.co/industry-guides/hospitality-industry-guide/granting-access-using-seam-instant-keys

Issue Seam Instant Keys to hotel guests by creating a user identity and Access Grant, then sending the key URL by text or email with no app needed.

To issue an Instant Key, identify the user to whom you want to grant access and create a user identity to represent this user. Then, create an Access Grant to specify the entrances and spaces to which you want to grant the user access. The Access Grant returns the Instant Key URL that you can deliver to your user through text or email.

<img
  alt="Send hotel guests Seam Instant Keys in a text message or email—No app
download required!"
/>

This section details the steps in this process and provides accompanying Seam API code samples. See the following instructions:

1. [Create a User Identity](#create-a-user-identity)
2. [Create an Access Grant](#create-an-access-grant)
3. [Deliver the Instant Key](#deliver-the-instant-key)

***

## Create a User Identity

Use the Seam API to create a `user_identity`. A user identity represents the hotel guest.

**Code:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  // Create a user identity for your user.
  const janeUser = await seam.userIdentities.create({
    full_name: 'Jane Doe',
    phone_number: '+15555550100',
  })
  ```

  ```bash cURL theme={null}
  # Create a user identity for your user.
  jane_user=$(curl -X 'POST' \
    'https://connect.getseam.com/user_identities/create' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d '{
    "full_name": "Jane Doe",
    "phone_number": "+15555550100"
  }')
  ```

  ```python Python theme={null}
  # Create a user identity for your user.
  jane_user = seam.user_identities.create(
    full_name = "Jane Doe",
    phone_number = "+15555550100"
  )
  ```

  ```ruby Ruby theme={null}
  # Create a user identity for your user.
  jane_user = seam.user_identities.create(
    full_name: "Jane Doe",
    phone_number: "+15555550100"
  )
  ```

  ```php PHP theme={null}
  // Create a user identity for your user.
  $jane_user = $seam->user_identities->create(
    full_name: "Jane Doe",
    phone_number: "+15555550100"
  );
  ```

  ```csharp C# theme={null}
  // Coming soon!
  ```
</CodeGroup>

**Output:**

<CodeGroup>
  ```json JavaScript theme={null}
  {
    "user_identity_id": "43947360-cdc8-4db6-8b22-e079416d1d8b",
    "full_name": "Jane Doe",
    "phone_number": "+15555550100",
    ...
  }
  ```

  ```json cURL theme={null}
  {
    "user_identity": {
      "user_identity_id": "43947360-cdc8-4db6-8b22-e079416d1d8b",
      "full_name": "Jane Doe",
      "phone_number": "+15555550100",
      ...
    },
    "ok": true
  }
  ```

  ```json Python theme={null}
  UserIdentity(
    user_identity_id='43947360-cdc8-4db6-8b22-e079416d1d8b',
    full_name='Jane Doe',
    phone_number='+15555550100',
    ...
  )
  ```

  ```json Ruby theme={null}
  <Seam::Resources::UserIdentity:0x005f0
    user_identity_id="43947360-cdc8-4db6-8b22-e079416d1d8b"
    full_name="Jane Doe"
    phone_number="+15555550100"
    ...
  >
  ```

  ```json PHP theme={null}
  {
    "user_identity_id": "43947360-cdc8-4db6-8b22-e079416d1d8b",
    "full_name": "Jane Doe",
    "phone_number": "+15555550100",
    ...
  }
  ```

  ```json C# theme={null}
  // Coming soon!
  ```
</CodeGroup>

***

## Create an Access Grant

To create an Access Grant, specify the user identity, entrance or space IDs, and starting and ending times. Include `mobile_key` as a requested access method.

**Code:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  await seam.accessGrants.create({
    // You can specify the ID of an existing user identity or
    // use the user_identity parameter to create a new one.
    user_identity_id: janeUser.user_identity_id,
    // You can specify acs_entrance_ids, space_ids, or both.
    acs_entrance_ids: [
      '48ebfb50-c531-43c5-b9ea-409f26dabbd7',
      'f74e4879-5991-4e2f-a368-888983dcfbfc',
    ],
    requested_access_methods: [{ mode: 'mobile_key' }],
    starts_at: '2025-07-13T15:00:00.000Z',
    ends_at: '2025-07-16T11:00:00.000Z',
  })
  ```

  ```bash cURL theme={null}
  # You can specify the ID of an existing user identity or
  # use the user_identity parameter to create a new one.
  # Also, you can specify acs_entrance_ids, space_ids, or both.
  curl -X 'POST' \
    'https://connect.getseam.com/access_grants/create' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d "{
      \"user_identity_id\": \"$(jq -r '.user_identity.user_identity_id' <<< ${jane_user})\",
      \"acs_entrance_ids\": [
        \"48ebfb50-c531-43c5-b9ea-409f26dabbd7\",
        \"f74e4879-5991-4e2f-a368-888983dcfbfc\"
      ],
      \"requested_access_methods\": [
        {\"mode\": \"mobile_key\"}
      ],
      \"starts_at\": \"2025-07-13T15:00:00.000Z\",
      \"ends_at\": \"2025-07-16T11:00:00.000Z\"
  }"
  ```

  ```python Python theme={null}
  seam.access_grants.create(
    # You can specify the ID of an existing user identity or
    # use the user_identity parameter to create a new one.
    user_identity_id=jane_user.user_identity_id,
    # You can specify acs_entrance_ids, space_ids, or both.
    acs_entrance_ids=[
      "48ebfb50-c531-43c5-b9ea-409f26dabbd7",
      "f74e4879-5991-4e2f-a368-888983dcfbfc"
    ],
    requested_access_methods=[
      {"mode": "mobile_key"}
    ],
    starts_at="2025-07-13T15:00:00.000Z",
    ends_at="2025-07-16T11:00:00.000Z"
  )
  ```

  ```ruby Ruby theme={null}
  seam.access_grants.create(
    # You can specify the ID of an existing user identity or
    # use the user_identity parameter to create a new one.
    user_identity_id: jane_user.user_identity_id,
    # You can specify acs_entrance_ids, space_ids, or both.
    acs_entrance_ids: %w[48ebfb50-c531-43c5-b9ea-409f26dabbd7 f74e4879-5991-4e2f-a368-888983dcfbfc],
    requested_access_methods: [
      {"mode": "mobile_key"}
    ],
    starts_at: "2025-07-13T15:00:00.000Z",
    ends_at: "2025-07-16T11:00:00.000Z"
  )
  ```

  ```php PHP theme={null}
  $seam->access_grants->create(
    // You can specify the ID of an existing user identity or
    // use the user_identity parameter to create a new one.
    user_identity_id: $jane_user->user_identity_id,
    // You can specify acs_entrance_ids, space_ids, or both.
    acs_entrance_ids: [
      "48ebfb50-c531-43c5-b9ea-409f26dabbd7",
      "f74e4879-5991-4e2f-a368-888983dcfbfc",
    ],
    requested_access_methods: [
      ["mode" => "mobile_key"],
    ],
    starts_at: "2025-07-13T15:00:00.000Z",
    ends_at: "2025-07-16T11:00:00.000Z"
  );
  ```

  ```csharp C# theme={null}
  // Coming Soon!
  ```
</CodeGroup>

**Output:**

<CodeGroup>
  ```json JavaScript theme={null}
  {
    "access_grant_id": "ef83cca9-5fdf-4ac2-93f3-c21c5a8be54b",
    "display_name": "My Access Grant",
    "user_identity_id": "43947360-cdc8-4db6-8b22-e079416d1d8b",
    "starts_at": "2025-07-13T15:00:00.000Z",
    "ends_at": "2025-07-16T11:00:00.000Z",
    "instant_key_url": "https://ik.seam.co/ABCXYZ",
    ...
  }

  // Share the instant_key_url with your user.
  ```

  ```json cURL theme={null}
  {
    "access_grant": {
      "access_grant_id": "ef83cca9-5fdf-4ac2-93f3-c21c5a8be54b",
      "display_name": "My Access Grant",
      "user_identity_id": "43947360-cdc8-4db6-8b22-e079416d1d8b",
      "starts_at": "2025-07-13T15:00:00.000Z",
      "ends_at": "2025-07-16T11:00:00.000Z",
      "instant_key_url": "https://ik.seam.co/ABCXYZ",
      ...
    }
  }

  # Share the instant_key_url with your user.
  ```

  ```python Python theme={null}
  AccessGrant(
    access_grant_id="ef83cca9-5fdf-4ac2-93f3-c21c5a8be54b",
    display_name="My Access Grant",
    user_identity_id="43947360-cdc8-4db6-8b22-e079416d1d8b",
    starts_at="2025-07-13T15:00:00.000Z",
    ends_at="2025-07-16T11:00:00.000Z",
    instant_key_url="https://ik.seam.co/ABCXYZ",
    ...
  )

  # Share the instant_key_url with your user.
  ```

  ```ruby Ruby theme={null}
  {
    "access_grant_id" => "ef83cca9-5fdf-4ac2-93f3-c21c5a8be54b",
    "display_name" => "My Access Grant",
    "user_identity_id" => "43947360-cdc8-4db6-8b22-e079416d1d8b",
    "starts_at" => "2025-07-13T15:00:00.000Z",
    "ends_at" => "2025-07-16T11:00:00.000Z",
    "instant_key_url" => "https://ik.seam.co/ABCXYZ",
    ...
  }

  # Share the instant_key_url with your user.
  ```

  ```php PHP theme={null}
  [
    "access_grant_id" => "ef83cca9-5fdf-4ac2-93f3-c21c5a8be54b",
    "display_name" => "My Access Grant",
    "user_identity_id" => "43947360-cdc8-4db6-8b22-e079416d1d8b",
    "starts_at" => "2025-07-13T15:00:00.000Z",
    "ends_at" => "2025-07-16T11:00:00.000Z",
    "instant_key_url" => "https://ik.seam.co/ABCXYZ",
    ...
  ];

  // Share the instant_key_url with your user.
  ```

  ```json C# theme={null}
  // Coming Soon!
  ```
</CodeGroup>

***

## Deliver the Instant Key

Share the generated `instant_key_url` with your user in your preferred way, depending on your product flow and guest experience. For most use cases, the simplest way to deliver an Instant Key is using a link in a text message or email. This method works well if you already collect the guest's phone number or email at booking.

<img alt="You can deliver an Instant Key using a link in a text message or email." />

Note that Instant Keys are also designed to have an appropriately-short validity period, as indicated by the Instant Key resource's `expires_at` property.


# Hospitality Industry Guide
Source: https://docs.seam.co/industry-guides/hospitality-industry-guide/index

Learn the key access functions that Seam provides for hospitality, as well as how to design your app to use Seam.

## Overview

This guide shows how to use the Seam API to build access control features into your hospitality app, like issuing mobile keys, Instant Keys, and plastic cards.

***

## Use Cases

<CardGroup>
  <Card title="Instant Keys">
    Seam Instant Keys are the fastest way to share access with no app download
    required! Use our no-code, fully-hosted mobile key solution.
  </Card>

  <Card title="Customized Mobile Key Apps">
    The Seam mobile SDK enables you to build your own custom mobile key app.
    Integrate once for universal access to all supported access systems.
  </Card>

  <Card title="Plastic Key Card Encoding">
    With Seam, your hospitality PMS app can convert a reservation into an issued
    access method and then encode it onto a plastic key card.
  </Card>
</CardGroup>

Seam enables you to grant and manage access to buildings, such as hotels, and much more. We integrate with multiple access systems and brands—both cloud-based and on-premises—and the Seam API standardizes key functions.

As modern hospitality PMSs, you need to develop SaaS apps that integrate with your hotel partners' multiple access systems and issue access credentials for their hotel guests. Seam enables you to improve front desk and hotel efficiency, while enhancing the guest experience.

With Seam, you can create self-check-in solutions that grant access using the following access modes:

* Instant Keys (No app download required, fully-hosted)
* Mobile keys
* Apple Wallet keys
* Plastic card encoding
* PIN codes

Seam also enables you to build efficient front desk dashboards to help you streamline front desk workflows and reduce errors. For example:

* Create a portal for agents to encode cards.
* Feed in reservation data automatically so that there are fewer errors.
* Create a user-friendly UI that reduces the learning curve for employees.

***

## Learn More

Jump into the following sections in this guide to learn more about how Seam can help you:

* [Feature Overview](/industry-guides/hospitality-industry-guide/feature-overview)
* [Seam API Overview](/industry-guides/hospitality-industry-guide/seam-api-overview)
* [Setting Up the Hotel Site](/industry-guides/hospitality-industry-guide/setting-up-the-hotel-site)
* [Granting Access Using Seam Instant Keys](/industry-guides/hospitality-industry-guide/granting-access-using-seam-instant-keys)
* [Granting Access Using Mobile Keys](/industry-guides/hospitality-industry-guide/granting-access-using-mobile-keys)
* [Granting Access Using Encoded Plastic Key Cards](/industry-guides/hospitality-industry-guide/granting-access-using-encoded-plastic-key-cards)
* [Additional Guest Access Actions](/industry-guides/hospitality-industry-guide/additional-guest-access-actions)


# Seam API Overview
Source: https://docs.seam.co/industry-guides/hospitality-industry-guide/seam-api-overview

Grant and manage guest access across all supported hotel access systems with Seam's unified API and the powerful Access Grants endpoint.

Seam provides a single unified API to grant and manage access across all supported hotel access systems. Intuitive and flexible, the Seam API makes it easy to grant access, no matter what type of device or system controls this access.

If you want the easiest, most efficient way to grant access, use the [Access Grants](../../use-cases/granting-access/index) API. This powerful API enables you to grant hotel guests access with a single call—for any access method. With this single API, you can…

* Grant access to the desired set of guest rooms and relevant common areas.
* Support mixed hardware environments without extra logic.
* Simplify onboarding and reduce maintenance as you scale.

This unified approach means that you can build access workflows once and rely on them to work everywhere.

If you need more granular control, the Seam API provides lower-level API resources and endpoints as well. In this case, use the Seam [access control system](/low-level-apis/access-systems/index) (ACS) API.

***

## Mapping Your Resources to Seam

Seam makes it easy to tag Seam resources with your own internal IDs. Use resource keys to map your own data—such as rooms, reservations, and so on—to the corresponding Seam resources. In addition, you can link your own customers with the Connect Webviews and resulting connected accounts that they use to connect their systems and devices to Seam.

For details, see [Mapping Your Resources to Seam Resources](../../core-concepts/mapping-your-resources-to-seam-resources).


# Setting Up the Hotel Site
Source: https://docs.seam.co/industry-guides/hospitality-industry-guide/setting-up-the-hotel-site

Set up your hotel access system and integrate it with your Seam-powered PMS app by confirming capabilities, connecting the site, and configuring access.

Before you can grant access using Seam, you must first set up the hotel access system and integrate it with your Seam-powered PMS app. This process consists of the following steps:

1. [Confirm access system capabilities and requirements.](#access-system-capabilities-and-requirements)
2. [Configure the access system to integrate with Seam.](#access-system-settings)
3. [Connect the hotel site to Seam.](#access-system-seam-connection)
4. [Configure the desired access settings for the hotel's guest rooms.](#guest-room-access-settings)

***

## Access System Capabilities and Requirements

Before integrating an access system with Seam, make sure that the system—including hardware and software—supports the capabilities that you want to offer guests in your hotel PMS app.

This section provides an overview of the capabilities and requirements. For more information about each supported access system and for detailed setup instructions, see the corresponding [system integration guide](/device-and-system-integration-guides#access-control-systems).

### Supported Capabilities

Before integrating an access system with Seam, it is imperative to understand which access methods the system supports, such as mobile keys and Instant Keys, plastic cards, and PIN codes. Some access systems support a subset of the access methods that you can issue through Seam. For details, see the [system integration guide](/device-and-system-integration-guides#access-control-systems) for the access system.

### Hotel Access System Requirements

To integrate with Seam, the hotel must meet the following requirements:

* The hotel may need to confirm that their access system is in a released state, rather than using a prerelease or test environment.
* If you want to use mobile keys, you must confirm that all locks support Bluetooth.
* To use encoded plastic key cards or mobile keys, the hotel may need to purchase and install the appropriate access system feature licenses.

***

## Access System Settings

To ensure successful integration with Seam, confirm or configure the following settings in the hotel access system:

* Make sure that the user account that you plan to use for the integration with Seam has the appropriate permissions.
* For some access systems, you may need to configure communications protocol settings.
* You may want to configure any available proximity behavior settings.

For details, see the [system integration guide](/device-and-system-integration-guides#access-control-systems) for the access system.

***

## Access System-Seam Connection

To connect the access system to Seam, we recommend embedding a [Connect Webview](/core-concepts/connect-webviews/index) in your app. The Seam Connect Webview flow guides the property manager through each step of the connection process.

<img alt="Example Connect Webview for an access system" />

### Connecting On-Premises Access Systems

For on-premises access systems, Seam offers the lightweight [Seam Bridge](../../capability-guides/seam-bridge) app. This software-only component runs on a computer within the same local network as the access system and creates a secure tunnel between Seam Cloud and the access system. Seam Bridge manages encryption, handles authentication, and removes the need to expose local ports to the internet.

<img alt="Use Seam Bridge to connect on-premises access systems to Seam." />

***

## Guest Room Access Settings

In the access system dashboard, the property manager configures each guest room with access to the room's door and to any relevant common access points, such as the main entrance, nearest elevator, gym, and so on. This mapping is critical to ensure that each guest has the proper access to the necessary access points at the start of their reservation.

Seam resources enable you to set a custom unique key on each object. Use this to map your own data, such as rooms, listings, or reservations, to the corresponding Seam resources. This makes it easier to cross-reference and sync information between your systems and Seam.

<div>
  <img
    alt="Example: Dashboard for mapping a hotel room listing to the corresponding
set of access points"
  />
</div>


# Encodable Key Card Quick Start
Source: https://docs.seam.co/low-level-apis/access-systems/acs-quick-starts/encodable-key-card-quick-start

Create your first encodable key card credential to start controlling an access control system with Seam.

In this quick start, create an ACS user for a virtual [ASSA ABLOY Visionline](/device-and-system-integration-guides/assa-abloy-visionline-access-control-system) access control system. Then, grant the user access to an entrance using a encodable key card credential.

<Info>
  This quick start walks you through the process that applies specifically to the Visionline ACS. There are often differences between access control systems. For example, for some access control systems, you encode credentials onto cards. For others, you do not encode data onto cards, but, rather, assign cards to users.

  Once you've completed this quick start, learn how to work with your ACS using Seam, by reading the [system integration guide](/device-and-system-integration-guides#access-control-systems) for your ACS.
</Info>

## Overview

This quick start walks you through the following basic steps:

1. [Connect](/core-concepts/workspaces/index#connecting-virtual-devices) an access control system to Seam.
   * To get started quickly, use a virtual ACS in a [sandbox workspace](/core-concepts/workspaces/index#sandbox-workspaces).

2. Install a Seam SDK and create an API key.

3. Create an [ACS user](../user-management).

4. Create an encodable key card [ACS credential](../managing-credentials) for the ACS user.

   This credential contains both the set of entrances to which the user has access and the access schedule for the user.\
   While some access control systems specify allowed entrances directly within the credential, others use access groups. For more details, see [Access Permission Assignment Variations](../connect-an-acs-to-seam/understanding-access-control-system-differences#access-permission-assignment-variations).

5. View the following information about your successfully-created credential:
   * The list of entrances to which the ACS user now has access.
   * The access schedule for the credential.

6. Encode the credential onto a card.

   Some access control systems—including Visionline—require you to encode credentials onto key cards.

:rocket: Let's get started!

***

## Step 1: Connect a Virtual ACS

In this quick start, use Seam Console to connect a virtual ACS to your sandbox workspace. Alternately, you can use the Seam API to create a [Connect Webview](/core-concepts/connect-webviews/index) and then use it to connect an ACS to Seam.

1. Log in to [Seam Console](https://console.seam.co/).

2. In the upper-left corner, click the workspace switcher and select or [create a sandbox workspace](/core-concepts/workspaces/index#create-a-sandbox-workspace).

   <img alt="Use the Seam Console workspace switcher to switch between workspaces and create new workspaces." />

3. In the top navigation pane, click **ACS Systems**.

   <img alt="Click ACS Systems to go to the Access Systems page." />

4. On the **Access Systems** page, click **New Access System**.

   Seam Console displays a Connect Webview that enables you to connect a virtual ACS to Seam.

5. In the Connect Webview, authorize the connection.

   1. Click **Continue**.

   2. In the device brand list, click **Visionline**.

   3. On the **Set up your Seam Bridge** page, click **Continue**.

      [Seam Bridge](/capability-guides/seam-bridge) is a software-only component that enables you to connect on-premises software systems to the Seam platform. Because Visionline is an on-premises ACS, Seam Bridge is required for real Visionline systems. However, this quick start uses a virtual Visionline ACS, so you do not need to install Seam Bridge.

   4. On the **Seam Bridge Connection** page, click **Submit**.

   5. On the **Enter your credentials** page:
      1. In the **Visionline Site Name** field, type any string to identify this virtual Visionline ACS site, for example, `My Visionline Site`.
      2. In the **Username** field, type `jane`.
      3. In the **Password** field, type `1234`.
      4. Click **Submit**.

   6. Click **Close**.

   The **Access Systems** page now displays the newly-connected virtual Visionline access control system.

***

## Step 2: Install a Seam SDK and Create an API Key

1. Download and install a Seam SDK in your favorite programming language.

<Tabs>
  <Tab title="JavaScript">
    ```bash theme={null}
    npm i seam
    ```
  </Tab>

  <Tab title="Python">
    ```bash theme={null}
    pip install seam
    # For some development environments, use pip3 in this command instead of pip.
    ```
  </Tab>

  <Tab title="Ruby">
    ```bash theme={null}
    bundle add seam
    ```
  </Tab>

  <Tab title="PHP">
    ```bash theme={null}
    composer require seamapi/seam
    ```
  </Tab>

  <Tab title="C#">
    Install using [nuget](https://www.nuget.org/packages/Seam).
  </Tab>
</Tabs>

2. Create an API key.
   1. In the top navigation pane of [Seam Console](https://console.seam.co/), click **Developer**.
   2. In the left navigation pane, click **API Keys**.
   3. In the upper-right corner of the **API Keys** page, click **Add API Key**.
   4. In the **Add API Key** dialog, type a name for your new API key and then click **Create API Key**.
   5. Copy the newly-created API key and store it for future use.
3. Open a terminal window and export your API key as an environment variable.

   ```sh theme={null}
   export SEAM_API_KEY=seam_test2bMS_94SrGUXuNR2JmJkjtvBQDg5c
   ```

   The Seam SDK that you have installed automatically uses this API key once you have exported it.

***

## Step 3: Create an ACS User

Create an ACS user within the virtual Visionline access control system.

1. Find the ACS system ID.
   1. In the top navigation pane of [Seam Console](https://console.seam.co/), click **ACS Systems**.
   2. On the **Access Systems** page, locate the Visionline ACS, for example, **My Visionline Site**.
   3. In the **acs\_system\_id** column for the Visionline ACS, click the ID to copy it.
   4. Store this ACS system ID for future use.
2. Create the ACS user, as follows:

**Code:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  import { Seam } from 'seam'

  const seam = new Seam() // Seam automatically uses your exported SEAM_API_KEY.

  const acsUser = await seam.acs.users.create({
    full_name: 'Jim Doe',
    // Use the ACS system ID that you copied earlier from Seam Console.
    acs_system_id: acsSystemId,
  })
  ```

  ```bash cURL theme={null}
  # Use the ACS system ID that you copied earlier from Seam Console.
  acs_user=$(curl -X 'POST' \
    'https://connect.getseam.com/acs/users/create' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d "{
    \"full_name\": \"Jim Doe\",
    \"acs_system_id\": \"${acs_system_id}\"
  }")
  ```

  ```python Python theme={null}
  from seam import Seam

  seam = Seam()  # Seam automatically uses your exported SEAM_API_KEY.

  acs_user = seam.acs.users.create(
    full_name = "Jim Doe",
    # Use the ACS system ID that you copied earlier from Seam Console.
    acs_system_id = acs_system_id
  )
  ```

  ```ruby Ruby theme={null}
  require "seam"

  seam = Seam.new() # Seam automatically uses your exported SEAM_API_KEY.

  acs_user = seam.acs.users.create(
    full_name: "Jim Doe",
    # Use the ACS system ID that you copied earlier from Seam Console.
    acs_system_id: acs_system_id
  )
  ```

  ```php PHP theme={null}
  <?php
  require 'vendor/autoload.php';

  $seam = new Seam\SeamClient(); // Seam automatically uses your exported SEAM_API_KEY.

  $acs_user = $seam->acs->users->create(
    full_name: "Jim Doe",
    // Use the ACS system ID that you copied earlier from Seam Console.
    acs_system_id: $acs_system_id
  );
  ```

  ```csharp C# theme={null}
  // Coming soon!
  ```
</CodeGroup>

**Output:**

<CodeGroup>
  ```json JavaScript theme={null}
  {
    acs_user_id: '33333333-3333-3333-3333-333333333333',
    full_name: 'Jim Doe',
    ...
  }
  ```

  ```json cURL theme={null}
  {
    "acs_user": {
      "acs_user_id": "33333333-3333-3333-3333-333333333333",
      "full_name": "Jim Doe",
      ...
    },
    "ok": true
  }
  ```

  ```json Python theme={null}
  AcsUser(
    acs_user_id='33333333-3333-3333-3333-333333333333',
    full_name='Jim Doe',
    ...
  )
  ```

  ```json Ruby theme={null}
  <Seam::Resources::AcsUser:0x005f0
    acs_user_id="33333333-3333-3333-3333-333333333333"
    full_name="Jim Doe"
    ...
  >
  ```

  ```json PHP theme={null}
  {
    "acs_user_id": "33333333-3333-3333-3333-333333333333",
    "full_name": "Jim Doe",
    ...
  }
  ```

  ```json C# theme={null}
  // Coming soon!
  ```
</CodeGroup>

***

## Step 4: Create an Encodable Key Card Credential

Create an encodable key card credential for the ACS user. In this credential, specify the set of allowed entrances and the access schedule. For Visionline, you must also specify some system-specific metadata, such as the card format and whether the credential is an [override credential](/device-and-system-integration-guides/assa-abloy-visionline-access-control-system/configuring-visionline-mobile-credentials#credential-types-for-visionline).

If this credential were intended for a real Visionline card, you'd need to create the credential and then encode this data onto the key card. Other access control systems do not use encodable cards, but, rather, assign cards to users.

1. Find the IDs of the allowed entrances.
   1. In the top navigation pane of [Seam Console](https://console.seam.co/), click **ACS Systems**.

   2. On the **Access Systems** page, click the Visionline ACS, for example, **My Visionline Site**.

   3. On the Visionline ACS page, click the **Entrances** tab.

   4. Locate the **Vingcard Lock 2** and **Guest Lock 1** entrances.

      In this example, the set of entrances includes both a common entrance and a guest room door.

   5. For each of these entrances, click **...**, click **Copy Id**, and then store this entrance ID for future use.

      <img alt="Copy the IDs for the Vingcard Lock 2 and Guest Lock 1 entrances." />

2. Create the key card credential, as follows:

**Code:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  const keyCardCredential = await seam.acs.credentials.create({
    acs_user_id: acsUser.acs_user_id,
    access_method: 'card',
    allowed_acs_entrance_ids: [vingcardLock2EntranceId, guestLock1EntranceId],
    starts_at: '2025-02-10T15:00:00.000Z',
    ends_at: '2025-02-12T11:00:00.000Z',
    visionline_metadata: {
      card_format: 'rfid48',
      override: true,
    },
  })
  ```

  ```bash cURL theme={null}
  key_card_credential=$(curl -X 'POST' \
    'https://connect.getseam.com/acs/credentials/create' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d "{
    \"acs_user_id\": \"$(jq -r '.acs_user.acs_user_id' <<< ${acs_user})\",
    \"access_method\": \"card\",
    \"allowed_acs_entrance_ids\": [
      \"${vingcard_lock_2_entrance_id}\",
      \"${guest_lock_1_entrance_id}\"
    ],
    \"starts_at\": \"2025-02-10T15:00:00.000Z\",
    \"ends_at\": \"2025-02-12T11:00:00.000Z\",
    \"visionline_metadata\": {
       \"card_format\": \"rfid48\",
       \"override\": true
    }
  }")
  ```

  ```python Python theme={null}
  key_card_credential = seam.acs.credentials.create(
    acs_user_id = acs_user.acs_user_id,
    access_method = "card",
    allowed_acs_entrance_ids = [
      vingcard_lock_2_entrance_id,
      guest_lock_1_entrance_id
    ],
    starts_at = "2025-02-10T15:00:00.000Z",
    ends_at = "2025-02-12T11:00:00.000Z",
    visionline_metadata = {
      "card_format": "rfid48",
      "override": True
    }
  )
  ```

  ```ruby Ruby theme={null}
  key_card_credential = seam.acs.credentials.create(
    acs_user_id: acs_user.acs_user_id,
    access_method: "card",
    allowed_acs_entrance_ids: [
      vingcard_lock_2_entrance_id,
      guest_lock_1_entrance_id
    ],
    starts_at: "2025-02-10T15:00:00.000Z",
    ends_at: "2025-02-12T11:00:00.000Z",
    visionline_metadata: {
      "card_format": "rfid48",
      "override": true
    }
  )
  ```

  ```php PHP theme={null}
  $key_card_credential = $seam->acs->credentials->create(
    acs_user_id: $acs_user->acs_user_id,
    access_method: "card",
    allowed_acs_entrance_ids: [
      $vingcard_lock_2_entrance_id,
      $guest_lock_1_entrance_id
    ],
    starts_at: "2025-02-10T15:00:00.000Z",
    ends_at: "2025-02-12T11:00:00.000Z",
    visionline_metadata: array('card_format' => "rfid48", 'is_override_key' => true)
  );
  ```

  ```csharp C# theme={null}
  // Coming soon!
  ```
</CodeGroup>

**Output:**

<CodeGroup>
  ```json JavaScript theme={null}
  {
    acs_credential_id: '66666666-6666-6666-6666-666666666666',
    acs_user_id: '33333333-3333-3333-3333-333333333333',
    access_method: 'card',
    starts_at: '2025-02-10T15:00:00.000Z',
    ends_at: '2025-02-12T11:00:00.000Z',
    ...
  }
  ```

  ```json cURL theme={null}
  {
    "acs_credential":
      {
        "acs_credential_id": "66666666-6666-6666-6666-666666666666",
        "acs_user_id": "33333333-3333-3333-3333-333333333333",
        "access_method": "card",
        "starts_at": "2025-02-10T15:00:00.000Z",
        "ends_at": "2025-02-12T11:00:00.000Z",
        ...
      },
    "ok":true
  }
  ```

  ```json Python theme={null}
  AcsCredential(
    acs_credential_id='66666666-6666-6666-6666-666666666666',
    acs_user_id='33333333-3333-3333-3333-333333333333',
    access_method='card',
    starts_at='2025-02-10T15:00:00.000Z',
    ends_at='2025-02-12T11:00:00.000Z',
    ...
  )
  ```

  ```json Ruby theme={null}
  <Seam::Resources::AcsCredential:0x00410
    acs_credential_id="66666666-6666-6666-6666-666666666666"
    acs_user_id="33333333-3333-3333-3333-333333333333"
    access_method="card"
    starts_at="2025-02-10T15:00:00.000Z"
    ends_at="2025-02-12T11:00:00.000Z"
    ...
  >
  ```

  ```json PHP theme={null}
  {
    "acs_credential_id": "66666666-6666-6666-6666-666666666666",
    "acs_user_id": "33333333-3333-3333-3333-333333333333",
    "access_method": "card",
    "starts_at": "2025-02-10T15:00:00.000Z",
    "ends_at": "2025-02-12T11:00:00.000Z",
    ...
  }
  ```

  ```json C# theme={null}
  // Coming soon!
  ```
</CodeGroup>

***

## Step 5: View Your New Credential

You can use Seam Console, the Seam API, or the [Seam CLI](../../../core-concepts/seam-console/seam-online-cli) to view the following information about your successfully-created credential:

* The list of entrances to which the ACS user now has access.
* The access schedule for the credential.

To use Seam Console to view information about your new key card credential:

1. In the top navigation pane of [Seam Console](https://console.seam.co/), click **ACS Systems**.

2. On the **Access Systems** page, click the Visionline ACS, for example, **My Visionline Site**.

3. In the **Users** table, click **Jim Doe**, the ACS user that you created.

   <img alt="Click the ACS user to view their credentials." />

4. In the **Credentials** tab for the ACS user, view the following information for the key card credential that you created:

   1. Under the credential name, Seam Console displays the list of list of entrances to which the credential grants access.
   2. The **Start** and **End** fields for the credential show the access schedule.

      Note that Seam Console displays times adjusted to your local computer settings. That is, the times that you see in Seam Console are the times that you specified when creating the credential, adjusted to match your computer's time settings.

   <img
     alt="View the entrances and access schedule for the credential that you
   created."
   />

***

## Step 6: Encode the Credential onto a Card

Encode the credential that you created onto a card for the Visionline access control system.

First, find the encoder that you want to use and note its ID. Then, encode the credential onto the card using the encoder that you identified. Finally, confirm that the card was encoded successfully.

For more information, see [Working with Card Encoders and Scanners](/low-level-apis/access-systems/working-with-card-encoders-and-scanners/index).

**Code:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  // Get the encoder that you want to use.
  const encoder = (
    await seam.acs.encoders.list({
      acs_system_ids: [acsSystemId],
    })
  )[0]

  // Encode the card.
  const encodingActionAttempt = await seam.acs.encoders.encodeCredential({
    acs_credential_id: keyCardCredential.acs_credential_id,
    acs_encoder_id: encoder.acs_encoder_id,
  })

  // Confirm that the encoding succeeded by
  // polling the returned action attempt
  // until its status is success.
  // You can also use a webhook.
  await seam.actionAttempts.get({
    action_attempt_id: encodingActionAttempt.action_attempt_id,
  })
  ```

  ```bash cURL theme={null}
  # Get the encoder that you want to use.
  encoder=$(curl -X 'POST' \
    'https://connect.getseam.com/acs/encoders/list' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d "{
    \"acs_system_id\": \"${acs_system_id}\"
  }" | jq -r '.acs_encoders[0]')

  # Encode the card.
  encoding_action_attempt=$(curl -X 'POST' \
    'https://connect.getseam.com/acs/encoders/encode_credential' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d "{
    \"acs_credential_id\": \"$(jq -r '.acs_credential.acs_credential_id' <<< ${key_card_credential})\",
    \"acs_encoder_id\": \"$(jq -r '.acs_encoder_id' <<< ${encoder})\"
  }")

  # Confirm that the encoding succeeded by
  # polling the returned action attempt
  # until its status is success.
  # You can also use a webhook.
  curl -X 'POST' \
    'https://connect.getseam.com/action_attempts/get' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d "{
    \"action_attempt_id\": \"$(jq -r '.action_attempt.action_attempt_id' <<< ${encoding_action_attempt})\"
  }"
  ```

  ```python Python theme={null}
  # Get the encoder that you want to use.
  encoder = seam.acs.encoders.list(
    acs_system_ids = [acs_system_id]
  )[0]

  # Encode the card.
  encoding_action_attempt = seam.acs.encoders.encode_credential(
    acs_credential_id = key_card_credential.acs_credential_id,
    acs_encoder_id = encoder.acs_encoder_id
  )

  # Confirm that the encoding succeeded by
  # polling the returned action attempt
  # until its status is success.
  # You can also use a webhook.
  seam.action_attempts.get(
    action_attempt_id = encoding_action_attempt.action_attempt_id
  )
  ```

  ```ruby Ruby theme={null}
  # Get the encoder that you want to use.
  encoder = (seam.acs.encoders.list(
    acs_system_ids: [acs_system_id]
  ))[0]

  # Encode the card.
  encoding_action_attempt = seam.acs.encoders.encode_credential(
    acs_credential_id: key_card_credential.acs_credential_id,
    acs_encoder_id: encoder.acs_encoder_id
  )

  # Confirm that the encoding succeeded by
  # polling the returned action attempt
  # until its status is success.
  # You can also use a webhook.
  seam.action_attempts.get(
    action_attempt_id: encoding_action_attempt.action_attempt_id
  )
  ```

  ```php PHP theme={null}
  // Get the encoder that you want to use.
  $encoder = $seam->acs->encoders->list(
    acs_system_ids: [$acs_system_id]
  )[0];

  // Encode the card.
  $encoding_action_attempt = $seam->acs->encoders->encode_credential(
    acs_credential_id: $key_card_credential->acs_credential_id,
    acs_encoder_id: $encoder->acs_encoder_id
  );

  // Confirm that the encoding succeeded by
  // polling the returned action attempt
  // until its status is success.
  // You can also use a webhook.
  $seam->action_attempts->get(
    action_attempt_id: $encoding_action_attempt->action_attempt_id
  );
  ```

  ```csharp C# theme={null}
  // Coming soon!
  ```
</CodeGroup>

**Output:**

<CodeGroup>
  ```json JavaScript theme={null}
  {
    status: 'success',
    action_attempt_id: '11111111-2222-3333-4444-555555555555",
    action_type: 'ENCODE_CREDENTIAL',
    result: {
      acs_credential_id: "66666666-6666-6666-6666-666666666666',
      card_number: '1234abc',
      is_issued: true,
      issued_at: '2025-02-10T12:00:00.000Z',
      ...
    },
    error: null
  }
  ```

  ```json cURL theme={null}
  {
    "action_attempt":
      {
        "status": "success",
        "action_attempt_id": "11111111-2222-3333-4444-555555555555",
        "action_type": "ENCODE_CREDENTIAL",
        "result": {
          "acs_credential_id": "66666666-6666-6666-6666-666666666666",
          "card_number": "1234abc",
          "is_issued": true,
          "issued_at": "2025-02-10T12:00:00.000Z",
          ...
        },
        "error": null
      },
    "ok": true
  }
  ```

  ```json Python theme={null}
  ActionAttempt(
    status='success',
    action_attempt_id='11111111-2222-3333-4444-555555555555',
    action_type='ENCODE_CREDENTIAL',
    result={
      acs_credential_id='66666666-6666-6666-6666-666666666666',
      card_number='1234abc',
      is_issued=True,
      issued_at='2025-02-10T12:00:00.000Z',
      ...
    },
    error=null
  )
  ```

  ```json Ruby theme={null}
  <Seam::Resources::ActionAttempt:0x00410
    status="success"
    action_attempt_id="11111111-2222-3333-4444-555555555555"
    action_type="ENCODE_CREDENTIAL"
    result={
      acs_credential_id="66666666-6666-6666-6666-666666666666"
      card_number="1234abc"
      is_issued=true,
      issued_at="2025-02-10T12:00:00.000Z"
      ...
    }
    error=nil
  >
  ```

  ```json PHP theme={null}
  {
    "status": "success",
    "action_attempt_id": "11111111-2222-3333-4444-555555555555",
    "action_type": "ENCODE_CREDENTIAL",
    "result": {
      "acs_credential_id": "66666666-6666-6666-6666-666666666666",
      "card_number": "1234abc",
      "is_issued": true,
      "issued_at": "2025-02-10T12:00:00.000Z",
      ...
    },
    "error": null
  }
  ```

  ```json C# theme={null}
  // Coming soon!
  ```
</CodeGroup>

***

## Next Steps

Now that you've created a key card credential and encoded it onto a card, try out the other ACS quick starts.

* [Mobile Key Quick Start](./mobile-key-quick-start)
* [PIN Code Quick Start](./pin-code-quick-start)

Then, [connect your ACS to Seam](/low-level-apis/access-systems/connect-an-acs-to-seam/index).

***

## Learn More

For a deeper dive into ACS concepts and instructions, see the following topics:

1. Learn about ACS concepts.
   * [Access Control System Resources](../connect-an-acs-to-seam/access-control-system-resources)
   * [Understanding ACS Differences](../connect-an-acs-to-seam/understanding-access-control-system-differences)
2. Create ACS users.
   * [Managing ACS Users](../user-management)
3. For relevant access control systems, assign ACS users to access groups.
   * [Assigning ACS Users to Access Groups](../user-management/assigning-users-to-access-groups)
4. Learn about available entrances.
   * [Retrieving Entrance Details](../retrieving-entrance-details)
5. Create credentials for ACS users.
   * [Managing Credentials](../managing-credentials)
6. For relevant access control systems, encode credentials onto key cards.
   * [Working with Card Encoders and Scanners](/low-level-apis/access-systems/working-with-card-encoders-and-scanners/index)
7. See the Seam [Access Control Systems API reference](/api/acs/object).


# Access System Quick Starts
Source: https://docs.seam.co/low-level-apis/access-systems/acs-quick-starts/index

Seam provides a unified API to manage your access system. These guides walk you through the process of issuing your first credentials to access system users.

<Info>
  **Granting access?** [Access Grants](/use-cases/granting-access/index) are the
  default and recommended way to grant access—they manage the underlying codes
  and credentials for you, across standalone smart locks and access systems
  alike.
</Info>

* [PIN Code Quick Start](/low-level-apis/access-systems/acs-quick-starts/pin-code-quick-start)\
  Create your first PIN code credential to grant an access system user scheduled access to a virtual entrance that has a keypad.
* [Encodable Key Card Quick Start](/low-level-apis/access-systems/acs-quick-starts/encodable-key-card-quick-start)\
  Create your first encodable key card credential to grant an access system user scheduled access to a virtual entrance that uses plastic card encoders and scanners.
* [Mobile Key Quick Start](/low-level-apis/access-systems/acs-quick-starts/mobile-key-quick-start)\
  Create your first mobile key credential to grant an access system user scheduled access to a virtual entrance that accepts Bluetooth low energy (BLE)-powered keys within mobile apps.

<Info>
  These quick starts introduce you to the Seam access system resources and
  processes using specific supported access control systems as examples. Note
  that there are often differences between access control systems. Once you've
  completed the quick starts, learn how to work with your access system using
  Seam, by reading the [system integration
  guide](/device-and-system-integration-guides#access-control-systems)
  for your access system.
</Info>


# Mobile Key Quick Start
Source: https://docs.seam.co/low-level-apis/access-systems/acs-quick-starts/mobile-key-quick-start

Create your first mobile key credential to start controlling an access control system with Seam.

In this quick start, create a user identity for a virtual [Salto KS](/device-and-system-integration-guides/salto-ks-access-control-system) access control system. Then, grant the user access to an entrance using a mobile key credential. With mobile keys, developers can create mobile apps that download users' credentials and then use Bluetooth low energy (BLE) or similar communications technologies to unlock granted nearby entrances. For more information about Seam's mobile access solution, see [Mobile Access](/capability-guides/mobile-access/index).

<Info>
  This quick start walks you through the process that applies specifically to
  the Salto KS ACS. There are often differences between access control systems.
  Once you've completed this quick start, learn how to work with your ACS using
  Seam, by reading the [system integration
  guide](/device-and-system-integration-guides#access-control-systems)
  for your ACS.
</Info>

## Overview

This quick start walks you through the following basic steps:

1. [Connect](/core-concepts/workspaces/index#connecting-virtual-devices) an access control system to Seam.
   * To get started quickly, use a virtual ACS in a [sandbox workspace](/core-concepts/workspaces/index#sandbox-workspaces).
2. Install a Seam SDK and create an API key.
3. Create a [user identity](/api/user_identities/object).
   * Seam user identities enable you to match your own mobile app users to ACS users.
4. Assign the user identity to an [access group](../user-management/assigning-users-to-access-groups).
   * Access groups are preconfigured to grant access to specific entrances.\
     While some access control systems use access groups, others specify allowed entrances directly within the credential. For more details, see [Access Permission Assignment Variations](../connect-an-acs-to-seam/understanding-access-control-system-differences#access-permission-assignment-variations).
5. Create a mobile key [ACS credential](../managing-credentials) for the user identity.
6. View the list of entrances to which the user now has access.

:rocket: Let's get started!

***

## Step 1: Connect a Virtual ACS

In this quick start, use Seam Console to connect a virtual ACS to your sandbox workspace. Alternately, you can use the Seam API to create a [Connect Webview](/core-concepts/connect-webviews/index) and then use it to connect an ACS to Seam.

1. Log in to [Seam Console](https://console.seam.co/).

2. In the upper-left corner, click the workspace switcher and select or [create a sandbox workspace](/core-concepts/workspaces/index#create-a-sandbox-workspace).

   <img alt="Use the Seam Console workspace switcher to switch between workspaces and create new workspaces." />

3. In the top navigation pane, click **ACS Systems**.

   <img alt="Click ACS Systems to go to the Access Systems page." />

4. On the **Access Systems** page, click **New Access System**.

   Seam Console displays a Connect Webview that enables you to connect a virtual ACS to Seam.

5. In the Connect Webview, authorize the connection.

   1. Click **Continue**.
   2. In the device brand list, click **Salto KS**.
   3. On the Salto KS authorization page:
      1. In the **Email** field, type `jane@example.com`.
      2. In the **Password** field, type `1234`.
      3. Click **Log In**.
      4. When prompted to allow application access, click **Yes, Allow**.
      5. In the sites list, select **Main Site** and then click **Continue**.
      6. When prompted to allow Seam to add a user to the virtual Salto KS Site, click **Allow and Continue**.
      7. Click **Close**.

   The **Access Systems** page now displays the newly-connected virtual Salto KS access control system.

***

## Step 2: Install a Seam SDK and Create an API Key

1. Download and install a Seam SDK in your favorite programming language.

<Tabs>
  <Tab title="JavaScript">
    ```bash theme={null}
    npm i seam
    ```
  </Tab>

  <Tab title="Python">
    ```bash theme={null}
    pip install seam
    # For some development environments, use pip3 in this command instead of pip.
    ```
  </Tab>

  <Tab title="Ruby">
    ```bash theme={null}
    bundle add seam
    ```
  </Tab>

  <Tab title="PHP">
    ```bash theme={null}
    composer require seamapi/seam
    ```
  </Tab>

  <Tab title="C#">
    Install using [nuget](https://www.nuget.org/packages/Seam).
  </Tab>
</Tabs>

2. Create an API key.
   1. In the top navigation pane of [Seam Console](https://console.seam.co/), click **Developer**.
   2. In the left navigation pane, click **API Keys**.
   3. In the upper-right corner of the **API Keys** page, click **Add API Key**.
   4. In the **Add API Key** dialog, type a name for your new API key and then click **Create API Key**.
   5. Copy the newly-created API key and store it for future use.
3. Open a terminal window and export your API key as an environment variable.

   ```sh theme={null}
   export SEAM_API_KEY=seam_test2bMS_94SrGUXuNR2JmJkjtvBQDg5c
   ```

   The Seam SDK that you have installed automatically uses this API key once you have exported it.

***

## Step 3: Create a User Identity

Create a user identity to represent a mobile app user.

1. Find the ACS system ID.
   1. In the top navigation pane of [Seam Console](https://console.seam.co/), click **ACS Systems**.
   2. On the **Access Systems** page, locate the Salto KS Main Site ACS.
   3. In the **acs\_system\_id** column for the Main Site ACS, click the ID to copy it.
   4. Store this ACS system ID for future use.
2. Create the user identity, as follows:

**Code:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  import { Seam } from 'seam'

  const seam = new Seam() // Seam automatically uses your exported SEAM_API_KEY.

  const jenDoeUser = await seam.userIdentities.create({
    full_name: 'Jen Doe',
    email_address: 'jen.doe@example.com',
    // Use the ACS system ID that you copied earlier from Seam Console.
    acs_system_id: acsSystemId,
  })
  ```

  ```bash cURL theme={null}
  # Use the ACS system ID that you copied earlier from Seam Console.
  jen_doe_user=$(curl -X 'POST' \
    'https://connect.getseam.com/user_identities/create' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d "{
    \"full_name\": \"Jen Doe\",
    \"email_address\": \"jen.doe@example.com\",
    \"acs_system_id\": \"${acs_system_id}\",
  }")
  ```

  ```python Python theme={null}
  from seam import Seam

  seam = Seam()  # Seam automatically uses your exported SEAM_API_KEY.

  jen_doe_user = seam.user_identities.create(
    full_name="Jen Doe",
    email_address="jen.doe@example.com",
    # Use the ACS system ID that you copied earlier from Seam Console.
    acs_system_ids=[acs_system_id]
  )
  ```

  ```ruby Ruby theme={null}
  require "seam"

  seam = Seam.new() # Seam automatically uses your exported SEAM_API_KEY.

  jen_doe_user = seam.user_identities.create(
    full_name: "Jen Doe",
    email_address: "jen.doe@example.com",
    # Use the ACS system ID that you copied earlier from Seam Console.
    acs_system_id: acs_system_id,
  )
  ```

  ```php PHP theme={null}
  <?php
  require 'vendor/autoload.php';

  $seam = new Seam\SeamClient(); // Seam automatically uses your exported SEAM_API_KEY.

  $jen_doe_user = $seam->user_identities->create(
    full_name: "Jen Doe",
    email_address: "jen.doe@example.com",
    // Use the ACS system ID that you copied earlier from Seam Console.
    acs_system_id: $acs_system_id,
  );
  ```

  ```csharp C# theme={null}
  // Coming soon!
  ```
</CodeGroup>

**Output:**

<CodeGroup>
  ```json JavaScript theme={null}
  {
    "user_identity_id": "22222222-2222-2222-2222-222222222222",
    "full_name": "Jen Doe",
    "email_address": "jen.doe@example.com",
    ...
  }
  ```

  ```json cURL theme={null}
  {
    "user_identity": {
      "user_identity_id": "22222222-2222-2222-2222-222222222222",
      "full_name": "Jen Doe",
      "email_address": "jen.doe@example.com",
      ...
    },
    "ok": true
  }
  ```

  ```json Python theme={null}
  UserIdentity(
    user_identity_id='22222222-2222-2222-2222-222222222222',
    full_name='Jen Doe',
    email_address='jen.doe@example.com',
    ...
  )
  ```

  ```json Ruby theme={null}
  <Seam::Resources::UserIdentity:0x005f0
    user_identity_id="22222222-2222-2222-2222-222222222222"
    full_name="Jen Doe"
    email_address="jen.doe@example.com"
    ...
  >
  ```

  ```json PHP theme={null}
  {
    "user_identity_id": "22222222-2222-2222-2222-222222222222",
    "full_name": "Jen Doe",
    "email_address": "jen.doe@example.com",
    ...
  }
  ```

  ```json C# theme={null}
  // Coming soon!
  ```
</CodeGroup>

***

## Step 4: Assign the User Identity to an Access Group

Add the user identity to an access group. For Salto KS, access groups specify the entrances to which users have access.

Some other access control systems do not use access groups and, instead, specify allowed entrances directly within the credential. For more details, see [Access Permission Assignment Variations](../connect-an-acs-to-seam/understanding-access-control-system-differences#access-permission-assignment-variations).

1. Find the access group ID.
   1. In the top navigation pane of [Seam Console](https://console.seam.co/), click **ACS Systems**.
   2. On the **Access Systems** page, click the Salto KS Main Site ACS.
   3. On the **Main Site** page, click the **Access Groups** tab.
   4. Locate the Main Group, click **...**, and click **Copy Id**.
   5. Store this access group ID for future use.
2. Assign the user identity to the Main Group, as follows:

**Code:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  await seam.acs.accessGroups.addUser({
    // Use the access group ID that you copied earlier from Seam Console.
    acs_access_group_id: accessGroupId,
    user_identity_id: jenDoeUser.user_identity_id,
  })
  ```

  ```bash cURL theme={null}
  # Use the access group ID that you copied earlier from Seam Console.
  curl -X 'POST' \
    'https://connect.getseam.com/acs/access_groups/add_user' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d "{
    \"acs_access_group_id\": \"${access_group_id}\",
    \"user_identity_id\": \"$(jq -r '.user_identity.user_identity_id' <<< ${jen_doe_user})\"
  }"
  ```

  ```python Python theme={null}
  seam.acs.access_groups.add_user(
    # Use the access group ID that you copied earlier from Seam Console.
    acs_access_group_id = access_group_id,
    user_identity_id = jen_doe_user.user_identity_id
  )
  ```

  ```ruby Ruby theme={null}
  seam.acs.access_groups.add_user(
    # Use the access group ID that you copied earlier from Seam Console.
    acs_access_group_id: access_group_id,
    user_identity_id: jen_doe_user.user_identity_id
  )
  ```

  ```php PHP theme={null}
  $seam->acs->access_groups->add_user(
    // Use the access group ID that you copied earlier from Seam Console.
    acs_access_group_id: $access_group_id,
    user_identity_id: jen_doe_user.user_identity_id
  );
  ```

  ```csharp C# theme={null}
  // Coming soon!
  ```
</CodeGroup>

**Output:**

<CodeGroup>
  ```json JavaScript theme={null}
  void
  ```

  ```json cURL theme={null}
  {
    "ok": true
  }
  ```

  ```json Python theme={null}
  None
  ```

  ```json Ruby theme={null}
  nil
  ```

  ```json PHP theme={null}
  void
  ```

  ```json C# theme={null}
  // Coming soon!
  ```
</CodeGroup>

***

## Step 5: Create a Mobile Key Credential

Create a mobile key credential for the user identity.

**Code:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  const mobileKey = await seam.acs.credentials.create({
    user_identity_id: jenDoeUser.user_identity_id,
    is_multi_phone_sync_credential: true,
    access_method: 'mobile_key',
  })
  ```

  ```bash cURL theme={null}
  mobile_key=$(curl -X 'POST' \
    'https://connect.getseam.com/acs/credentials/create' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d "{
    \"user_identity_id\": \"$(jq -r '.user_identity.user_identity_id' <<< ${jen_doe_user})\",
    \"is_multi_phone_sync_credential\": true,
    \"access_method\": \"mobile_key\"
  }")
  ```

  ```python Python theme={null}
  mobile_key = seam.acs.credentials.create(
    user_identity_id = jen_doe_user.user_identity_id,
    is_multi_phone_sync_credential = True,
    access_method = "mobile_key"
  )
  ```

  ```ruby Ruby theme={null}
  mobile_key = seam.acs.credentials.create(
    user_identity_id: jen_doe_user.user_identity_id,
    is_multi_phone_sync_credential: true,
    access_method: "mobile_key"
  )
  ```

  ```php PHP theme={null}
  $pin_code_credential = $seam->acs->credentials->create(
    user_identity_id: $jen_doe_user->user_identity_id,
    is_multi_phone_sync_credential: true,
    access_method: "mobile_key"
  );
  ```

  ```csharp C# theme={null}
  // Coming soon!
  ```
</CodeGroup>

**Output:**

<CodeGroup>
  ```json JavaScript theme={null}
  {
    acs_credential_id: '66666666-6666-6666-6666-666666666666',
    acs_system_id: '11111111-1111-1111-1111-111111111111',
    user_identity_id: '22222222-2222-2222-2222-222222222222',
    access_method: 'mobile_key',
    ...
  }
  ```

  ```json cURL theme={null}
  {
    "acs_credential":{
      "acs_credential_id": "66666666-6666-6666-6666-666666666666",
      "acs_system_id": "11111111-1111-1111-1111-111111111111",
      "user_identity_id": "22222222-2222-2222-2222-222222222222",
      "access_method": "mobile_key",
      ...
    }
  }
  ```

  ```json Python theme={null}
  AcsCredential(
    acs_credential_id='66666666-6666-6666-6666-666666666666',
    acs_system_id='11111111-1111-1111-1111-111111111111',
    user_identity_id='22222222-2222-2222-2222-222222222222',
    access_method='mobile_key',
    ...
  )
  ```

  ```json Ruby theme={null}
  <Seam::Resources::AcsCredential:0x005f0
    acs_credential_id="66666666-6666-6666-6666-666666666666"
    acs_system_id="11111111-1111-1111-1111-111111111111"
    user_identity_id= "22222222-2222-2222-2222-222222222222"
    access_method="mobile_key"
    ...
  >
  ```

  ```json PHP theme={null}
  {
    "acs_credential_id": "66666666-6666-6666-6666-666666666666",
    "acs_system_id": "11111111-1111-1111-1111-111111111111",
    "user_identity_id": "22222222-2222-2222-2222-222222222222",
    "access_method": "mobile_key",
    ...
  }
  ```

  ```json C# theme={null}
  // Coming soon!
  ```
</CodeGroup>

***

## Step 6: View Your New Credential

You can use Seam Console, the Seam API, or the [Seam CLI](../../../core-concepts/seam-console/seam-online-cli) to view the list of entrances to which the ACS user now has access.

To use Seam Console to view information about your new PIN code credential:

1. In the top navigation pane of [Seam Console](https://console.seam.co/), click **ACS Systems**.

2. On the **Access Systems** page, click the Salto KS Main Site ACS.

3. In the **Users** table, click **Jen Doe**, the ACS user that you created.

   <img alt="Click the ACS user to view their credentials." />

4. In the **Credentials** tab for the ACS user, note the mobile key credential (multi-phone sync credential) that you created.

5. Click the **Access Groups** tab for the ACS user.

6. Click the **Main Group** access group.

7. On the **Main Group** page click the **Entrances** tab and then view the entrances to which this access group grants the ACS user access.

   <img
     alt="View the entrances to which the ACS user has access as a member of the
   access group."
   />

<Info>
  This quick start shows the server-side portion of the mobile access
  development process. The other piece of this process is to develop a mobile
  app that downloads the user's mobile keys and then uses BLE or similar
  technology to unlock nearby entrances to which the user's credentials grant
  access. For details, see [Integrating into your mobile
  application](/capability-guides/mobile-access/mobile-device-sdks/index).
</Info>

***

## Next Steps

Now that you've created a mobile key credential, try out the other ACS quick starts.

* [PIN Code Quick Start](/low-level-apis/access-systems/acs-quick-starts/pin-code-quick-start)
* [Key Card Quick Start](/low-level-apis/access-systems/acs-quick-starts/encodable-key-card-quick-start)

Then, [connect your ACS to Seam](/low-level-apis/access-systems/connect-an-acs-to-seam/index).

***

## Learn More

For a deeper dive into ACS concepts and instructions, see the following topics:

1. Learn about ACS concepts.
   * [Access Control System Resources](../connect-an-acs-to-seam/access-control-system-resources)
   * [Understanding ACS Differences](../connect-an-acs-to-seam/understanding-access-control-system-differences)
2. Create user identities.
   * [Managing Mobile App User Accounts with User Identities](/capability-guides/mobile-access/managing-mobile-app-user-accounts-with-user-identities)
3. For relevant access control systems, assign user identities to access groups.
   * [Adding User Identities to Access Groups](/api/acs/access_groups/add_user)
4. Learn about available entrances.
   * [Retrieving Entrance Details](../retrieving-entrance-details)
5. Create credentials for ACS users.
   * [Managing Credentials](../managing-credentials)
6. Learn more about the Seam mobile access solution.
   * [Mobile Access](/capability-guides/mobile-access/index)
   * [Integrating into your mobile application](/capability-guides/mobile-access/mobile-device-sdks/index)
7. See the Seam [Access Control Systems API reference](/api/acs/object).


# PIN Code Quick Start
Source: https://docs.seam.co/low-level-apis/access-systems/acs-quick-starts/pin-code-quick-start

Create your first PIN code credential to start controlling an access control system with Seam.

In this quick start, create an ACS user for a virtual [Salto KS](/device-and-system-integration-guides/salto-ks-access-control-system) access control system. Then, grant the user access to an entrance using a PIN code credential.

<Info>
  This quick start walks you through the process that applies specifically to
  the Salto KS ACS. There are often differences between access control systems.
  Once you've completed this quick start, learn how to work with your ACS using
  Seam, by reading the [system integration
  guide](/device-and-system-integration-guides#access-control-systems)
  for your ACS.
</Info>

## Overview

This quick start walks you through the following basic steps:

1. [Connect](/core-concepts/workspaces/index#connecting-virtual-devices) an access control system to Seam.
   * To get started quickly, use a virtual ACS in a [sandbox workspace](/core-concepts/workspaces/index#sandbox-workspaces).
2. Install a Seam SDK and create an API key.
3. Create an [ACS user](../user-management).
   * Also, specify the access schedule for this user.
4. Assign the ACS user to an [access group](../user-management/assigning-users-to-access-groups).
   * Access groups are preconfigured to grant access to specific entrances.\
     While some access control systems use access groups, others specify allowed entrances directly within the credential. For more details, see [Access Permission Assignment Variations](../connect-an-acs-to-seam/understanding-access-control-system-differences#access-permission-assignment-variations).
5. Create a PIN code [ACS credential](../managing-credentials) for the ACS user.
6. View the following information about your successfully-created credential:
   * The PIN code for the credential.
   * The access schedule for the ACS user.
   * The list of entrances to which the ACS user now has access.

:rocket: Let's get started!

***

## Step 1: Connect a Virtual ACS

In this quick start, use Seam Console to connect a virtual ACS to your sandbox workspace. Alternately, you can use the Seam API to create a [Connect Webview](/core-concepts/connect-webviews/index) and then use it to connect an ACS to Seam.

1. Log in to [Seam Console](https://console.seam.co/).

2. In the upper-left corner, click the workspace switcher and select or [create a sandbox workspace](/core-concepts/workspaces/index#create-a-sandbox-workspace).

   <img alt="Use the Seam Console workspace switcher to switch between workspaces and create new workspaces." />

3. In the top navigation pane, click **ACS Systems**.

   <img alt="Click ACS Systems to go to the Access Systems page." />

4. On the **Access Systems** page, click **New Access System**.

   Seam Console displays a Connect Webview that enables you to connect a virtual ACS to Seam.

5. In the Connect Webview, authorize the connection.

   1. Click **Continue**.
   2. In the device brand list, click **Salto KS**.
   3. On the Salto KS authorization page:
      1. In the **Email** field, type `jane@example.com`.
      2. In the **Password** field, type `1234`.
      3. Click **Log In**.
      4. When prompted to allow application access, click **Yes, Allow**.
      5. In the sites list, select **Main Site** and then click **Continue**.
      6. Click **Close**.

   The **Access Systems** page now displays the newly-connected virtual Salto KS access control system.

***

## Step 2: Install a Seam SDK and Create an API Key

1. Download and install a Seam SDK in your favorite programming language.

<Tabs>
  <Tab title="JavaScript">
    ```bash theme={null}
    npm i seam
    ```
  </Tab>

  <Tab title="Python">
    ```bash theme={null}
    pip install seam
    # For some development environments, use pip3 in this command instead of pip.
    ```
  </Tab>

  <Tab title="Ruby">
    ```bash theme={null}
    bundle add seam
    ```
  </Tab>

  <Tab title="PHP">
    ```bash theme={null}
    composer require seamapi/seam
    ```
  </Tab>

  <Tab title="C#">
    Install using [nuget](https://www.nuget.org/packages/Seam).
  </Tab>
</Tabs>

2. Create an API key.
   1. In the top navigation pane of [Seam Console](https://console.seam.co/), click **Developer**.
   2. In the left navigation pane, click **API Keys**.
   3. In the upper-right corner of the **API Keys** page, click **Add API Key**.
   4. In the **Add API Key** dialog, type a name for your new API key and then click **Create API Key**.
   5. Copy the newly-created API key and store it for future use.
3. Open a terminal window and export your API key as an environment variable.

   ```sh theme={null}
   export SEAM_API_KEY=seam_test2bMS_94SrGUXuNR2JmJkjtvBQDg5c
   ```

   The Seam SDK that you have installed automatically uses this API key once you have exported it.

***

## Step 3: Create an ACS User

Create an ACS user within the virtual Salto KS access control system, and specify an access schedule for this user.

1. Find the ACS system ID.
   1. In the top navigation pane of [Seam Console](https://console.seam.co/), click **ACS Systems**.
   2. On the **Access Systems** page, locate the Salto KS Main Site ACS.
   3. In the **acs\_system\_id** column for the Main Site ACS, click the ID to copy it.
   4. Store this ACS system ID for future use.
2. Create the ACS user, as follows:

**Code:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  import { Seam } from 'seam'

  const seam = new Seam() // Seam automatically uses your exported SEAM_API_KEY.

  const acsUser = await seam.acs.users.create({
    full_name: 'June Doe',
    // Use the ACS system ID that you copied earlier from Seam Console.
    acs_system_id: acsSystemId,
    access_schedule: {
      starts_at: '2025-02-10T15:00:00.000Z',
      ends_at: '2025-02-12T11:00:00.000Z',
    },
  })
  ```

  ```bash cURL theme={null}
  # Use the ACS system ID that you copied earlier from Seam Console.
  acs_user=$(curl -X 'POST' \
    'https://connect.getseam.com/acs/users/create' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d "{
    \"full_name\": \"June Doe\",
    \"acs_system_id\": \"${acs_system_id}\",
    \"access_schedule\": {
        \"starts_at\": \"2025-02-10T15:00:00.000Z\",
        \"ends_at\": \"2025-02-12T11:00:00.000Z\"
    }
  }")
  ```

  ```python Python theme={null}
  from seam import Seam

  seam = Seam()  # Seam automatically uses your exported SEAM_API_KEY.

  acs_user = seam.acs.users.create(
    full_name = "June Doe",
    # Use the ACS system ID that you copied earlier from Seam Console.
    acs_system_id = acs_system_id,
    access_schedule = {
      "starts_at": "2025-02-10T15:00:00.000Z",
      "ends_at": "2025-02-12T11:00:00.000Z"
    }
  )
  ```

  ```ruby Ruby theme={null}
  require "seam"

  seam = Seam.new() # Seam automatically uses your exported SEAM_API_KEY.

  acs_user = seam.acs.users.create(
    full_name: "June Doe",
    # Use the ACS system ID that you copied earlier from Seam Console.
    acs_system_id: acs_system_id,
    access_schedule: {
      "starts_at": "2025-02-10T15:00:00.000Z",
      "ends_at": "2025-02-12T11:00:00.000Z"
    }
  )
  ```

  ```php PHP theme={null}
  <?php
  require 'vendor/autoload.php';

  $seam = new Seam\SeamClient(); // Seam automatically uses your exported SEAM_API_KEY.

  $acs_user = $seam->acs->users->create(
    full_name: "June Doe",
    // Use the ACS system ID that you copied earlier from Seam Console.
    acs_system_id: $acs_system_id,
    access_schedule: array(
      "starts_at" => "2025-02-10T15:00:00.000Z",
      "ends_at" => "2025-02-12T11:00:00.000Z"
    )
  );
  ```

  ```csharp C# theme={null}
  // Coming soon!
  ```
</CodeGroup>

**Output:**

<CodeGroup>
  ```json JavaScript theme={null}
  {
    acs_user_id: '33333333-3333-3333-3333-333333333333',
    full_name: 'June Doe',
    access_schedule: {
      "starts_at": "2025-02-10T15:00:00.000Z",
      "ends_at": "2025-02-12T11:00:00.000Z"
    },
    ...
  }
  ```

  ```json cURL theme={null}
  {
    "acs_user": {
      "acs_user_id": "33333333-3333-3333-3333-333333333333",
      "full_name": "June Doe",
      "access_schedule": {
        "starts_at": "2025-02-10T15:00:00.000Z",
        "ends_at": "2025-02-12T11:00:00.000Z"
      },
      ...
    },
    "ok": true
  }
  ```

  ```json Python theme={null}
  AcsUser(
    acs_user_id='33333333-3333-3333-3333-333333333333',
    full_name='June Doe',
    access_schedule={
      'starts_at': '2025-02-10T15:00:00.000Z',
      'ends_at': '2025-02-12T11:00:00.000Z'
    },
    ...
  )
  ```

  ```json Ruby theme={null}
  <Seam::Resources::AcsUser:0x005f0
    acs_user_id="33333333-3333-3333-3333-333333333333"
    full_name="June Doe"
    access_schedule=#<Seam::DeepHashAccessor:0x000001fd69e446f8 @data={
      "starts_at"=>"2025-02-10T15:00:00.000Z",
      "ends_at"=>"2025-02-12T11:00:00.000Z"
    }>
    ...
  >
  ```

  ```json PHP theme={null}
  {
    "acs_user_id": "33333333-3333-3333-3333-333333333333",
    "full_name": "June Doe",
    "access_schedule": {
      "starts_at": "2025-02-10T15:00:00.000Z",
      "ends_at": "2025-02-12T11:00:00.000Z"
    },
    ...
  }
  ```

  ```json C# theme={null}
  // Coming soon!
  ```
</CodeGroup>

***

## Step 4: Assign the ACS User to an Access Group

Add the ACS user to an access group. For Salto KS, access groups specify the entrances to which users have access.

Some other access control systems do not use access groups and, instead, specify allowed entrances directly within the credential. For more details, see [Access Permission Assignment Variations](../connect-an-acs-to-seam/understanding-access-control-system-differences#access-permission-assignment-variations).

1. Find the access group ID.
   1. In the top navigation pane of [Seam Console](https://console.seam.co/), click **ACS Systems**.
   2. On the **Access Systems** page, click the Salto KS Main Site ACS.
   3. On the **Main Site** page, click the **Access Groups** tab.
   4. Locate the Main Group, click **...**, and click **Copy Id**.
   5. Store this access group ID for future use.
2. Assign the ACS user to the Main Group, as follows:

**Code:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  await seam.acs.users.addToAccessGroup({
    acs_user_id: acsUser.acs_user_id,
    // Use the access group ID that you copied earlier from Seam Console.
    acs_access_group_id: accessGroupId,
  })
  ```

  ```bash cURL theme={null}
  # Use the access group ID that you copied earlier from Seam Console.
  curl -X 'POST' \
    'https://connect.getseam.com/acs/users/add_to_access_group' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d "{
    \"acs_user_id\": \"$(jq -r '.acs_user.acs_user_id' <<< ${acs_user})\",
    \"acs_access_group_id\": \"${access_group_id}\"
  }"
  ```

  ```python Python theme={null}
  seam.acs.users.add_to_access_group(
    acs_user_id = acs_user.acs_user_id,
    # Use the access group ID that you copied earlier from Seam Console.
    acs_access_group_id = access_group_id
  )
  ```

  ```ruby Ruby theme={null}
  seam.acs.users.add_to_access_group(
    acs_user_id: acs_user.acs_user_id,
    # Use the access group ID that you copied earlier from Seam Console.
    acs_access_group_id: access_group_id
  )
  ```

  ```php PHP theme={null}
  $seam->acs->users->add_to_access_group(
    acs_user_id: $acs_user->acs_user_id,
    // Use the access group ID that you copied earlier from Seam Console.
    acs_access_group_id: $access_group_id
  );
  ```

  ```csharp C# theme={null}
  // Coming soon!
  ```
</CodeGroup>

**Output:**

<CodeGroup>
  ```json JavaScript theme={null}
  void
  ```

  ```json cURL theme={null}
  {
    "ok": true
  }
  ```

  ```json Python theme={null}
  None
  ```

  ```json Ruby theme={null}
  nil
  ```

  ```json PHP theme={null}
  void
  ```

  ```json C# theme={null}
  // Coming soon!
  ```
</CodeGroup>

***

## Step 5: Create a PIN Code Credential

Create a PIN code credential for the ACS user. After you create the credential, Salto KS generates the corresponding PIN code.

**Code:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  const pinCodeCredential = await seam.acs.credentials.create({
    acs_user_id: acsUser.acs_user_id,
    access_method: 'code',
  })
  ```

  ```bash cURL theme={null}
  pin_code_credential=$(curl -X 'POST' \
    'https://connect.getseam.com/acs/credentials/create' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d "{
    \"acs_user_id\": \"$(jq -r '.acs_user.acs_user_id' <<< ${acs_user})\",
    \"access_method\": \"code\"
  }")
  ```

  ```python Python theme={null}
  pin_code_credential = seam.acs.credentials.create(
    acs_user_id = acs_user.acs_user_id,
    access_method = "code"
  )
  ```

  ```ruby Ruby theme={null}
  pin_code_credential = seam.acs.credentials.create(
    acs_user_id: acs_user.acs_user_id,
    access_method: "code"
  )
  ```

  ```php PHP theme={null}
  $pin_code_credential = $seam->acs->credentials->create(
    acs_user_id: $acs_user->acs_user_id,
    access_method: "code"
  );
  ```

  ```csharp C# theme={null}
  // Coming soon!
  ```
</CodeGroup>

**Output:**

<CodeGroup>
  ```json JavaScript theme={null}
  {
    acs_credential_id: '66666666-6666-6666-6666-666666666666',
    acs_system_id: '11111111-1111-1111-1111-111111111111',
    acs_user_id: '33333333-3333-3333-3333-333333333333',
    code: '123456',
    access_method: 'code',
    ...
  }
  ```

  ```json cURL theme={null}
  {
    "acs_credential":{
      "acs_credential_id": "66666666-6666-6666-6666-666666666666",
      "acs_system_id": "11111111-1111-1111-1111-111111111111",
      "acs_user_id": "33333333-3333-3333-3333-333333333333",
      "code": "123456",
      "access_method": "code",
      ...
    }
  }
  ```

  ```json Python theme={null}
  AcsCredential(
    acs_credential_id='66666666-6666-6666-6666-666666666666',
    acs_system_id='11111111-1111-1111-1111-111111111111',
    acs_user_id='33333333-3333-3333-3333-333333333333',
    code='123456',
    access_method='code',
    ...
  )
  ```

  ```json Ruby theme={null}
  <Seam::Resources::AcsCredential:0x005f0
    acs_credential_id="66666666-6666-6666-6666-666666666666"
    acs_user_id="33333333-3333-3333-3333-333333333333"
    code="123456"
    access_method="code"
    ...
  >
  ```

  ```json PHP theme={null}
  {
    "acs_credential_id": "66666666-6666-6666-6666-666666666666",
    "acs_system_id": "11111111-1111-1111-1111-111111111111",
    "acs_user_id": "33333333-3333-3333-3333-333333333333",
    "code": "123456",
    "access_method": "code",
    ...
  }
  ```

  ```json C# theme={null}
  // Coming soon!
  ```
</CodeGroup>

***

## Step 6: View Your New Credential

You can use Seam Console, the Seam API, or the [Seam CLI](../../../core-concepts/seam-console/seam-online-cli) to view the following information about your successfully-created credential:

* The PIN code for the credential.
* The access schedule for the ACS user.
* The list of entrances to which the ACS user now has access.

To use Seam Console to view information about your new PIN code credential:

1. In the top navigation pane of [Seam Console](https://console.seam.co/), click **ACS Systems**.

2. On the **Access Systems** page, click the Salto KS Main Site ACS.

3. In the **Users** table, click **June Doe**, the ACS user that you created.

   <img alt="Click the ACS user to view their credentials." />

4. In the **Credentials** tab for the ACS user, view the **Code** for the PIN code credential that you created.

   <img alt="View the PIN code for the credential that you created." />

5. In the **Properties** area for the ACS user, view the user's access schedule.\
   Note that Seam Console displays times adjusted to your local computer settings. That is, the times that you see in Seam Console are the times that you specified when creating the credential, adjusted to match your computer's time settings.

   <img alt="View the access schedule for the ACS user." />

6. Click the **Access Groups** tab for the ACS user.

7. Click the **Main Group** access group.

8. On the **Main Group** page click the **Entrances** tab and then view the entrances to which this access group grants the ACS user access.

   <img
     alt="View the entrances to which the ACS user has access as a member of the
   access group."
   />

***

## Next Steps

Now that you've created a PIN code credential, try out the other ACS quick starts.

* [Key Card Quick Start](/low-level-apis/access-systems/acs-quick-starts/encodable-key-card-quick-start)
* [Mobile Key Quick Start](/low-level-apis/access-systems/acs-quick-starts/mobile-key-quick-start)

Then, [connect your ACS to Seam](/low-level-apis/access-systems/connect-an-acs-to-seam/index).

***

## Learn More

For a deeper dive into ACS concepts and instructions, see the following topics:

1. Learn about ACS concepts.
   * [Access Control System Resources](../connect-an-acs-to-seam/access-control-system-resources)
   * [Understanding ACS Differences](../connect-an-acs-to-seam/understanding-access-control-system-differences)
2. Create ACS users.
   * [Managing ACS Users](../user-management)
3. For relevant access control systems, assign ACS users to access groups.
   * [Assigning ACS Users to Access Groups](../user-management/assigning-users-to-access-groups)
4. Learn about available entrances.
   * [Retrieving Entrance Details](../retrieving-entrance-details)
5. Create credentials for ACS users.
   * [Managing Credentials](../managing-credentials)
6. See the Seam [Access Control Systems API reference](/api/acs/object).


# Access Control System Resources
Source: https://docs.seam.co/low-level-apis/access-systems/connect-an-acs-to-seam/access-control-system-resources

Learn about the Seam resources that you use to manage your ACS.

The Seam ACS schema consists of a series of resources. These resources interact intuitively, enabling you to manage your ACS in a logical, efficient manner. Seam's universal API provides the flexibility to manage a variety of [ACSs](./understanding-access-control-system-differences), each of which may have manufacturer-specific differences. For details about your ACS, see the corresponding [system integration guide](/device-and-system-integration-guides#access-control-systems).

The following diagram shows an example of one ACS, including the ACS resources and the relationships between them:

<img
  alt="Seam's ACS resources provide the flexibility to manage your ACS
intuitively, regardless of the differences between various ACS
manufacturers."
/>

The following table provides a brief description of each of the Seam ACS resources:

<table>
  <thead>
    <tr>
      <th>ACS Resource</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        <p>
          <img alt="" />
        </p>

        <p>
          <a href="/api/acs/systems/object">
            <code>acs\_system</code>
          </a>
        </p>
      </td>

      <td>
        The top-level object. Represents one or more buildings, residential
        locations, or other sites that you manage using this ACS.

        <br />

        For more information, see

        <a href="/low-level-apis/access-systems/connect-an-acs-to-seam/retrieving-acs-system-details">
          Retrieving ACS System Details
        </a>

        .
      </td>
    </tr>

    <tr>
      <td>
        <p>
          <img alt="" />
        </p>

        <p>
          <a href="/api/acs/users/object">
            <code>acs\_user</code>
          </a>
        </p>
      </td>

      <td>
        <p>The set of users who access the entrances.</p>

        <p>
          If you manage multiple ACSs and need to grant the same user access to
          <a href="/low-level-apis/access-systems/retrieving-entrance-details">entrances</a> in multiple
          ACSs, you can also use Seam

          <a href="/api/user_identities/object">
            user identities
          </a>

          . With user identities, you can link an application user in your own
          system to one or more Seam ACS users.

          <br />

          For more information, see

          <a href="/low-level-apis/access-systems/user-management">
            Managing ACS Users
          </a>

          .
        </p>
      </td>
    </tr>

    <tr>
      <td>
        <p>
          <img alt="" />
        </p>

        <p>
          <a href="/api/acs/access_groups/object">
            <code>acs\_access\_group</code>
          </a>
        </p>
      </td>

      <td>
        Some ACSs use access groups as an efficient way to grant sets of
        scheduled entrance access to one or more users.

        <br />

        For more information, see

        <a href="/low-level-apis/access-systems/user-management/assigning-users-to-access-groups">
          Assigning ACS Users to Access Groups
        </a>

        .
      </td>
    </tr>

    <tr>
      <td>
        <p>
          <img alt="" />
        </p>

        <p>
          <a href="/api/acs/credentials/object">
            <code>acs\_credential</code>
          </a>
        </p>
      </td>

      <td>
        A digital means that authorizes a user to access one or more entrances
        at specific days and times. Examples of credentials include RFID cards,
        mobile keys, and PIN codes.

        <br />

        For more information, see
        <a href="/low-level-apis/access-systems/managing-credentials">Managing Credentials</a>.
      </td>
    </tr>

    <tr>
      <td>
        <p>
          <img alt="" />
        </p>

        <p>
          <a href="/api/acs/entrances/object">
            <code>acs\_entrance</code>
          </a>
        </p>
      </td>

      <td>
        The set of entrances, doors, or zones that you want to manage. You
        identify each entrance by the corresponding lock object.

        <br />

        For more information, see

        <a href="/low-level-apis/access-systems/retrieving-entrance-details">
          Retrieving Entrance Details
        </a>

        .
      </td>
    </tr>
  </tbody>
</table>

<Info>
  You configure the access schedules for your ACS users either through access
  groups or credentials, depending on your specific ACS. There is no separate
  schedule resource in the Seam API.
</Info>


# Connect an Access System to Seam
Source: https://docs.seam.co/low-level-apis/access-systems/connect-an-acs-to-seam/index

Learn how to connect your access system to Seam.

You can use [Seam Console](/core-concepts/seam-console/index) or the [Seam API](/api/connect_webviews/object) to connect your access system to Seam. You use a [Connect Webview](/core-concepts/connect-webviews/index) to authorize the connection.

## Connect an Access System Using Seam Console

1. Log in to [Seam Console](https://console.seam.co/).

2. In the upper-left corner, click the workspace switcher and select or create a [workspace](/core-concepts/workspaces/index).

   To connect a real access system to Seam, use a production workspace. To use one of Seam's [virtual access systems](/device-and-system-integration-guides), use a [sandbox workspace](/core-concepts/workspaces/index#sandbox-workspaces).

   <img alt="Use the Seam Console workspace switcher to switch between workspaces and create new workspaces." />

3. In the top navigation pane, click **ACS Systems**.

4. On the **Access Systems** page, click **New Access System**.

   Seam Console displays a Connect Webview that enables you to connect your access system to Seam.

5. In the Connect Webview, follow the prompts to authorize the connection.

   <img alt="Use a Connect Webview to connect your access system to Seam." />

   If you want to connect a virtual access system to a sandbox workspace, use the corresponding [sandbox access system credentials](/developer-tools/test-accounts).

   To connect a real access system, see the [system integration guide](/device-and-system-integration-guides#access-control-systems) for your ACS to learn any brand- or system-specific prerequisites, requirements, and restrictions.

The **Access Systems** page now displays the newly-connected access control system.

***

## Connect an Access System Using the Seam API

First, use the Seam API to [create a Connect Webview](/api/connect_webviews/create). Then, display this Connect Webview to your user. You user completes the Connect Webview to authorize the access system connection to Seam.

For detailed instructions, see [Connect Webview Process](../../../core-concepts/connect-webviews/connect-webview-process).


# Retrieving ACS System Details
Source: https://docs.seam.co/low-level-apis/access-systems/connect-an-acs-to-seam/retrieving-acs-system-details

Learn how to list and get information about your ACS systems.

You can list details for all the ACSs in your [workspace](/core-concepts/workspaces/index) or get these details for a specific ACS. Note that Seam represents the ACS as an [`acs_system`](/api/acs/systems/object) resource. When you want to [create ACS users](/low-level-apis/access-systems/user-management#create-an-acs-user) for your ACS, you must first obtain the ID of the `acs_system` for which you want to create these users.

***

## List ACS Systems

You can [list all `acs_system` resources](/api/acs/systems/list) in your workspace. Note the `acs_system_id` in the response.

**Request:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  await seam.acs.systems.list()
  ```

  ```bash cURL theme={null}
  # Use GET or POST.
  curl -X 'GET' \
    'https://connect.getseam.com/acs/systems/list' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${API_KEY}" \
    -H 'Content-Type: application/json' \
    -d '{}'
  ```

  ```python Python theme={null}
  seam.acs.systems.list()
  ```

  ```ruby Ruby theme={null}
  # Coming soon!
  ```

  ```php PHP theme={null}
  $seam->acs->systems->list();
  ```

  ```csharp C# theme={null}
  seam.SystemsAcs.List();
  ```
</CodeGroup>

**Response:**

<CodeGroup>
  ```json JavaScript theme={null}
  [
    {
      acs_system_id: '11111111-1111-1111-1111-111111111111',
      name: 'Visionline System',
      ...
    },
    ...
  ]
  ```

  ```json cURL theme={null}
  {
    "acs_systems": [
      {
        "acs_system_id": "11111111-1111-1111-1111-111111111111",
        "name": "Visionline System",
        ...
      },
      ...
    ],
    "ok": true
  }
  ```

  ```json Python theme={null}
  [
    AcsSystem(
      acs_system_id='11111111-1111-1111-1111-111111111111',
      name='Visionline System',
      ...
    ),
    ...
  ]
  ```

  ```json Ruby theme={null}
  # Coming soon!
  ```

  ```json PHP theme={null}
  [
    {
      "acs_system_id": "11111111-1111-1111-1111-111111111111",
      "name": "Visionline System",
      ...
    },
    ...
  ]
  ```

  ```json C# theme={null}
  {
    "acs_system_id": "11111111-1111-1111-1111-111111111111",
    "name": "Visionline System",
    ...
  }
  ...
  ```
</CodeGroup>

***

## Get an ACS System

You can [get the details of a specific `acs_system`](/api/acs/systems/get) in your workspace. These details include the `acs_system_id`, date and time at which the `acs_system` was created in Seam, the name and type of the `acs_system`, and so on.

**Request:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  await seam.acs.systems.get({
    acs_system_id: '11111111-1111-1111-1111-111111111111',
  })
  ```

  ```bash cURL theme={null}
  # Use GET or POST.
  curl -X 'GET' \
    'https://connect.getseam.com/acs/systems/get' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${API_KEY}" \
    -H 'Content-Type: application/json' \
    -d '{
    "acs_system_id": "11111111-1111-1111-1111-111111111111"
  }'
  ```

  ```python Python theme={null}
  seam.acs.systems.get(
   acs_system_id="11111111-1111-1111-1111-111111111111"
  )
  ```

  ```ruby Ruby theme={null}
  # Coming soon!
  ```

  ```php PHP theme={null}
  $seam->acs->systems->get(
    acs_system_id: "11111111-1111-1111-1111-111111111111"
  );
  ```

  ```csharp C# theme={null}
  seam.SystemsAcs.Get(
    acsSystemId: "11111111-1111-1111-1111-111111111111"
  );
  ```
</CodeGroup>

**Response:**

<CodeGroup>
  ```json JavaScript theme={null}
  {
    "acs_system_id": "11111111-1111-1111-1111-111111111111",
    "name": "Example Inc",
    "workspace_id": "00000000-0000-0000-0000-000000000000",
    "created_at": "2023-11-30T06:27:14.961Z",
    "external_type": "pti_site",
    "external_type_display_name": "PTI site",
    "connected_account_ids": ["11111111-1111-1111-1111-222222222222"],
    "image_url": "https://connect.getseam.com/assets/images/acs_systems/pti_site.png",
    "image_alt_text": "PTI site Logo"
  }
  ```

  ```json cURL theme={null}
  {
    "acs_system": {
      "acs_system_id": "11111111-1111-1111-1111-111111111111",
      "name": "Example Inc",
      "workspace_id": "00000000-0000-0000-0000-000000000000",
      "created_at": "2023-11-30T06:27:14.961Z",
      "external_type": "pti_site",
      "external_type_display_name": "PTI site",
      "connected_account_ids": ["11111111-1111-1111-1111-222222222222"],
      "image_url": "https://connect.getseam.com/assets/images/acs_systems/pti_site.png",
      "image_alt_text": "PTI site Logo"
    },
    "ok": true
  }
  ```

  ```json Python theme={null}
  AcsSystem(
    acs_system_id='11111111-1111-1111-1111-111111111111',
    name='Example Inc',
    workspace_id='00000000-0000-0000-0000-000000000000',
    created_at='2023-11-30T06:27:14.961Z',
    external_type='pti_site',
    external_type_display_name='PTI site",
    connected_account_ids=[
      '11111111-1111-1111-1111-222222222222'
    ],
    image_url='https://connect.getseam.com/assets/images/acs_systems/pti_site.png',
    image_alt_text='PTI site Logo'
  )
  ```

  ```json Ruby theme={null}
  # Coming soon!
  ```

  ```json PHP theme={null}
  {
    "acs_system_id": "11111111-1111-1111-1111-111111111111",
    "name": "Example Inc",
    "workspace_id": "00000000-0000-0000-0000-000000000000",
    "created_at": "2023-11-30T06:27:14.961Z",
    "external_type": "pti_site",
    "external_type_display_name": "PTI site",
    "connected_account_ids": ["11111111-1111-1111-1111-222222222222"],
    "image_url": "https://connect.getseam.com/assets/images/acs_systems/pti_site.png",
    "image_alt_text": "PTI site Logo"
  }
  ```

  ```json C# theme={null}
  {
    "acs_system_id": "11111111-1111-1111-1111-111111111111",
    "name": "Example Inc",
    "workspace_id": "00000000-0000-0000-0000-000000000000",
    "created_at": "2023-11-30T06:27:14.961Z",
    "external_type": "pti_site",
    "external_type_display_name": "PTI site",
    "connected_account_ids": ["11111111-1111-1111-1111-222222222222"],
    "image_url": "https://connect.getseam.com/assets/images/acs_systems/pti_site.png",
    "image_alt_text": "PTI site Logo"
  }
  ```
</CodeGroup>


# Understanding Access Control System Differences
Source: https://docs.seam.co/low-level-apis/access-systems/connect-an-acs-to-seam/understanding-access-control-system-differences

Seam provides the flexibility to support various ACSs, including manufacturer-specific differences.

Seam's universal API provides the flexibility to manage a variety of [ACSs](/low-level-apis/access-systems/index). Variations among ACSs include the methods that you use to assign access permissions to users. For example, some ACSs grant scheduled access to [entrances](../retrieving-entrance-details) through configured [access groups](../user-management/assigning-users-to-access-groups), while others specify entrance permissions and schedules as properties of [credentials](../managing-credentials). Other variations include the following:

* Whether an ACS is cloud-based or on-premises
* The specific licenses, if any, that each ACS manufacturer requires you to purchase
* The manufacturer-specific ACS properties and metadata that you must configure to create and assign credentials to ACS users

To understand the manufacturer-specific nuances of your ACS, see the relevant [system integration guide](/device-and-system-integration-guides#access-control-systems).

***

## Access Control System Installation Variations

Seam supports connecting to ACSs that are either cloud-based or on-premises.

Cloud-based ACSs are hosted on the internet and are accessible by Seam over a secure connection. This type of ACS provides the benefits and ease of remote management. In addition, you can monitor real-time data and analytics.

On-premises ACSs can also be connected to the internet but are typically protected by a firewall. To integrate with these systems, Seam requires the [Seam Bridge](/capability-guides/seam-bridge), an application installed on a local computer. Once installed, the [Seam Bridge](/capability-guides/seam-bridge) acts as a secure intermediary, handling network requests between Seam and the on-premises network, and enables secure communication through the firewall.

For detailed information about installing the Seam Bridge and connecting an on-premises ACS to Seam, see [Seam Bridge](/capability-guides/seam-bridge).

***

## Access Permission Assignment Variations

This section describes various ways in which ACSs handle assigning access permissions to users.

### Access Group-Based Access Control Systems

Access group-based ACSs use access groups as an efficient way to assign access permissions to [ACS users](../../../low-level-apis/access-systems/user-management). Each access group contains a list of entrances and the corresponding access schedule. Seam syncs all the access group and entrance information from the ACS.

To assign access permissions in an access group-based ACS, you add ACS users to the access groups. Then, you create credentials to specify the access mechanisms—such as key cards, PIN codes, or mobile keys—and assign these credentials to the ACS users.

<img alt="Seam resource relationships for an access group-based ACS" />

The following process describes the configuration steps for your application to grant access in an access group-based ACS:

1. Connect the ACS system.\
   When the ACS connects to Seam, Seam automatically creates the `acs_system`. Seam also syncs the entrances and access groups from the connected ACS as `acs_entrance` and `acs_access_group` resources.\
   Note that because Seam automatically syncs these entrance and access group resources from the ACS, you cannot create, edit, or delete them using the Seam API.
2. Create ACS users.\
   Your application creates an `acs_user` for each user within this ACS. Each `acs_user` is configured with a set of attributes, such their name, email address, and phone number, as applicable.\
   If you need to grant a single application user access to multiple ACSs—for example, if an application user needs access to multiple buildings, each of which uses a separate ACS, or if a single building has different ACSs for different floors—you can use Seam [user identities](/api/user_identities/object) to link `acs_user`s in different `acs_system`s.
3. Add ACS users to access groups.\
   Your application [adds](/low-level-apis/access-systems/user-management/assigning-users-to-access-groups#add-an-acs-user-to-an-access-group) each `acs_user` to an `acs_access_group`. Note that the access group defines the entrances and access schedules for all the ACS users in this access group.
4. Create credentials.\
   Your application creates `acs_credential`s with the following attributes:

   * ID of the `acs_user` to associate with this credential
   * Access method for the credential, such as `code`, `card`, or `mobile_key`

   Depending on the access method and specific ACS, your application can also configure additional credential properties. For more information about manufacturer-specific variations, see the [system integration guide](/device-and-system-integration-guides#access-control-systems) for your ACS.

You can also perform other management actions, as needed, such as [adding ACS users to](../user-management/assigning-users-to-access-groups#add-an-acs-user-to-an-access-group) and [removing ACS users from access groups](../user-management/assigning-users-to-access-groups#remove-an-acs-user-from-an-access-group), [assigning](/low-level-apis/access-systems/managing-credentials/assigning-credentials-to-users#assign-a-credential-to-an-acs-user) and [unassigning](/low-level-apis/access-systems/managing-credentials/assigning-credentials-to-users#unassign-a-credential-from-an-acs-user) existing credentials, [suspending](../../../low-level-apis/access-systems/user-management/suspending-and-unsuspending-users#suspend-an-acs-user) and [unsuspending](../../../low-level-apis/access-systems/user-management/suspending-and-unsuspending-users#unsuspend-an-acs-user) ACS users, [updating ACS users](/low-level-apis/access-systems/user-management#update-an-acs-user) and [credentials](/api/acs/credentials/update), and [deleting ACS users](/low-level-apis/access-systems/user-management#delete-an-acs-user) and [credentials](../managing-credentials#delete-a-credential).

### Credential-Based Access Control Systems

In a credential-based ACS, the [`acs_credential`](/api/acs/credentials/object) resource contains the list of entrances to which the credential grants access. The `acs_credential` also contains the schedule that specifies when this access is valid. You specify each schedule by configuring a `starts_at` and `ends_at` date and time.

<img alt="Seam resource relationships for a credential-based ACS" />

The following process describes the configuration steps for your application to grant access in a credential-based ACS:

1. Connect the ACS system.\
   When the ACS connects to Seam, Seam automatically creates the [`acs_system`](/api/acs/systems/object). Seam also syncs the entrances from the connected ACS as `acs_entrance` resources. Note that because Seam automatically syncs these entrance resources from the ACS, you cannot create, edit, or delete them using the Seam API.
2. Create ACS users.\
   Your application [creates](/low-level-apis/access-systems/user-management#create-an-acs-user) an [`acs_user`](/api/acs/users/object) for each user within this ACS. Each `acs_user` is configured with a set of attributes, such their name, email address, and phone number, as applicable.\
   If you need to grant a single application user access to multiple ACSs—for example, if an application user needs access to multiple buildings, each of which uses a separate ACS—you can use Seam [user identities](/api/user_identities/object) to link `acs_user`s in different `acs_system`s.
3. Create credentials.\
   Your application [creates](/low-level-apis/access-systems/managing-credentials#create-a-credential-for-an-acs-user) `acs_credential`s with the following attributes:

   * ID of the `acs_user` to associate with this credential
   * Access method for the credential, such as `code`, `card`, or `mobile_key`
   * Set of entrances to which this credential grants access
   * Start and end date and time during which this credential grants access

   Depending on the access method and specific ACS, your application can also configure additional credential properties. For more information about manufacturer-specific variations, see the [system integration guide](/device-and-system-integration-guides#access-control-systems) for your ACS.

You can also perform other management actions, as needed, such as [assigning](/low-level-apis/access-systems/managing-credentials/assigning-credentials-to-users#assign-a-credential-to-an-acs-user) and [unassigning](/low-level-apis/access-systems/managing-credentials/assigning-credentials-to-users#unassign-a-credential-from-an-acs-user) existing credentials, [suspending](../../../low-level-apis/access-systems/user-management/suspending-and-unsuspending-users#suspend-an-acs-user) and [unsuspending](../../../low-level-apis/access-systems/user-management/suspending-and-unsuspending-users#unsuspend-an-acs-user) ACS users, [updating ACS users](/low-level-apis/access-systems/user-management#update-an-acs-user) and [credentials](/api/acs/credentials/update), and [deleting ACS users](/low-level-apis/access-systems/user-management#delete-an-acs-user) and [credentials](../managing-credentials#delete-a-credential).

***

## Next Steps

To learn about the manufacturer-specific variations for ACSs, see the corresponding [system integration guides](/device-and-system-integration-guides#access-control-systems).


# Access Control Systems
Source: https://docs.seam.co/low-level-apis/access-systems/index

Learn about managing access control systems that enable you to control users' access to physical spaces, using credentials.

<Warning>
  This is a low-level API. For granting access through your access control
  system, use [Access Grants](/use-cases/granting-access/index)—the default and
  recommended way to grant access to any physical space. We don't recommend
  building on the ACS API directly unless you've discussed your use case with
  the Seam team at [support@seam.co](mailto:support@seam.co).
</Warning>

<img
  alt="With Seam, you can manage your access control system, granting users
access to multiple entrances using credentials."
/>

Use the Seam access control system (ACS) API to grant and manage access to apartment buildings, hotels, commercial offices, warehouses, special-purpose facilities, and much more. Seam integrates with multiple ACS systems and brands, and the Seam API standardizes key functions.

***

## What Is an Access Control System?

Access control systems centralize access authorization for buildings, which means that you can use a single system to grant users access to one or more entrances. An access control system manages the following elements:

* Who has access
* The entrances to which users have access
* The access schedule for each user and entrance
* The access mechanism—PIN codes, mobile keys, or plastic cards—for each access grant

***

## Managing Your ACS with Seam

Seam enables you to manage your ACS in a logical, efficient manner.

1. Create ACS users.

2. Configure access for your ACS users.

   For each user, specify the entrances to which the user has access and the schedule for this access.

3. Define credentials, which are the digital means of granting access, such as PIN codes, mobile keys, and plastic (RFID) cards.\
   If you are developing a mobile app to provide access for your ACS users, you can also use [Seam's iOS and Android SDKs](/mobile-sdks) that pair with the Seam API to create and manage mobile keys.

<img
  alt="Seam provides the flexibility to grant access to ACS users, using the
access methods that best suit your users' needs."
/>

### Seam's API Handles ACS Differences

Seam's universal API provides the flexibility to manage a variety of [access control systems](../../low-level-apis/access-systems/connect-an-acs-to-seam/understanding-access-control-system-differences), each of which may have manufacturer-specific differences. For example, depending on your ACS, you configure access permissions by [assigning ACS users to access groups](../../low-level-apis/access-systems/connect-an-acs-to-seam/understanding-access-control-system-differences#access-group-based-access-control-systems) or by [specifying access permissions for each ACS user or credential](../../low-level-apis/access-systems/connect-an-acs-to-seam/understanding-access-control-system-differences#credential-based-access-control-systems).

For details specific to your access control system, see the [system integration guide](/device-and-system-integration-guides#access-control-systems) for your ACS.

***

## **Getting Started**

Create your first credentials! See the [ACS Quick Starts](/low-level-apis/access-systems/acs-quick-starts/index).

<CardGroup>
  <Card title="Create your first PIN code credential. →" href="/low-level-apis/access-systems/acs-quick-starts/pin-code-quick-start" />

  <Card title="Create your first encodable key card credential. →" href="/low-level-apis/access-systems/acs-quick-starts/encodable-key-card-quick-start" />

  <Card title="Create your first mobile key credential. →" href="/low-level-apis/access-systems/acs-quick-starts/mobile-key-quick-start" />
</CardGroup>

***

## Learn More

Find out more about using Seam to manage access control system resources. See the following guides:

1. Connect your ACS to Seam.
   * [Connect an ACS to Seam](/low-level-apis/access-systems/connect-an-acs-to-seam/index)
2. Learn about ACS concepts.
   * [Access Control System Resources](../../low-level-apis/access-systems/connect-an-acs-to-seam/access-control-system-resources)
   * [Understanding ACS Differences](../../low-level-apis/access-systems/connect-an-acs-to-seam/understanding-access-control-system-differences)
3. Get your ACS system ID.
   * [Retrieving ACS System Details](../../low-level-apis/access-systems/connect-an-acs-to-seam/retrieving-acs-system-details)
4. Create ACS users.
   * [Managing ACS Users](/low-level-apis/access-systems/user-management)
5. For relevant access control systems, assign ACS users to access groups.
   * [Assigning ACS Users to Access Groups](../../low-level-apis/access-systems/user-management/assigning-users-to-access-groups)
6. Learn about available entrances.
   * [Retrieving Entrance Details](../../low-level-apis/access-systems/retrieving-entrance-details)
7. Create credentials for ACS users.
   * [Managing Credentials](../../low-level-apis/access-systems/managing-credentials)
8. See the Seam [Access Control Systems API reference](/api/acs/object).


# Managing Credentials
Source: https://docs.seam.co/low-level-apis/access-systems/managing-credentials

Learn how to manage credentials and assign them to users.

<Warning>
  This is a low-level API. For granting a person access, use [Access
  Grants](/use-cases/granting-access/index)—the default and recommended way to
  grant access to any physical space. We don't recommend building on the ACS
  credential API directly unless you specifically need low-level control over
  individual credentials (or have discussed your use case with the Seam team at
  [support@seam.co](mailto:support@seam.co)).
</Warning>

An ACS generally uses digital means of access to authorize an [ACS user](../../low-level-apis/access-systems/user-management) trying to get through a specific entrance. Examples of credentials include plastic key cards, mobile keys, biometric identifiers, and PIN codes. The electronic nature of these credentials, as well as the fact that access is centralized, enables both the rapid provisioning and rescinding of access and the ability to compile access audit logs.

<img alt="Examples of ACS user credentials" />

This guide provides instructions for creating and deleting various types of credentials.

<Info>
  You can assign a credential to an ACS user when you create the credential. You
  can also [assign an existing credential to an ACS
  user](/low-level-apis/access-systems/managing-credentials/assigning-credentials-to-users#assign-a-credential-to-an-acs-user).
  Further, you can [unassign a credential from an ACS
  user](/low-level-apis/access-systems/managing-credentials/assigning-credentials-to-users#unassign-a-credential-from-an-acs-user)
  without deleting the credential.
</Info>

***

## Create a Credential for an ACS User

To [create a credential for an ACS user](/api/acs/credentials/create), provide the `acs_user_id` and the desired `access_method`. Seam supports the following access methods:

* `code` for a PIN code-based credential
* `card` for a plastic key card-based credential
* `mobile_key` for a [Seam mobile key](/capability-guides/mobile-access/issuing-mobile-credentials-from-an-access-control-system#what-are-multi-phone-sync-credentials).

Depending on the ACS and the type of credential you are issuing, you can also specify the following properties for the new credential:

* PIN code.
* Start and end time frame for the validity of the credential.
* Whether the credential is a multi-phone sync credential.\
  When creating a Seam mobile key, make sure to issue a multi-phone sync credential by setting `is_multi_phone_sync_credential` to `true`.
* Manufacturer-specific data.

<Info>
  Make sure to note any manufacturer-specific metadata and restrictions. For
  details, see the applicable [device or system integration
  guide](/device-and-system-integration-guides).
</Info>

The response includes the `acs_credential_id` of the newly-created credential, the `acs_user_id` associated with the credential, and additional attributes of the credential.

<Info>
  If you are creating card-based credentials, and your ACS requires card
  encoding, see also [Creating and Encoding Card-based
  Credentials](/low-level-apis/access-systems/working-with-card-encoders-and-scanners/creating-and-encoding-card-based-credentials).
</Info>

***

### Create a PIN Code-based Credential

**Request:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  await seam.acs.credentials.create({
    acs_user_id: '33333333-3333-3333-3333-333333333333',
    access_method: 'code',
    code: '824759',
  })
  ```

  ```bash cURL theme={null}
  curl -X 'POST' \
    'https://connect.getseam.com/acs/credentials/create' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${API_KEY}" \
    -H 'Content-Type: application/json' \
    -d '{
    "acs_user_id": "33333333-3333-3333-3333-333333333333",
    "access_method": "code",
    "code": "824759"
  }'
  ```

  ```python Python theme={null}
  seam.acs.credentials.create(
    acs_user_id="33333333-3333-3333-3333-333333333333",
    access_method="code",
    code="824759"
  )
  ```

  ```ruby Ruby theme={null}
  # Coming soon!
  ```

  ```php PHP theme={null}
  $seam->acs->credentials->create(
    acs_user_id: "33333333-3333-3333-3333-333333333333",
    access_method: "code",
    code: "824759"
  );
  ```

  ```csharp C# theme={null}
  seam.CredentialsAcs.Create(
    acsUserId: "33333333-3333-3333-3333-333333333333",
    accessMethod: "code",
    code: "824759"
  );
  ```
</CodeGroup>

**Response:**

<CodeGroup>
  ```json JavaScript theme={null}
  {
    acs_credential_id: '66666666-6666-6666-6666-666666666666',
    acs_user_id: '33333333-3333-3333-3333-333333333333',
    code: '824759',
    access_method: 'code',
    ...
  }
  ```

  ```json cURL theme={null}
  {
    "acs_credential": {
      "acs_credential_id": "66666666-6666-6666-6666-666666666666",
      "acs_user_id": "33333333-3333-3333-3333-333333333333",
      "code": "824759",
      "access_method": "code",
      ...
    },
    "ok": true
  }
  ```

  ```json Python theme={null}
  AcsCredential(
    acs_credential_id='66666666-6666-6666-6666-666666666666',
    acs_user_id='33333333-3333-3333-3333-333333333333',
    code='824759',
    access_method='code',
    ...
  )
  ```

  ```json Ruby theme={null}
  # Coming soon!
  ```

  ```json PHP theme={null}
  {
    "acs_credential_id": "66666666-6666-6666-6666-666666666666",
    "acs_user_id": "33333333-3333-3333-3333-333333333333",
    "code": "824759",
    "access_method": "code",
    ...
  }
  ```

  ```json C# theme={null}
  {
    "acs_credential_id": "66666666-6666-6666-6666-666666666666",
    "acs_user_id": "33333333-3333-3333-3333-333333333333",
    "code": "824759",
    "access_method": "code",
    ...
  }
  ```
</CodeGroup>

***

### Create a Card-based Credential

To create a plastic key card-based credential, set the `access_method` to `card`. Once you've created a credential, some access control systems require you to encode the card with the credential. To learn whether your ACS requires card encoding, see the [system integration guide](/device-and-system-integration-guides#access-control-systems) for your ACS. For card encoding instructions, see [Creating and Encoding Card-based Credentials](/low-level-apis/access-systems/working-with-card-encoders-and-scanners/creating-and-encoding-card-based-credentials).

**Request:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  await seam.acs.credentials.create({
    acs_user_id: '33333333-3333-3333-3333-333333333333',
    access_method: 'card',
    code: '123456',
  })
  ```

  ```bash cURL theme={null}
  curl -X 'POST' \
    'https://connect.getseam.com/acs/credentials/create' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${API_KEY}" \
    -H 'Content-Type: application/json' \
    -d '{
    "acs_user_id": "33333333-3333-3333-3333-333333333333",
    "access_method": "card",
    "code": "123456"
  }'
  ```

  ```python Python theme={null}
  seam.acs.credentials.create(
    acs_user_id="33333333-3333-3333-3333-333333333333",
    access_method="card",
    code="123456"
  )
  ```

  ```ruby Ruby theme={null}
  # Coming soon!
  ```

  ```php PHP theme={null}
  $seam->acs->credentials->create(
    acs_user_id: "33333333-3333-3333-3333-333333333333",
    access_method: "card",
    code: "123456"
  );
  ```

  ```csharp C# theme={null}
  seam.CredentialsAcs.Create(
    acsUserId: "33333333-3333-3333-3333-333333333333",
    accessMethod: "card",
    code: "123456"
  );
  ```
</CodeGroup>

**Response:**

<CodeGroup>
  ```json JavaScript theme={null}
  {
    acs_credential_id: '77777777-7777-7777-7777-777777777777',
    acs_user_id: '33333333-3333-3333-3333-333333333333',
    access_method: 'card',
    ...
  }
  ```

  ```json cURL theme={null}
  {
    "acs_credential": {
      "acs_credential_id": "77777777-7777-7777-7777-777777777777",
      "acs_user_id": "33333333-3333-3333-3333-333333333333",
      "access_method": "card",
      ...
    },
    "ok": true
  }
  ```

  ```json Python theme={null}
  AcsCredential(
    acs_credential_id='77777777-7777-7777-7777-777777777777',
    acs_user_id='33333333-3333-3333-3333-333333333333',
    access_method='card',
    ...
  )
  ```

  ```json Ruby theme={null}
  # Coming soon!
  ```

  ```json PHP theme={null}
  {
    "acs_credential_id": "77777777-7777-7777-7777-777777777777",
    "acs_user_id": "33333333-3333-3333-3333-333333333333",
    "access_method": "card",
    ...
  }
  ```

  ```json C# theme={null}
  {
    "acs_credential_id": "77777777-7777-7777-7777-777777777777",
    "acs_user_id": "33333333-3333-3333-3333-333333333333",
    "access_method": "card",
    ...
  }
  ```
</CodeGroup>

***

### Create a Seam Mobile Key

Depending on the ACS for which you want to create a credential, you may also need to include system-specific metadata. See the [system integration guide](/device-and-system-integration-guides#access-control-systems) for your ACS. For more information about mobile access and issuing mobile credentials, see [Mobile Access](/capability-guides/mobile-access/index) and [Issuing Mobile Credentials from an Access Control System](/capability-guides/mobile-access/issuing-mobile-credentials-from-an-access-control-system).

**Request:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  await seam.acs.credentials.create({
    acs_user_id: "33333333-3333-3333-3333-333333333333",
    allowed_acs_entrance_ids: [
      "55555555-5555-5555-5555-555555555555",
      "55555555-5555-5555-5555-000000000000"
    ],
    credential_manager_acs_system_id: "88888888-8888-8888-8888-888888888888",
    access_method: "mobile_key",
    is_multi_phone_sync_credential: true,
    starts_at: "2024-03-01T10:40:00Z",
    ends_at: "2024-03-04T10:40:00Z",
    ...
  });
  ```

  ```bash cURL theme={null}
  curl -X 'POST' \
    'https://connect.getseam.com/acs/credentials/create' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${API_KEY}" \
    -H 'Content-Type: application/json' \
    -d '{
    "acs_user_id": "33333333-3333-3333-3333-333333333333",
    "allowed_acs_entrance_ids": [
      "55555555-5555-5555-5555-555555555555",
      "55555555-5555-5555-5555-000000000000"
    ],
    "credential_manager_acs_system_id": "88888888-8888-8888-8888-888888888888",
    "access_method": "mobile_key",
    "is_multi_phone_sync_credential": true,
    "starts_at": "2024-03-01T10:40:00Z",
    "ends_at": "2024-03-04T10:40:00Z",
    ...
  }'
  ```

  ```python Python theme={null}
  seam.acs.credentials.create(
    acs_user_id="33333333-3333-3333-3333-333333333333",
    allowed_acs_entrance_ids=[
      "55555555-5555-5555-5555-555555555555",
      "55555555-5555-5555-5555-000000000000"
    ],
    credential_manager_acs_system_id="88888888-8888-8888-8888-888888888888",
    access_method="mobile_key",
    is_multi_phone_sync_credential=True,
    starts_at="2024-03-01T10:40:00Z",
    ends_at="2024-03-04T10:40:00Z",
    ...
  )
  ```

  ```ruby Ruby theme={null}
  # Coming soon!
  ```

  ```php PHP theme={null}
  $seam->acs->credentials->create(
    acs_user_id: "33333333-3333-3333-3333-333333333333",
    allowed_acs_entrance_ids: [
      "55555555-5555-5555-5555-555555555555",
      "55555555-5555-5555-5555-000000000000"
    ],
    credential_manager_acs_system_id: "88888888-8888-8888-8888-888888888888",
    access_method: "mobile_key",
    is_multi_phone_sync_credential: true,
    starts_at: "2024-03-01T10:40:00Z",
    ends_at: "2024-03-04T10:40:00Z",
    ...
  );
  ```

  ```csharp C# theme={null}
  seam.CredentialsAcs.Create(
    acsUserId: "33333333-3333-3333-3333-333333333333",
    allowedAcsEntranceIds: new List<string>
      {
        "55555555-5555-5555-5555-555555555555",
        "55555555-5555-5555-5555-000000000000"
      },
    credentialManagerAcsSystemId: "88888888-8888-8888-8888-888888888888",
    accessMethod: "mobile_key",
    isMultiPhoneSyncCredential: true,
    startsAt: "2024-03-01T10:40:00Z",
    endsAt: "2024-03-04T10:40:00Z",
    ...
  );
  ```
</CodeGroup>

**Response:**

<CodeGroup>
  ```json JavaScript theme={null}
  {
    acs_credential_id: '99999999-9999-9999-9999-999999999999',
    acs_user_id: '33333333-3333-3333-3333-333333333333',
    access_method: 'mobile_key',
    is_multi_phone_sync_credential: true,
    ...
  }
  ```

  ```json cURL theme={null}
  {
    "acs_credential": {
      "acs_credential_id": "99999999-9999-9999-9999-999999999999",
      "acs_user_id": "33333333-3333-3333-3333-333333333333",
      "access_method": "mobile_key",
      "is_multi_phone_sync_credential": true,
      ...
    },
    "ok": true
  }
  ```

  ```json Python theme={null}
  AcsCredential(
    acs_credential_id='99999999-9999-9999-9999-999999999999',
    acs_user_id='33333333-3333-3333-3333-333333333333',
    access_method='mobile_key',
    is_multi_phone_sync_credential=True,
    ...
  )
  ```

  ```json Ruby theme={null}
  # Coming soon!
  ```

  ```json PHP theme={null}
  {
    "acs_credential_id": "99999999-9999-9999-9999-999999999999",
    "acs_user_id": "33333333-3333-3333-3333-333333333333",
    "access_method": "mobile_key",
    "is_multi_phone_sync_credential": true,
    ...
  }
  ```

  ```json C# theme={null}
  {
    "acs_credential_id": "99999999-9999-9999-9999-999999999999",
    "acs_user_id": "33333333-3333-3333-3333-333333333333",
    "access_method": "mobile_key",
    "is_multi_phone_sync_credential": true,
    ...
  }
  ```
</CodeGroup>

***

## List Credentials

You can [list all ACS credentials](/api/acs/credentials/list) for a specific [ACS user](../../low-level-apis/access-systems/user-management) or [user identity](/capability-guides/mobile-access/managing-mobile-app-user-accounts-with-user-identities#what-is-a-user-identity). You can also [list all credentials for an ACS system](/api/acs/credentials/list).

### List Credentials by ACS User

To [list all ACS credentials](/api/acs/credentials/list) for a specific [ACS user](../../low-level-apis/access-systems/user-management), provide the `acs_user_id`.

**Request:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  await seam.acs.credentials.list({
    acs_user_id: '33333333-3333-3333-3333-333333333333',
  })
  ```

  ```bash cURL theme={null}
  # Use GET or POST.
  curl -X 'GET' \
    'https://connect.getseam.com/acs/credentials/list' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${API_KEY}" \
    -H 'Content-Type: application/json' \
    -d '{
    "acs_user_id": "33333333-3333-3333-3333-333333333333"
  }'
  ```

  ```python Python theme={null}
  seam.acs.credentials.list(
    acs_user_id="33333333-3333-3333-3333-333333333333"
  )
  ```

  ```ruby Ruby theme={null}
  # Coming soon!
  ```

  ```php PHP theme={null}
  $seam->acs->credentials->list(
    acs_user_id: "33333333-3333-3333-3333-333333333333"
  );
  ```

  ```csharp C# theme={null}
  seam.CredentialsAcs.List(
    acsUserId: "33333333-3333-3333-3333-333333333333"
  );
  ```
</CodeGroup>

**Response:**

<CodeGroup>
  ```json JavaScript theme={null}
  [
    {
      acs_credential_id: '99999999-9999-9999-9999-999999999999',
      acs_user_id: '33333333-3333-3333-3333-333333333333',
      ...
    },
    ...
  ]
  ```

  ```json cURL theme={null}
  {
    "acs_credentials": [
      {
        "acs_credential_id": "99999999-9999-9999-9999-999999999999",
        "acs_user_id": "33333333-3333-3333-3333-333333333333",
        ...
      }
      ...
    ],
    "ok": true
  }
  ```

  ```json Python theme={null}
  [
    AcsCredential(
      acs_credential_id='99999999-9999-9999-9999-999999999999',
      acs_user_id='33333333-3333-3333-3333-333333333333',
      ...
    ),
    ...
  ]
  ```

  ```json Ruby theme={null}
  # Coming soon!
  ```

  ```json PHP theme={null}
  [
    {
      "acs_credential_id": "99999999-9999-9999-9999-999999999999",
      "acs_user_id": "33333333-3333-3333-3333-333333333333",
      ...
    },
    ...
  ]
  ```

  ```json C# theme={null}
  {
    "acs_credential_id": "99999999-9999-9999-9999-999999999999",
    "acs_user_id": "33333333-3333-3333-3333-333333333333",
    ...
  }
  ...
  ```
</CodeGroup>

### List Credentials by User Identity

To [list all ACS credentials](/api/acs/credentials/list) for a specific [user identity](/capability-guides/mobile-access/managing-mobile-app-user-accounts-with-user-identities#what-is-a-user-identity), provide the `user_identity_id`.

**Request:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  await seam.acs.credentials.list({
    user_identity_id: '22222222-2222-2222-2222-222222222222',
  })
  ```

  ```bash cURL theme={null}
  # Use GET or POST.
  curl -X 'GET' \
    'https://connect.getseam.com/acs/credentials/list' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${API_KEY}" \
    -H 'Content-Type: application/json' \
    -d '{
    "user_identity_id": "22222222-2222-2222-2222-222222222222"
  }'
  ```

  ```python Python theme={null}
  seam.acs.credentials.list(
    user_identity_id="22222222-2222-2222-2222-222222222222"
  )
  ```

  ```ruby Ruby theme={null}
  # Coming soon!
  ```

  ```php PHP theme={null}
  $seam->acs->credentials->list(
    user_identity_id: "22222222-2222-2222-2222-222222222222"
  );
  ```

  ```csharp C# theme={null}
  seam.CredentialsAcs.List(
    userIdentityId: "22222222-2222-2222-2222-222222222222"
  );
  ```
</CodeGroup>

**Response:**

<CodeGroup>
  ```json JavaScript theme={null}
  [
    {
      acs_credential_id: '99999999-9999-9999-9999-999999999999',
      acs_user_id: '33333333-3333-3333-3333-333333333333',
      ...
    },
    ...
  ]
  ```

  ```json cURL theme={null}
  {
    "acs_credentials": [
      {
        "acs_credential_id": "99999999-9999-9999-9999-999999999999",
        "acs_user_id": "33333333-3333-3333-3333-333333333333",
        ...
      }
      ...
    ],
    "ok": true
  }
  ```

  ```json Python theme={null}
  [
    AcsCredential(
      acs_credential_id='99999999-9999-9999-9999-999999999999',
      acs_user_id='33333333-3333-3333-3333-333333333333',
      ...
    ),
    ...
  ]
  ```

  ```json Ruby theme={null}
  # Coming soon!
  ```

  ```json PHP theme={null}
  [
    {
      "acs_credential_id": "99999999-9999-9999-9999-999999999999",
      "acs_user_id": "33333333-3333-3333-3333-333333333333",
      ...
    },
    ...
  ]
  ```

  ```json C# theme={null}
  {
    "acs_credential_id": "99999999-9999-9999-9999-999999999999",
    "acs_user_id": "33333333-3333-3333-3333-333333333333",
    ...
  }
  ...
  ```
</CodeGroup>

***

## Get a Credential

To [get a credential](/api/acs/credentials/get), provide the `acs_credential_id` of the credential that you want to retrieve. These details include the user associated with the credential, the access method, the schedule for the credential, if applicable, and so on.

**Request:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  await seam.acs.credentials.get({
    acs_credential_id: '66666666-6666-6666-6666-666666666666',
  })
  ```

  ```bash cURL theme={null}
  curl -X 'POST' \
    'https://connect.getseam.com/acs/credentials/get' \
    -H "Authorization: Bearer ${API_KEY}" \
    -H 'Content-Type: application/json' \
    -d '{
    "acs_credential_id": "66666666-6666-6666-6666-666666666666"
  }'
  ```

  ```python Python theme={null}
  seam.acs.credentials.get(
    acs_credential_id="66666666-6666-6666-6666-666666666666"
  )
  ```

  ```ruby Ruby theme={null}
  # Coming soon!
  ```

  ```php PHP theme={null}
  $seam->acs->credentials->get(
    acs_credential_id: "66666666-6666-6666-6666-66666666"
  );
  ```

  ```csharp C# theme={null}
  seam.CredentialsAcs.Get(
    acsCredentialId: "66666666-6666-6666-6666-66666666"
  );
  ```
</CodeGroup>

**Response:**

<CodeGroup>
  ```json JavaScript theme={null}
  {
    acs_credential_id: '99999999-9999-9999-9999-999999999999',
    acs_user_id: '33333333-3333-3333-3333-333333333333',
    acs_system_id: '11111111-1111-1111-1111-111111111111',
    access_method: 'mobile_key',
    ...
  }
  ```

  ```json cURL theme={null}
  {
    "acs_credential": {
      "acs_credential_id": "99999999-9999-9999-9999-999999999999",
      "acs_user_id": "33333333-3333-3333-3333-333333333333",
      "acs_system_id": "11111111-1111-1111-1111-111111111111",
      "access_method": "mobile_key",
      ...
    },
    "ok": true
  }
  ```

  ```json Python theme={null}
  AcsCredential(
    acs_credential_id='99999999-9999-9999-9999-999999999999',
    acs_user_id='33333333-3333-3333-3333-333333333333',
    acs_system_id='11111111-1111-1111-1111-111111111111',
    access_method='mobile_key',
    ...
  )
  ```

  ```json Ruby theme={null}
  # Coming soon!
  ```

  ```json PHP theme={null}
  {
    "acs_credential_id": "99999999-9999-9999-9999-999999999999",
    "acs_user_id": "33333333-3333-3333-3333-333333333333",
    "acs_system_id": "11111111-1111-1111-1111-111111111111",
    "access_method": "mobile_key",
    ...
  }
  ```

  ```json C# theme={null}
  {
    "acs_credential_id": "99999999-9999-9999-9999-999999999999",
    "acs_user_id": "33333333-3333-3333-3333-333333333333",
    "acs_system_id": "11111111-1111-1111-1111-111111111111",
    "access_method": "mobile_key",
    ...
  }
  ```
</CodeGroup>

***

## Delete a Credential

To [delete a credential](/api/acs/credentials/delete), provide the `acs_credential_id`.

**Request:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  await seam.acs.credentials.delete({
    acs_credential_id: '66666666-6666-6666-6666-666666666666',
  })
  ```

  ```bash cURL theme={null}
  curl -X 'POST' \
    'https://connect.getseam.com/acs/credentials/delete' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${API_KEY}" \
    -H 'Content-Type: application/json' \
    -d '{
    "acs_credential_id": "66666666-6666-6666-6666-666666666666"
  }'
  ```

  ```python Python theme={null}
  seam.acs.credentials.delete(
    acs_credential_id="66666666-6666-6666-6666-666666666666"
  )
  ```

  ```ruby Ruby theme={null}
  # Coming soon!
  ```

  ```php PHP theme={null}
  $seam->acs->credentials->delete(
    acs_credential_id: "66666666-6666-6666-6666-666666666666"
  );
  ```

  ```csharp C# theme={null}
  seam.CredentialsAcs.Delete(
    acsCredentialId: "66666666-6666-6666-6666-666666666666"
  );
  ```
</CodeGroup>

**Response:**

<CodeGroup>
  ```json JavaScript theme={null}
  void
  ```

  ```json cURL theme={null}
  {
    "ok": true
  }
  ```

  ```json Python theme={null}
  None
  ```

  ```json Ruby theme={null}
  # Coming soon!
  ```

  ```json PHP theme={null}
  void
  ```

  ```json C# theme={null}
  void
  ```
</CodeGroup>


# Assigning Credentials to ACS Users
Source: https://docs.seam.co/low-level-apis/access-systems/managing-credentials/assigning-credentials-to-users

Learn how to assign existing credentials the ACS users and unassign credentials from ACS users.

This guide explains how to assign existing [credentials](./) to [ACS users](../user-management) and unassign credentials from users. Once you assign credentials to ACS users, these users can use the credentials to access areas and resources according to their permissions. When you unassign credentials from ACS users, these users can no longer use these specific credentials to access areas or resources.

***

## Assign a Credential to an ACS User

To [assign a credential to an ACS user](/api/acs/credentials/assign), provide both the `acs_user_id` and the `acs_credential_id`.

**Request:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  await seam.acs.credentials.assign({
    acs_user_id: '33333333-3333-3333-3333-333333333333',
    acs_credential_id: '66666666-6666-6666-6666-666666666666',
  })
  ```

  ```bash cURL theme={null}
  curl -X 'POST' \
    'https://connect.getseam.com/acs/credentials/assign' \
    -H "Authorization: Bearer ${API_KEY}" \
    -H 'Content-Type: application/json' \
    -d '{
    "acs_user_id": "33333333-3333-3333-3333-333333333333",
    "acs_credential_id": "66666666-6666-6666-6666-666666666666"
  }'
  ```

  ```python Python theme={null}
  seam.acs.credentials.assign(
    acs_user_id="33333333-3333-3333-3333-333333333333",
    acs_credential_id="66666666-6666-6666-6666-666666666666"
  )
  ```

  ```ruby Ruby theme={null}
  # Coming soon!
  ```

  ```php PHP theme={null}
  $seam->acs->credentials->assign(
    acs_user_id: "33333333-3333-3333-3333-333333333333",
    acs_credential_id: "66666666-6666-6666-6666-66666666"
  );
  ```

  ```csharp C# theme={null}
  seam.CredentialsAcs.Assign(
    acsUserId: "33333333-3333-3333-3333-333333333333",
    acsCredentialId: "66666666-6666-6666-6666-66666666"
  );
  ```
</CodeGroup>

**Response:**

<CodeGroup>
  ```json JavaScript theme={null}
  {
    "acs_credential_id": "99999999-9999-9999-9999-999999999999",
    "acs_user_id": "33333333-3333-3333-3333-333333333333",
    "display_name": "Multi Phone Sync Credential",
    "code": null,
    "acs_system_id": "11111111-1111-1111-1111-111111111111",
    "access_method": "mobile_key",
    "workspace_id": "00000000-0000-0000-0000-000000000000",
    "created_at": "2024-04-12T03:56:22.396Z",
    "is_multi_phone_sync_credential": true
    // manufacturer-specific metadata
  }
  ```

  ```json cURL theme={null}
  {
    "acs_credential": {
      "acs_credential_id": "99999999-9999-9999-9999-999999999999",
      "acs_user_id": "33333333-3333-3333-3333-333333333333",
      "display_name": "Multi Phone Sync Credential",
      "code": null,
      "acs_system_id": "11111111-1111-1111-1111-111111111111",
      "access_method": "mobile_key",
      "workspace_id": "00000000-0000-0000-0000-000000000000",
      "created_at": "2024-04-12T03:56:22.396Z",
      "is_multi_phone_sync_credential": true,
      # manufacturer-specific metadata
    },
    "ok": true
  }
  ```

  ```json Python theme={null}
  AcsCredential(
    acs_credential_id='99999999-9999-9999-9999-999999999999',
    acs_user_id='33333333-3333-3333-3333-333333333333',
    display_name='Multi Phone Sync Credential',
    code=null,
    acs_system_id='11111111-1111-1111-1111-111111111111',
    access_method='mobile_key',
    workspace_id='00000000-0000-0000-0000-000000000000',
    created_at='2024-04-12T03:56:22.396Z',
    is_multi_phone_sync_credential=True,
    # manufacturer-specific metadata
  )
  ```

  ```json Ruby theme={null}
  # Coming soon!
  ```

  ```json PHP theme={null}
  {
    "acs_credential_id": "99999999-9999-9999-9999-999999999999",
    "acs_user_id": "33333333-3333-3333-3333-333333333333",
    "display_name": "Multi Phone Sync Credential",
    "code": null,
    "acs_system_id": "11111111-1111-1111-1111-111111111111",
    "access_method": "mobile_key",
    "workspace_id": "00000000-0000-0000-0000-000000000000",
    "created_at": "2024-04-12T03:56:22.396Z",
    "is_multi_phone_sync_credential": true
    // manufacturer-specific metadata
  }
  ```

  ```json C# theme={null}
  {
    "acs_credential_id": "99999999-9999-9999-9999-999999999999",
    "acs_user_id": "33333333-3333-3333-3333-333333333333",
    "display_name": "Multi Phone Sync Credential",
    "code": null,
    "acs_system_id": "11111111-1111-1111-1111-111111111111",
    "access_method": "mobile_key",
    "workspace_id": "00000000-0000-0000-0000-000000000000",
    "created_at": "2024-04-12T03:56:22.396Z",
    "is_multi_phone_sync_credential": true
    // manufacturer-specific metadata
  }
  ```
</CodeGroup>

***

## Unassign a Credential from an ACS User

To [unassign a credential from an ACS user](/api/acs/credentials/unassign), provide both the `acs_user_id` and the `acs_credential_id`.

**Request:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  await seam.acs.credentials.unassign({
    acs_user_id: '33333333-3333-3333-3333-333333333333',
    acs_credential_id: '66666666-6666-6666-6666-666666666666',
  })
  ```

  ```bash cURL theme={null}
  curl -X 'POST' \
    'https://connect.getseam.com/acs/credentials/unassign' \
    -H "Authorization: Bearer ${API_KEY}" \
    -H 'Content-Type: application/json' \
    -d '{
    "acs_user_id": "33333333-3333-3333-3333-333333333333",
    "acs_credential_id": "66666666-6666-6666-6666-666666666666"
  }'
  ```

  ```python Python theme={null}
  seam.acs.credentials.unassign(
    acs_user_id="33333333-3333-3333-3333-333333333333",
    acs_credential_id="66666666-6666-6666-6666-666666666666"
  )
  ```

  ```ruby Ruby theme={null}
  # Coming soon!
  ```

  ```php PHP theme={null}
  $seam->acs->credentials->unassign(
    acs_user_id: "33333333-3333-3333-3333-333333333333",
    acs_credential_id: "66666666-6666-6666-6666-66666666"
  );
  ```

  ```csharp C# theme={null}
  seam.CredentialsAcs.Unassign(
    acsUserId: "33333333-3333-3333-3333-333333333333",
    acsCredentialId: "66666666-6666-6666-6666-66666666"
  );
  ```
</CodeGroup>

**Response:**

<CodeGroup>
  ```json JavaScript theme={null}
  {
    "acs_credential_id": "99999999-9999-9999-9999-999999999999",
    "acs_user_id": "33333333-3333-3333-3333-333333333333",
    "display_name": "Multi Phone Sync Credential",
    "code": null,
    "acs_system_id": "11111111-1111-1111-1111-111111111111",
    "access_method": "mobile_key",
    "workspace_id": "00000000-0000-0000-0000-000000000000",
    "created_at": "2024-04-12T03:56:22.396Z",
    "is_multi_phone_sync_credential": true
    // manufacturer-specific metadata
  }
  ```

  ```json cURL theme={null}
  {
    "acs_credential": {
      "acs_credential_id": "99999999-9999-9999-9999-999999999999",
      "acs_user_id": "33333333-3333-3333-3333-333333333333",
      "display_name": "Multi Phone Sync Credential",
      "code": null,
      "acs_system_id": "11111111-1111-1111-1111-111111111111",
      "access_method": "mobile_key",
      "workspace_id": "00000000-0000-0000-0000-000000000000",
      "created_at": "2024-04-12T03:56:22.396Z",
      "is_multi_phone_sync_credential": true,
      # manufacturer-specific metadata
    },
    "ok": true
  }
  ```

  ```json Python theme={null}
  AcsCredential(
    acs_credential_id='99999999-9999-9999-9999-999999999999',
    acs_user_id='33333333-3333-3333-3333-333333333333',
    display_name='Multi Phone Sync Credential',
    code=null,
    acs_system_id='11111111-1111-1111-1111-111111111111',
    access_method='mobile_key',
    workspace_id='00000000-0000-0000-0000-000000000000',
    created_at='2024-04-12T03:56:22.396Z',
    is_multi_phone_sync_credential=True,
    # manufacturer-specific metadata
  )
  ```

  ```json Ruby theme={null}
  # Coming soon!
  ```

  ```json PHP theme={null}
  {
    "acs_credential_id": "99999999-9999-9999-9999-999999999999",
    "acs_user_id": "33333333-3333-3333-3333-333333333333",
    "display_name": "Multi Phone Sync Credential",
    "code": null,
    "acs_system_id": "11111111-1111-1111-1111-111111111111",
    "access_method": "mobile_key",
    "workspace_id": "00000000-0000-0000-0000-000000000000",
    "created_at": "2024-04-12T03:56:22.396Z",
    "is_multi_phone_sync_credential": true
    // manufacturer-specific metadata
  }
  ```

  ```json C# theme={null}
  {
    "acs_credential_id": "99999999-9999-9999-9999-999999999999",
    "acs_user_id": "33333333-3333-3333-3333-333333333333",
    "display_name": "Multi Phone Sync Credential",
    "code": null,
    "acs_system_id": "11111111-1111-1111-1111-111111111111",
    "access_method": "mobile_key",
    "workspace_id": "00000000-0000-0000-0000-000000000000",
    "created_at": "2024-04-12T03:56:22.396Z",
    "is_multi_phone_sync_credential": true
    // manufacturer-specific metadata
  }
  ```
</CodeGroup>


# Listing Credentials and Associated Entrances
Source: https://docs.seam.co/low-level-apis/access-systems/managing-credentials/listing-credentials-and-associated-entrances

Learn how to list entrances associated with a credential and credentials associated with an entrance.

Once you have [created credentials](../managing-credentials), you can retrieve the set of entrances associated with a credential. You can also use an `acs_entrance` endpoint to retrieve the credentials that grant access to a specific entrance.

## List Entrances Associated with a Credential

To [list the entrances to which a specific credential grants access](/api/acs/credentials/list_accessible_entrances), use `list_accessible_entrances` and provide the `acs_credential_id`.

**Request:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  await seam.acs.credentials.listAccessibleEntrances({
    acs_credential_id: '66666666-6666-6666-6666-666666666666',
  })
  ```

  ```bash cURL theme={null}
  # Use GET or POST.
  curl -X 'GET' \
    'https://connect.getseam.com/acs/credentials/list_accessible_entrances' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${API_KEY}" \
    -H 'Content-Type: application/json' \
    -d '{
    "acs_credential_id": "66666666-6666-6666-6666-666666666666"
  }'
  ```

  ```python Python theme={null}
  seam.acs.credentials.list_accessible_entrances(
    acs_credential_id="66666666-6666-6666-6666-666666666666"
  )
  ```

  ```ruby Ruby theme={null}
  # Coming soon!
  ```

  ```php PHP theme={null}
  $seam->acs->credentials->list_accessible_entrances(
    acs_credential_id: "66666666-6666-6666-6666-666666666666"
  );
  ```

  ```csharp C# theme={null}
  seam.CredentialsAcs.ListAccessibleEntrances(
    acsCredentialId: "66666666-6666-6666-6666-666666666666"
  );
  ```
</CodeGroup>

**Response:**

<CodeGroup>
  ```json JavaScript theme={null}
  [
    {
      acs_entrance_id: '55555555-5555-5555-5555-555555555555',
      acs_system_id: '11111111-1111-1111-1111-111111111111',
      display_name: 'Guest Lock 2',
      ...
    },
    ...
  ]
  ```

  ```json cURL theme={null}
  {
    "acs_entrances": [
      {
        "acs_entrance_id": "55555555-5555-5555-5555-555555555555",
        "acs_system_id": "11111111-1111-1111-1111-111111111111",
        "display_name": "Guest Lock 2",
        ...
      },
      ...
    ],
    "ok": true
  }
  ```

  ```json Python theme={null}
  [
    AcsEntrance(
      acs_entrance_id='55555555-5555-5555-5555-555555555555',
      acs_system_id='11111111-1111-1111-1111-111111111111',
      display_name='Guest Lock 2',
      ...
    ),
    ...
  ]
  ```

  ```json Ruby theme={null}
  # Coming soon!
  ```

  ```json PHP theme={null}
  [
    {
      "acs_entrance_id": "55555555-5555-5555-5555-555555555555",
      "acs_system_id": "11111111-1111-1111-1111-111111111111",
      "display_name": "Guest Lock 2",
      ...
    },
    ...
  ]
  ```

  ```json C# theme={null}
  {
    "acs_entrance_id": "55555555-5555-5555-5555-555555555555",
    "acs_system_id": "11111111-1111-1111-1111-111111111111",
    "display_name": "Guest Lock 2",
    ...
  }
  ...
  ```
</CodeGroup>

***

## List Credentials Associated with an Entrance

To list the credentials that grant access to a specific entrance, use `list_credentials_with_access` method for the `acs_entrance` object and provide the `acs_entrance_id`. For details, see [Retrieving Entrance Details](../retrieving-entrance-details#list-credentials-associated-with-an-entrance).


# Retrieving Entrance Details
Source: https://docs.seam.co/low-level-apis/access-systems/retrieving-entrance-details

Learn how to get details about the entrances in your ACS, including listing the credentials that provide access to a specific entrance.

In an ACS, an entrance is a secured door, gate, zone, or other method of entry. You can list details for all the `acs_entrance` resources in your [workspace](/core-concepts/workspaces/index) or get these details for a specific `acs_entrance`. You can also list all entrances associated with a specific [credential](/low-level-apis/access-systems/managing-credentials), and you can list all credentials associated with a specific entrance.

***

## List All Entrances

You can [list all `acs_entrance` resources](/api/acs/entrances/list) in your workspace. Note that entrance details include manufacturer-specific metadata that may vary by [manufacturer](/device-and-system-integration-guides#access-control-systems).

**Request:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  await seam.acs.entrances.list()
  ```

  ```bash cURL theme={null}
  # Use GET or POST.
  curl -X 'GET' \
    'https://connect.getseam.com/acs/entrances/list' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${API_KEY}" \
    -H 'Content-Type: application/json' \
    -d '{}'
  ```

  ```python Python theme={null}
  seam.acs.entrances.list()
  ```

  ```ruby Ruby theme={null}
  # Coming soon!
  ```

  ```php PHP theme={null}
  $seam->acs->entrances->list();
  ```

  ```csharp C# theme={null}
  seam.EntrancesAcs.List();
  ```
</CodeGroup>

**Response:**

<CodeGroup>
  ```json JavaScript theme={null}
  [
    {
      acs_entrance_id: '55555555-5555-5555-5555-555555555555',
      acs_system_id: '11111111-1111-1111-1111-111111111111',
      workspace_id: '00000000-0000-0000-0000-000000000000',
      display_name: 'Guest Lock 2',
      ...
    },
    ...
  ]
  ```

  ```json cURL theme={null}
  {
    "acs_entrances": [
      {
        "acs_entrance_id": "55555555-5555-5555-5555-555555555555",
        "acs_system_id": "11111111-1111-1111-1111-111111111111",
        "workspace_id": "00000000-0000-0000-0000-000000000000",
        "display_name": "Guest Lock 2",
        ...
      },
      ...
    ],
    "ok": true
  }
  ```

  ```json Python theme={null}
  [
    AcsEntrance(
      acs_entrance_id='55555555-5555-5555-5555-555555555555',
      acs_system_id='11111111-1111-1111-1111-111111111111',
      workspace_id='00000000-0000-0000-0000-000000000000',
      display_name='Guest Lock 2',
      ....
    ),
    ...
  ]
  ```

  ```json Ruby theme={null}
  # Coming soon!
  ```

  ```json PHP theme={null}
  [
    {
      "acs_entrance_id": "55555555-5555-5555-5555-555555555555",
      "acs_system_id": "11111111-1111-1111-1111-111111111111",
      "workspace_id": "00000000-0000-0000-0000-000000000000",
      "display_name": "Guest Lock 2",
      ...
    },
    ...
  ]
  ```

  ```json C# theme={null}
  {
    "acs_entrance_id": "55555555-5555-5555-5555-555555555555",
    "acs_system_id": "11111111-1111-1111-1111-111111111111",
    "workspace_id": "00000000-0000-0000-0000-000000000000",
    "display_name": "Guest Lock 2",
    ...
  }
  ...
  ```
</CodeGroup>

***

## List Entrances in an ACS

To list all `acs_entrance`s in a specific ACS, include the `acs_system_id` filter in the [List Entrances](/api/acs/entrances/list) request. Note that entrance details include manufacturer-specific metadata that may vary by [manufacturer](/device-and-system-integration-guides#access-control-systems).

**Request:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  await seam.acs.entrances.list({
    acs_system_id: '11111111-1111-1111-1111-111111111111',
  })
  ```

  ```bash cURL theme={null}
  # Use GET or POST.
  curl -X 'GET' \
    'https://connect.getseam.com/acs/entrances/list' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${API_KEY}" \
    -H 'Content-Type: application/json' \
    -d '{
    "acs_system_id": "11111111-1111-1111-1111-111111111111"
  }'
  ```

  ```python Python theme={null}
  seam.acs.entrances.list(
    acs_system_id="11111111-1111-1111-1111-111111111111"
  )
  ```

  ```ruby Ruby theme={null}
  # Coming soon!
  ```

  ```php PHP theme={null}
  $seam->acs->entrances->list(
    acs_system_id: "11111111-1111-1111-1111-111111111111"
  );
  ```

  ```csharp C# theme={null}
  seam.EntrancesAcs.List(
    acsSystemId: "11111111-1111-1111-1111-111111111111"
  );
  ```
</CodeGroup>

**Response:**

<CodeGroup>
  ```json JavaScript theme={null}
  [
    {
      acs_entrance_id: '55555555-5555-5555-5555-555555555555',
      acs_system_id: '11111111-1111-1111-1111-111111111111',
      workspace_id: '00000000-0000-0000-0000-000000000000',
      display_name: 'Guest Lock 2',
      ...
    },
    ...
  ]
  ```

  ```json cURL theme={null}
  {
    "acs_entrances": [
      {
        "acs_entrance_id": "55555555-5555-5555-5555-555555555555",
        "acs_system_id": "11111111-1111-1111-1111-111111111111",
        "workspace_id": "00000000-0000-0000-0000-000000000000",
        "display_name": "Guest Lock 2",
        ...
      },
      ...
    ],
    "ok": true
  }
  ```

  ```json Python theme={null}
  [
    AcsEntrance(
      acs_entrance_id='55555555-5555-5555-5555-555555555555',
      acs_system_id='11111111-1111-1111-1111-111111111111',
      workspace_id='00000000-0000-0000-0000-000000000000',
      display_name='Guest Lock 2',
      ....
    ),
    ...
  ]
  ```

  ```json Ruby theme={null}
  # Coming soon!
  ```

  ```json PHP theme={null}
  [
    {
      "acs_entrance_id": "55555555-5555-5555-5555-555555555555",
      "acs_system_id": "11111111-1111-1111-1111-111111111111",
      "workspace_id": "00000000-0000-0000-0000-000000000000",
      "display_name": "Guest Lock 2",
      ...
    },
    ...
  ]
  ```

  ```json C# theme={null}
  {
    "acs_entrance_id": "55555555-5555-5555-5555-555555555555",
    "acs_system_id": "11111111-1111-1111-1111-111111111111",
    "workspace_id": "00000000-0000-0000-0000-000000000000",
    "display_name": "Guest Lock 2",
    ...
  }
  ...
  ```
</CodeGroup>

***

## List Credentials Associated with an Entrance

To [list the credentials that grant access to a specific entrance](/api/acs/entrances/list_credentials_with_access), use `list_credentials_with_access` method for the `acs_entrance` object and provide the `acs_entrance_id`.

**Request:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  await seam.acs.entrances.list_credentials_with_access({
    acs_entrance_id: '55555555-5555-5555-5555-555555555555',
  })
  ```

  ```bash cURL theme={null}
  # Use GET or POST.
  curl -X 'GET' \
    'https://connect.getseam.com/acs/entrances/list_credentials_with_access' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${API_KEY}" \
    -H 'Content-Type: application/json' \
    -d '{
    "acs_entrance_id": "55555555-5555-5555-5555-555555555555"
  }'
  ```

  ```python Python theme={null}
  seam.acs.entrances.list_credentials_with_access(
    acs_entrance_id="55555555-5555-5555-5555-555555555555"
  )
  ```

  ```ruby Ruby theme={null}
  # Coming soon!
  ```

  ```php PHP theme={null}
  $seam->acs->entrances->list_credentials_with_access(
    acs_entrance_id: "55555555-5555-5555-5555-555555555555"
  );
  ```

  ```csharp C# theme={null}
  seam.EntrancesAcs.ListCredentialsWithAccess(
    acsEntranceId: "55555555-5555-5555-5555-555555555555"
  );
  ```
</CodeGroup>

**Response:**

<CodeGroup>
  ```json JavaScript theme={null}
  [
    {
      acs_credential_id: '77777777-7777-7777-7777-777777777777',
      acs_user_id: '33333333-3333-3333-3333-333333333333',
      acs_system_id: '11111111-1111-1111-1111-111111111111',
      access_method: 'mobile_key',
      starts_at: '2024-04-09T14:30:55.688Z',
      ends_at: '2024-03-04T10:40:00.000Z',
      ...
    },
    ...
  ]
  ```

  ```json cURL theme={null}
  {
    "acs_credentials": [
      {
        "acs_credential_id": "77777777-7777-7777-7777-777777777777",
        "acs_user_id": "33333333-3333-3333-3333-333333333333",
        "acs_system_id": "11111111-1111-1111-1111-111111111111",
        "access_method": "mobile_key",
        "starts_at": "2024-04-09T14:30:55.688Z",
        "ends_at": "2024-03-04T10:40:00.000Z",
        ...
      },
      ...
    ],
    "ok": true
  }
  ```

  ```json Python theme={null}
  [
    AcsCredential(
      acs_credential_id='77777777-7777-7777-7777-777777777777',
      acs_user_id='33333333-3333-3333-3333-333333333333',
      acs_system_id='11111111-1111-1111-1111-111111111111',
      access_method='mobile_key',
      starts_at='2024-04-09T14:30:55.688Z',
      ends_at='2024-03-04T10:40:00.000Z',
      ...
    ),
    ...
  ]
  ```

  ```json Ruby theme={null}
  # Coming soon!
  ```

  ```json PHP theme={null}
  [
    {
      "acs_credential_id": "77777777-7777-7777-7777-777777777777",
      "acs_user_id": "33333333-3333-3333-3333-333333333333",
      "acs_system_id": "11111111-1111-1111-1111-111111111111",
      "access_method": "mobile_key",
      "starts_at": "2024-04-09T14:30:55.688Z",
      "ends_at": "2024-03-04T10:40:00.000Z",
      ...
    },
    ...
  ]
  ```

  ```json C# theme={null}
  {
    "acs_credential_id": "77777777-7777-7777-7777-777777777777",
    "acs_user_id": "33333333-3333-3333-3333-333333333333",
    "acs_system_id": "11111111-1111-1111-1111-111111111111",
    "access_method": "mobile_key",
    "starts_at": "2024-04-09T14:30:55.688Z",
    "ends_at": "2024-03-04T10:40:00.000Z",
    ...
  }
  ...
  ```
</CodeGroup>

***

## List Entrances Associated with a Credential

To [list the entrances to which a specific credential grants access](/api/acs/credentials/list_accessible_entrances), use `list_accessible_entrances` method for the `acs_credential` object and provide the `acs_credential_id`. For details, see [Managing Credentials](/low-level-apis/access-systems/managing-credentials/listing-credentials-and-associated-entrances#list-entrances-associated-with-a-credential).

***

## Get an Entrance

You can [get the details of a specific `acs_entrance`](/api/acs/entrances/get). Note that entrance details include manufacturer-specific metadata that may vary by [manufacturer](/device-and-system-integration-guides#access-control-systems).

**Request:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  await seam.acs.entrances.get({
    acs_entrance_id: '55555555-5555-5555-5555-555555555555',
  })
  ```

  ```bash cURL theme={null}
  # Use GET or POST.
  curl -X 'GET' \
    'https://connect.getseam.com/acs/entrances/get' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${API_KEY}" \
    -H 'Content-Type: application/json' \
    -d '{
    "acs_entrance_id": "55555555-5555-5555-5555-555555555555"
  }'
  ```

  ```python Python theme={null}
  seam.acs.entrances.get(
    acs_entrance_id="55555555-5555-5555-5555-555555555555"
  )
  ```

  ```ruby Ruby theme={null}
  # Coming soon!
  ```

  ```php PHP theme={null}
  $seam->acs->entrances->get(
    acs_entrance_id: "55555555-5555-5555-5555-555555555555"
  );
  ```

  ```csharp C# theme={null}
  seam.EntrancesAcs.Get(
    acsEntranceId: "55555555-5555-5555-5555-555555555555"
  );
  ```
</CodeGroup>

**Response:**

<CodeGroup>
  ```json JavaScript theme={null}
  {
    acs_entrance_id: '55555555-5555-5555-5555-555555555555',
    acs_system_id: '11111111-1111-1111-1111-111111111111',
    workspace_id: '00000000-0000-0000-0000-000000000000',
    display_name: 'Guest Lock 2',
    ...
  }
  ```

  ```json cURL theme={null}
  {
    "acs_entrance": {
      "acs_entrance_id": "55555555-5555-5555-5555-555555555555",
      "acs_system_id": "11111111-1111-1111-1111-111111111111",
      "workspace_id": "00000000-0000-0000-0000-000000000000",
      "display_name": "Guest Lock 2",
      ...
    },
    "ok": true
  }
  ```

  ```json Python theme={null}
  AcsEntrance(
    acs_entrance_id: '55555555-5555-5555-5555-555555555555',
    acs_system_id: '11111111-1111-1111-1111-111111111111',
    workspace_id: '00000000-0000-0000-0000-000000000000',
    display_name: 'Guest Lock 2',
    ...
  )
  ```

  ```json Ruby theme={null}
  # Coming soon!
  ```

  ```json PHP theme={null}
  {
    "acs_entrance_id": "55555555-5555-5555-5555-555555555555",
    "acs_system_id": "11111111-1111-1111-1111-111111111111",
    "workspace_id": "00000000-0000-0000-0000-000000000000",
    "display_name": "Guest Lock 2",
    ...
  }
  ```

  ```json C# theme={null}
  {
    "acs_entrance_id": "55555555-5555-5555-5555-555555555555",
    "acs_system_id": "11111111-1111-1111-1111-111111111111",
    "workspace_id": "00000000-0000-0000-0000-000000000000",
    "display_name": "Guest Lock 2",
    ...
  }
  ```
</CodeGroup>


# Troubleshooting Your Access Control System
Source: https://docs.seam.co/low-level-apis/access-systems/troubleshooting-your-access-control-system

Learn about ACS-related errors and warnings, as well as how to resolve them.

The Seam API provides a set of errors and warnings that help you to troubleshoot your ACS.

## On-Premises Access Control System Errors

These errors alert you to issues involving the connection between your on-premises ACS and Seam.

### `acs_system.errors.seam_bridge_disconnected`

This error indicates that the Seam API cannot communicate with your [Seam Bridge](/capability-guides/seam-bridge), for example, if the Seam Bridge executable has stopped or if the computer running the Seam Bridge executable is offline. This error might also occur if your Seam Bridge is connected to the wrong [workspace](/core-concepts/workspaces/index).

To troubleshoot this error:

* Make sure that you are running the [latest version of the Seam Bridge](https://www.seam.co/seam-bridge/releases/latest). If not, reinstall and then start the Seam Bridge executable. See the [Seam Bridge installation instructions](/capability-guides/seam-bridge#download-seam-bridge).
* Reconnect the Seam Bridge. To reconnect, you can go to your ACS in the **Access Systems** area of the [Seam Console](https://console.seam.co/) or use a [Connect Webview](/api/connect_webviews/object). For more information, see [Pairing the Seam Bridge with Your Workspace](/capability-guides/seam-bridge#getting-started).
* Restart the Seam Bridge executable.

***

### `acs_system.errors.visionline_instance_unreachable`

This error indicates that your Seam Bridge is functioning correctly and the Seam API can communicate with your Seam Bridge, but the Seam API cannot connect to your on-premises [Visionline ACS](/device-and-system-integration-guides/assa-abloy-visionline-access-control-system). For example, the IP address of the on-premises ACS may be set incorrectly within your Seam workspace.

To troubleshoot this error:

* Reconnect your on-premises ACS to correct the IP address configuration. To reconnect, you can go to **Access Systems** in the [Seam Console](https://console.seam.co/) or use a [Connect Webview](/api/connect_webviews/object). See the setup instructions within the [system integration guide](/device-and-system-integration-guides#access-control-systems) for your on-premises ACS.
* Make sure that your on-premises ACS is running correctly.

***

## Cloud-based Access Control System Errors

These errors alert you to issues involving your cloud-based ACS.

### `acs_system.errors.salto_ks_subscription_limit_exceeded`

You have reached the maximum number of users allowed for your site. This means that new access codes cannot be created.

To troubleshoot this error, contact Salto support to increase your user limit, or delete some users from your site.

***

### `acs_system.errors.acs_system_disconnected`

Your access system has been disconnected.

To troubleshoot this error:

* Use a [Connect Webview](/core-concepts/connect-webviews/index) to reconnect the account.
* Unblock the "Seam Integration" user within the [Salto KS dashboard](https://app.saltoks.com/).

***

### `acs_system.errors.account_disconnected`

Your login credentials for your ACS account are invalid.

To troubleshoot this error, use a [Connect Webview](/core-concepts/connect-webviews/index) to reconnect the account.

***

## Cloud-based Access Control System Warnings

These warnings alert you to issues involving your cloud-based ACS.

### `acs_system.warnings.salto_ks_subscription_limit_almost_reached`

the Salto KS site has exceeded 80% of the maximum number of allowed users.

To troubleshoot this warning, contact Salto support to increase your subscription limit, or delete some users from your site.

***

## ACS User Errors

These errors alert you to issues involving your ACS users.

### `acs_user.errors.salto_ks_subscription_limit_exceeded`

This Salto KS user could not be subscribed on Salto KS because the site's user subscription limit has been exceeded.

To troubleshoot this error, increase your subscription limit, or delete some users from your site.

***

### `acs_user.errors.failed_to_create_on_acs_system`

The ACS user was not created on the ACS system. This is likely due to an unexpected internal error.

This error occurs in any of the following situations:

* The site user role does not exist.
* The email address provided is already in use.

To troubleshoot this error, contact [Seam support](mailto:support@seam.co) or, if applicable, consider updating the user's email address.

***

### `acs_user.errors.failed_to_update_on_acs_system`

The ACS user was not updated on the ACS system. This is likely due to an unexpected internal error. This error also occurs if the provided email address is already in use.

To troubleshoot this error, contact [Seam support](mailto:support@seam.co) or, if applicable, consider updating the user's email address.

***

### `acs_user.errors.failed_to_delete_on_acs_system`

The ACS user was not deleted on the ACS system. This is likely due to an unexpected internal error.

To troubleshoot this error, contact [Seam support](mailto:support@seam.co).

***

### `acs_user.errors.deleted_externally`

The ACS user was deleted from the ACS system outside of Seam.

***

## ACS User Warnings

These warnings alert you to issues involving your ACS users.

### `acs_user.warnings.salto_ks_user_not_subscribed`

This ACS user is not subscribed on Salto KS, so they cannot unlock doors or perform any actions.

This warning occurs in any of the following situations:

* The ACS user's access schedule has not started yet.
* The ACS user's access schedule has ended.
* The site has reached its limit of active users (subscription slots).
* The ACS user has been manually unsubscribed.

***

### `acs_user.warnings.being_deleted`

The ACS user is being deleted from the ACS system. This is a temporary state, and the deletion will complete shortly.

***

## Credential Errors

These errors alert you to issues involving your credentials.

### `acs_credential.invalidated`

An credential was invalidated and cannot be used anymore. The implications of this error vary by brand and access control system.

For Visionline, if a card is considered invalid if it is overridden, discarded, canceled, or overwritten. If you receive this event for a Visionline credential, check its `visionline_metadata.is_valid` property.


# Managing ACS Users
Source: https://docs.seam.co/low-level-apis/access-systems/user-management

Learn how to manage your ACS users to grant or revoke physical access for people.

<Info>
  **Granting access?** [Access Grants](/use-cases/granting-access/index) are the
  default and recommended way to grant access—they manage the underlying codes
  and credentials for you, across standalone smart locks and access systems
  alike.
</Info>

An ACS user typically refers to an individual who requires access, like an employee or resident. Each user can possess multiple credentials that serve as their keys or identifiers for access. The type of credential can vary widely. For example, in the [Salto](/device-and-system-integration-guides/salto-locks) system, a user can have a PIN code, a mobile app account, and a fob. In other platforms, it is not uncommon for a user to have more than one of the same credential type, such as multiple key cards. Additionally, these credentials can have a schedule or validity period.

This guide explains how to create and manage ACS users. Using the [Access Control Systems API](/api/acs/object), you can automate issuing access to long-term tenants or visitors.

***

## Before You Begin: Identify the ACS System ID

To add ACS users to your access control system, first retrieve the `acs_system_id` of the ACS that you want to configure. To retrieve the ACS details, use [Get a System](/api/acs/systems/get) or [List Systems](/api/acs/systems/list). Then, continue to the remaining sections in this topic to learn how to manage ACS users.

**Request:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  await seam.acs.systems.list()
  ```

  ```bash cURL theme={null}
  # Use GET or POST.
  curl -X 'GET' \
    'https://connect.getseam.com/acs/systems/list' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${API_KEY}" \
    -H 'Content-Type: application/json' \
    -d '{}'
  ```

  ```python Python theme={null}
  seam.acs.systems.list()
  ```

  ```ruby Ruby theme={null}
  # Coming soon!
  ```

  ```php PHP theme={null}
  $seam->acs->systems->list();
  ```

  ```csharp C# theme={null}
  seam.SystemsAcs.List();
  ```
</CodeGroup>

**Response:**

<CodeGroup>
  ```json JavaScript theme={null}
  [
    {
      acs_system_id: '11111111-1111-1111-1111-111111111111',
      name: 'Visionline System',
      ...
    },
    ...
  ]
  ```

  ```json cURL theme={null}
  {
    "acs_systems": [
      {
        "acs_system_id": "11111111-1111-1111-1111-111111111111",
        "name": "Visionline System",
        ...
      },
      ...
    ],
    "ok": true
  }
  ```

  ```json Python theme={null}
  [
    AcsSystem(
      acs_system_id='11111111-1111-1111-1111-111111111111',
      name='Visionline System',
      ...
    ),
    ...
  ]
  ```

  ```json Ruby theme={null}
  # Coming soon!
  ```

  ```json PHP theme={null}
  [
    {
      "acs_system_id": "11111111-1111-1111-1111-111111111111",
      "name": "Visionline System",
      ...
    },
    ...
  ]
  ```

  ```json C# theme={null}
  {
    "acs_system_id": "11111111-1111-1111-1111-111111111111",
    "name": "Visionline System",
    ...
  }
  ...
  ```
</CodeGroup>

***

## Create an ACS User

To [create an ACS user](/api/acs/users/create), provide the `acs_system_id` of the ACS system and the attributes of the user, such as the `full_name`, `email_address`, `phone_number`, and so on.

Also, if your [ACS architecture](../../low-level-apis/access-systems/connect-an-acs-to-seam/understanding-access-control-system-differences) supports access groups, you can also assign an ACS user to one or more access groups. To do so, when you create the user, include the IDs of the access group to which you want add the user. The `acs_access_group_ids` parameter accepts an array of strings.

In addition, if your ACS architecture supports assigning access schedules directly to ACS users, you can specify an `access_schedule` for the user, including a `starts_at` and `ends_at` date and time.

Further, you can use the `user_identity_id` parameter to associate a new ACS user with a [user identity](/api/user_identities/object). You can use a user identity to link an ACS user with an app user in your system, such as a [mobile access app user](../../capability-guides/mobile-access/managing-mobile-app-user-accounts-with-user-identities#what-is-a-user-identity) or an app user who needs access to multiple ACSs.

**Request:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  await seam.acs.users.create({
    acs_system_id: '11111111-1111-1111-1111-111111111111',
    user_identity_id: '22222222-2222-2222-2222-222222222222',
    full_name: 'Jane Doe',
    email_address: 'jane@example.com',
    phone_number: '+15555550101',
  })
  ```

  ```bash cURL theme={null}
  curl -X 'POST' \
    'https://connect.getseam.com/acs/users/create' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${API_KEY}" \
    -H 'Content-Type: application/json' \
    -d '{
    "acs_system_id": "11111111-1111-1111-1111-111111111111",
    "user_identity_id": "22222222-2222-2222-2222-222222222222",
    "full_name": "Jane Doe",
    "email_address": "jane@example.com",
    "phone_number": "+15555550101"
  }'
  ```

  ```python Python theme={null}
  seam.acs.users.create(
    acs_system_id="11111111-1111-1111-1111-111111111111",
    user_identity_id="22222222-2222-2222-2222-222222222222",
    full_name="Jane Doe",
    email_address="jane@example.com",
    phone_number="+15555550101"
  )
  ```

  ```ruby Ruby theme={null}
  # Coming soon!
  ```

  ```php PHP theme={null}
  $seam->acs->users->create(
    acs_system_id: "11111111-1111-1111-1111-111111111111",
    user_identity_id: "22222222-2222-2222-2222-222222222222",
    full_name: "Jane Doe",
    email_address: "jane@example.com",
    phone_number: "+15555550101"
  );
  ```

  ```csharp C# theme={null}
  seam.UsersAcs.Create(
    acsSystemId: "11111111-1111-1111-1111-111111111111",
    userIdentityId: "22222222-2222-2222-2222-222222222222",
    fullName: "Jane Doe",
    emailAddress: "jane@example.com",
    phoneNumber: "+15555550101"
  );
  ```
</CodeGroup>

**Response:**

<CodeGroup>
  ```json JavaScript theme={null}
  {
    acs_user_id: '33333333-3333-3333-3333-333333333333',
    full_name: 'Jane Doe',
    email_address: 'jane@example.com',
    phone_number: '+15555550101',
    acs_system_id: '11111111-1111-1111-1111-111111111111',
    ...
  }
  ```

  ```json cURL theme={null}
  {
    "acs_user": {
      "acs_user_id": "33333333-3333-3333-3333-333333333333",
      "full_name": "Jane Doe",
      "email_address": "jane@example.com",
      "phone_number": "+15555550101",
      "acs_system_id": "11111111-1111-1111-1111-111111111111",
      ...
    },
    "ok": true
  }
  ```

  ```json Python theme={null}
  AcsUser(
    acs_user_id='33333333-3333-3333-3333-333333333333',
    full_name='Jane Doe',
    email_address='jane@example.com',
    phone_number='+15555550101',
    acs_system_id='11111111-1111-1111-1111-111111111111',
    ...
  )
  ```

  ```json Ruby theme={null}
  # Coming soon!
  ```

  ```json PHP theme={null}
  {
    "acs_user_id": "33333333-3333-3333-3333-333333333333",
    "full_name": "Jane Doe",
    "email_address": "jane@example.com",
    "phone_number": "+15555550101",
    "acs_system_id": "11111111-1111-1111-1111-111111111111",
    ...
  }
  ```

  ```json C# theme={null}
  {
    "acs_user_id": "33333333-3333-3333-3333-333333333333",
    "full_name": "Jane Doe",
    "email_address": "jane@example.com",
    "phone_number": "+15555550101",
    "acs_system_id": "11111111-1111-1111-1111-111111111111",
    ...
  }
  ```
</CodeGroup>

***

## List ACS Users

To [list all ACS users](/api/acs/users/list) within an `acs_system`, provide the `acs_system_id` of the ACS. You can also filter users by `user_identity_id`, `user_identity_email_address`, or `user_identity_phone_number`.

**Request:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  await seam.acs.users.list({
    acs_system_id: '11111111-1111-1111-1111-111111111111',
  })
  ```

  ```bash cURL theme={null}
  # Use GET or POST.
  curl -X 'GET' \
    'https://connect.getseam.com/acs/users/list' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${API_KEY}" \
    -H 'Content-Type: application/json' \
    -d '{
    "acs_system_id": "11111111-1111-1111-1111-111111111111"
  }'
  ```

  ```python Python theme={null}
  seam.acs.users.list(
    acs_system_id="11111111-1111-1111-1111-111111111111"
  )
  ```

  ```ruby Ruby theme={null}
  # Coming soon!
  ```

  ```php PHP theme={null}
  $seam->acs->users->list(
    acs_system_id: "11111111-1111-1111-1111-111111111111"
  );
  ```

  ```csharp C# theme={null}
  seam.UsersAcs.List(
    acsSystemId: "11111111-1111-1111-1111-111111111111"
  );
  ```
</CodeGroup>

**Response:**

<CodeGroup>
  ```json JavaScript theme={null}
  [
    {
      acs_user_id: '33333333-3333-3333-3333-333333333333',
      full_name: 'Jane Doe',
      email_address: 'jane@example.com',
      ...
    },
    ...
  ]
  ```

  ```json cURL theme={null}
  {
    "acs_users": [
      {
        "acs_user_id": "33333333-3333-3333-3333-333333333333",
        "full_name": "Jane Doe",
        "email_address": "jane@example.com",
        ...
      },
      ...
    ],
    "ok": true
  }
  ```

  ```json Python theme={null}
  [
    AcsUser(
      acs_user_id='33333333-3333-3333-3333-333333333333',
      full_name='Jane Doe',
      email_address='jane@example.com',
      ...
    ),
    ...
  ]
  ```

  ```json Ruby theme={null}
  # Coming soon!
  ```

  ```json PHP theme={null}
  [
    {
      "acs_user_id": "33333333-3333-3333-3333-333333333333",
      "full_name": "Jane Doe",
      "email_address": "jane@example.com",
      ...
    },
    ...
  ]
  ```

  ```json C# theme={null}
  {
    "acs_user_id": "33333333-3333-3333-3333-333333333333",
    "full_name": "Jane Doe",
    "email_address": "jane@example.com",
    ...
  }
  ...
  ```
</CodeGroup>

***

## Get an ACS User

To [get an ACS user](/api/acs/users/get), provide the `acs_user_id` of the user that you want to retrieve. These details include the contact details for the user, the user's access schedule, the associated [user identity](/api/user_identities/object), if applicable, and so on.

**Request:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  await seam.acs.users.get({
    acs_user_id: '33333333-3333-3333-3333-333333333333',
  })
  ```

  ```bash cURL theme={null}
  # Use GET or POST.
  curl -X 'GET' \
    'https://connect.getseam.com/acs/users/get' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${API_KEY}" \
    -H 'Content-Type: application/json' \
    -d '{
    "acs_user_id": "33333333-3333-3333-3333-333333333333"
  }'
  ```

  ```python Python theme={null}
  seam.acs.users.get(
   acs_user_id="33333333-3333-3333-3333-333333333333"
  )
  ```

  ```ruby Ruby theme={null}
  # Coming soon!
  ```

  ```php PHP theme={null}
  $seam->acs->users->get(
    acs_user_id: "33333333-3333-3333-3333-333333333333"
  );
  ```

  ```csharp C# theme={null}
  seam.AcsUsers.Get(
    acsUserId: "33333333-3333-3333-3333-333333333333"
  );
  ```
</CodeGroup>

**Response:**

<CodeGroup>
  ```json JavaScript theme={null}
  {
    acs_user_id: '33333333-3333-3333-3333-333333333333',
    full_name: 'Jane Doe',
    email_address: 'jane@example.com',
    phone_number: '+15555550100',
    acs_system_id: '11111111-1111-1111-1111-111111111111',
    access_schedule: {
      "starts_at": "2024-03-01T10:40:00.000Z",
      "ends_at": "2024-03-04T10:40:00.000Z"
    },
    user_identity_id: '22222222-2222-2222-2222-222222222222',
    ...
  }
  ```

  ```json cURL theme={null}
  {
    "acs_user": {
      "acs_user_id": "33333333-3333-3333-3333-333333333333",
      "full_name": "Jane Doe",
      "email_address": "jane@example.com",
      "phone_number": "+15555550100",
      "acs_system_id": "11111111-1111-1111-1111-111111111111",
      "access_schedule": {
        "starts_at": "2024-03-01T10:40:00.000Z",
        "ends_at": "2024-03-04T10:40:00.000Z"
      },
      "user_identity_id": "22222222-2222-2222-2222-222222222222",
      ...
    },
    "ok": true
  }
  ```

  ```json Python theme={null}
  AcsUser(
    acs_user_id='33333333-3333-3333-3333-333333333333',
    full_name='Jane Doe',
    email_address='jane@example.com',
    phone_number='+15555550100',
    acs_system_id='11111111-1111-1111-1111-111111111111',
    access_schedule={
      'starts_at': '2024-03-01T10:40:00.000Z',
      'ends_at': '2024-03-04T10:40:00.000Z'
    },
    user_identity_id='22222222-2222-2222-2222-222222222222',
    ...
  )
  ```

  ```json Ruby theme={null}
  # Coming soon!
  ```

  ```json PHP theme={null}
  {
    "acs_user_id": "33333333-3333-3333-3333-333333333333",
    "full_name": "Jane Doe",
    "email_address": "jane@example.com",
    "phone_number": "+15555550100",
    "acs_system_id": "11111111-1111-1111-1111-111111111111",
    "access_schedule": {
      "starts_at": "2024-03-01T10:40:00.000Z",
      "ends_at": "2024-03-04T10:40:00.000Z"
    },
    "user_identity_id": "22222222-2222-2222-2222-222222222222",
    ...
  }
  ```

  ```json C# theme={null}
  {
    "acs_user_id": "33333333-3333-3333-3333-333333333333",
    "full_name": "Jane Doe",
    "email_address": "jane@example.com",
    "phone_number": "+15555550100",
    "acs_system_id": "11111111-1111-1111-1111-111111111111",
    "access_schedule": {
      "starts_at": "2024-03-01T10:40:00.000Z",
      "ends_at": "2024-03-04T10:40:00.000Z"
    },
    "user_identity_id": "22222222-2222-2222-2222-222222222222",
    ..
  }
  ```
</CodeGroup>

***

## Update an ACS User

To [update an ACS user](/api/acs/users/update), provide the `acs_user_id` of the user that you want to update, along with the attributes that you want to modify, such as the contact details for the user or the user's access schedule.

**Request:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  await seam.acs.users.update({
    acs_user_id: '33333333-3333-3333-3333-333333333333',
    full_name: 'Jack Doe',
  })
  ```

  ```bash cURL theme={null}
  curl -X 'POST' \
    "https://connect.getseam.com/acs/users/update" \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${API_KEY}" \
    -H 'Content-Type: application/json' \
    -d '{
    "acs_user_id": "33333333-3333-3333-3333-333333333333",
    "full_name": "Jack Doe"
  }'
  ```

  ```python Python theme={null}
  seam.acs.users.update(
    acs_user_id="33333333-3333-3333-3333-333333333333",
    full_name="Jack Doe"
  )
  ```

  ```ruby Ruby theme={null}
  # Coming soon!
  ```

  ```php PHP theme={null}
  $seam->acs->users->update(
    acs_user_id: "33333333-3333-3333-3333-333333333333",
    full_name: "Jack Doe"
  );
  ```

  ```csharp C# theme={null}
  seam.UsersAcs.Update(
    acsUserId: "33333333-3333-3333-3333-333333333333",
    fullName: "Jack Doe"
  );
  ```
</CodeGroup>

**Response:**

<CodeGroup>
  ```json JavaScript theme={null}
  void
  ```

  ```json cURL theme={null}
  {
    "ok": true
  }
  ```

  ```json Python theme={null}
  None
  ```

  ```json Ruby theme={null}
  # Coming soon!
  ```

  ```json PHP theme={null}
  void
  ```

  ```json C# theme={null}
  void
  ```
</CodeGroup>

***

## Delete an ACS User

To [delete an ACS user](/api/acs/users/delete), provide the `acs_user_id` of the user that you want to delete.

**Request:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  await seam.acs.users.delete({
    acs_user_id: '33333333-3333-3333-3333-333333333333',
  })
  ```

  ```bash cURL theme={null}
  curl -X 'POST' \
    'https://connect.getseam.com/acs/users/delete' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${API_KEY}" \
    -H 'Content-Type: application/json' \
    -d '{
    "acs_user_id": "33333333-3333-3333-3333-333333333333"
  }'
  ```

  ```python Python theme={null}
  seam.acs.users.delete(
    acs_user_id="33333333-3333-3333-3333-333333333333"
  )
  ```

  ```ruby Ruby theme={null}
  # Coming soon!
  ```

  ```php PHP theme={null}
  $seam->acs->users->delete(
    acs_user_id: "33333333-3333-3333-3333-333333333333"
  );
  ```

  ```csharp C# theme={null}
  seam.UsersAcs.Delete(
    acsUserId: "33333333-3333-3333-3333-333333333333"
  );
  ```
</CodeGroup>

**Response:**

<CodeGroup>
  ```json JavaScript theme={null}
  void
  ```

  ```json cURL theme={null}
  {
    "ok": true
  }
  ```

  ```json Python theme={null}
  None
  ```

  ```json Ruby theme={null}
  # Coming soon!
  ```

  ```json PHP theme={null}
  void
  ```

  ```json C# theme={null}
  void
  ```
</CodeGroup>


# Assigning ACS Users to Access Groups
Source: https://docs.seam.co/low-level-apis/access-systems/user-management/assigning-users-to-access-groups

Learn how to use access groups to manage ACS user permissions across different doors and areas.

Some ACSs use access groups, which are sets of ACS users, combined with sets of permissions. These permissions include both the set of areas or assets that the ACS users can access and the schedule during which the users can access these areas or assets. Instead of assigning access rights individually to each ACS user, which can be time-consuming and error-prone, administrators can assign users to an access group, thereby ensuring that the users inherit all the permissions associated with the access group. Using access groups streamlines the process of managing large numbers of ACS users, especially in bigger organizations or complexes.

<Info>
  To learn whether your ACS supports access groups, see the [system integration
  guide](/device-and-system-integration-guides#access-control-systems)
  for your ACS.
</Info>

This guide explains how to grant access permissions to ACS users by adding them to the appropriate access groups.

***

## Add an ACS User to an Access Group

To [add an ACS user to an access group](/api/acs/users/add_to_access_group), provide both the `acs_user_id` and the `acs_access_group_id`.

**Request:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  await seam.acs.users.addToAccessGroup({
    acs_user_id: '33333333-3333-3333-3333-333333333333',
    acs_access_group_id: '44444444-4444-4444-4444-444444444444',
  })
  ```

  ```bash cURL theme={null}
  curl -X 'POST' \
    'https://connect.getseam.com/acs/users/add_to_access_group' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d '{
    "acs_user_id": "33333333-3333-3333-3333-333333333333",
    "acs_access_group_id": "44444444-4444-4444-4444-444444444444"
  }'
  ```

  ```python Python theme={null}
  seam.acs.users.add_to_access_group(
    acs_user_id="33333333-3333-3333-3333-333333333333",
    acs_access_group_id="44444444-4444-4444-4444-444444444444"
  )
  ```

  ```ruby Ruby theme={null}
  # Coming soon!
  ```

  ```php PHP theme={null}
  $seam->acs->users->add_to_access_group(
    acs_user_id: "33333333-3333-3333-3333-333333333333",
    acs_access_group_id: "44444444-4444-4444-4444-444444444444"
  );
  ```

  ```csharp C# theme={null}
  seam.UsersAcs.AddToAccessGroup(
    acsUserId: "33333333-3333-3333-3333-333333333333",
    acsAccessGroupId: "44444444-4444-4444-4444-444444444444"
  );
  ```
</CodeGroup>

**Response:**

<CodeGroup>
  ```json JavaScript theme={null}
  void
  ```

  ```json cURL theme={null}
  {
    "ok": true
  }
  ```

  ```json Python theme={null}
  None
  ```

  ```json Ruby theme={null}
  # Coming soon!
  ```

  ```json PHP theme={null}
  void
  ```

  ```json C# theme={null}
  void
  ```
</CodeGroup>

***

## Remove an ACS User from an Access Group

To [remove an ACS user from an access group](/api/acs/users/remove_from_access_group), provide both the `acs_user_id` and the `acs_access_group_id`.

**Request:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  await seam.acs.users.removeFromAccessGroup({
    acs_user_id: '33333333-3333-3333-3333-333333333333',
    acs_access_group_id: '44444444-4444-4444-4444-444444444444',
  })
  ```

  ```bash cURL theme={null}
  curl -X 'POST' \
    'https://connect.getseam.com/acs/users/remove_from_access_group' \
    -H 'accept: */*' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d '{
    "acs_user_id": "33333333-3333-3333-3333-333333333333",
    "acs_access_group_id": "44444444-4444-4444-4444-444444444444"
  }'
  ```

  ```python Python theme={null}
  seam.acs.users.remove_from_access_group(
    acs_user_id="33333333-3333-3333-3333-333333333333",
    acs_access_group_id="44444444-4444-4444-4444-444444444444"
  )
  ```

  ```ruby Ruby theme={null}
  # Coming soon!
  ```

  ```php PHP theme={null}
  $seam->acs->users->remove_from_access_group(
    acs_user_id: "33333333-3333-3333-3333-333333333333",
    acs_access_group_id: "44444444-4444-4444-4444-444444444444"
  );
  ```

  ```csharp C# theme={null}
  seam.UsersAcs.RemoveFromAccessGroup(
    acsUserId: "33333333-3333-3333-3333-333333333333",
    acsAccessGroupId: "44444444-4444-4444-4444-444444444444"
  );
  ```
</CodeGroup>

**Response:**

<CodeGroup>
  ```json JavaScript theme={null}
  void
  ```

  ```json cURL theme={null}
  {
    "ok": true
  }
  ```

  ```json Python theme={null}
  None
  ```

  ```json Ruby theme={null}
  # Coming soon!
  ```

  ```json PHP theme={null}
  void
  ```

  ```json C# theme={null}
  void
  ```
</CodeGroup>


# Suspending and Unsuspending ACS Users
Source: https://docs.seam.co/low-level-apis/access-systems/user-management/suspending-and-unsuspending-users

Learn how to make temporary access changes by suspending or unsuspending ACS users.

You can suspend an ACS user to revoke their access temporarily. Suspending an ACS user is a good action to take for users who may be behind on payment or have not fulfilled the requirements for entry. Then, once the user rectifies the payment, requirements, or other deficiency, you can unsuspend the ACS user to restore their access.

***

## Suspend an ACS User

To [suspend an ACS user](/api/acs/users/suspend), provide the `acs_user_id`.

**Request:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  await seam.acs.users.suspend({
    acs_user_id: '33333333-3333-3333-3333-333333333333',
  })
  ```

  ```bash cURL theme={null}
  curl -X 'POST' \
    'https://connect.getseam.com/acs/users/suspend' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${API_KEY}" \
    -H 'Content-Type: application/json' \
    -d '{
    "acs_user_id": "33333333-3333-3333-3333-333333333333"
  }'
  ```

  ```python Python theme={null}
  seam.acs.users.suspend(
    acs_user_id="33333333-3333-3333-3333-333333333333"
  )
  ```

  ```ruby Ruby theme={null}
  # Coming soon!
  ```

  ```php PHP theme={null}
  $seam->acs->users->suspend(
    acs_user_id: "33333333-3333-3333-3333-333333333333"
  );
  ```

  ```csharp C# theme={null}
  seam.UsersAcs.Suspend(
    acsUserId: "33333333-3333-3333-3333-333333333333",
  );
  ```
</CodeGroup>

**Response:**

<CodeGroup>
  ```json JavaScript theme={null}
  void
  ```

  ```json cURL theme={null}
  {
    "ok": true
  }
  ```

  ```json Python theme={null}
  None
  ```

  ```json Ruby theme={null}
  # Coming soon!
  ```

  ```json PHP theme={null}
  void
  ```

  ```json C# theme={null}
  void
  ```
</CodeGroup>

***

## Unsuspend an ACS User

To [unsuspend an ACS user](/api/acs/users/unsuspend), provide the `acs_user_id`.

**Request:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  await seam.acs.users.unsuspend({
    acs_user_id: '33333333-3333-3333-3333-333333333333',
  })
  ```

  ```bash cURL theme={null}
  curl -X 'POST' \
    'https://connect.getseam.com/acs/users/unsuspend' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${API_KEY}" \
    -H 'Content-Type: application/json' \
    -d '{
    "acs_user_id": "33333333-3333-3333-3333-333333333333"
  }'
  ```

  ```python Python theme={null}
  seam.acs.users.unsuspend(
    acs_user_id="33333333-3333-3333-3333-333333333333"
  )
  ```

  ```ruby Ruby theme={null}
  # Coming soon!
  ```

  ```php PHP theme={null}
  $seam->acs->users->unsuspend(
    acs_user_id: "33333333-3333-3333-3333-333333333333"
  );
  ```

  ```csharp C# theme={null}
  seam.UsersAcs.Unsuspend(
    acsUserId: "33333333-3333-3333-3333-333333333333"
  );
  ```
</CodeGroup>

**Response:**

<CodeGroup>
  ```json JavaScript theme={null}
  void
  ```

  ```json cURL theme={null}
  {
    "ok": true
  }
  ```

  ```json Python theme={null}
  None
  ```

  ```json Ruby theme={null}
  # Coming soon!
  ```

  ```json PHP theme={null}
  void
  ```

  ```json C# theme={null}
  void
  ```
</CodeGroup>


# Creating and Encoding Card Access Methods
Source: https://docs.seam.co/low-level-apis/access-systems/working-with-card-encoders-and-scanners/creating-and-encoding-card-access-methods

Learn how to create a card access method and then encode this access method onto a plastic card.

<img alt="" />

Some access control systems require encoding a plastic card with the data necessary to enable access. This process involves creating an access grant that requests a card access method with the required access permissions and then using a card encoder to write the access method onto the card.

This process consists of the following basic steps:

1. Create an [Access Grant](/use-cases/granting-access/index) that includes a request for a card access method and identify the ID of the resulting access method.

   See [Create an Access Grant](#1-create-an-access-grant).

2. Use the `/acs/encoders/list` endpoint to retrieve a list of available encoders. Then, choose the encoder that you want to use to write the access method onto the card.\
   See [Retrieve Encoders](#2-retrieve-encoders).

3. Use the `/access_methods/encode` endpoint to encode the access method onto the card, using the encoder that you have chosen.\
   See [Encode the Card](#3-encode-the-card).

4. Confirm that the card was encoded successfully using polling or a [webhook](../../../developer-tools/webhooks).\
   See [Confirm Successful Encoding](#4-confirm-successful-encoding). Also, see a list of [common encoding errors](#common-encoding-errors).

Once you have written an access method to a card, you cannot reuse the access method for another card. That is, you must create a separate access method for each card. However, you can reuse a card by re-encoding the card with a new access method.

***

## 1. **Create an Access Grant**

This example shows how to create a card access method as part of an Access Grant. Note that the `is_encoding_required` property of the resulting access method is `true`, which means that the access method must be encoded onto a card. Further, once you've encoded the access method on to the card, the `is_issued` property changes to `true`, and the `issued_at` property indicates the date and time at which the encoding occurred.

For more details about creating Access Grants, see [Creating an Access Grant](../../../use-cases/granting-access/creating-an-access-grant).

<Tabs>
  <Tab title="JavaScript">
    **Code**

    ```javascript theme={null}
    // Identify the IDs of the entrances to which
    // you want to grant access.
    const entrances = await seam.acs.entrances.list({
      // Use the access system ID that you copied in the previous step.
      acs_system_id: acsSystemId,
    })

    // Create the Access Grant.
    const accessGrant = await seam.accessGrants.create({
      // Create a new user identity to represent your user.
      user_identity: {
        full_name: 'Jane Doe',
        email_address: 'jane.doe@example.com',
        phone_number: '+15555551000',
      },
      // Specify the IDs of the entrances to which you want to grant access.
      acs_entrance_ids: [
        entrances[0].acs_entrance_id,
        entrances[1].acs_entrance_id,
      ],
      // Specify that you want to issue a card access method.
      requested_access_methods: [{ mode: 'card' }],
      // Specify the access schedule.
      starts_at: '2025-08-01T15:00:00.000Z',
      ends_at: '2025-08-04T11:00:00.000Z',
    })
    ```

    **Output**

    ```json theme={null}
    {
      access_grant_id: '6d74aefc-5712-4a8b-82c1-73a51ae60b87',
      user_identity_id: '8cc2633a-54ca-455a-8a2b-77e6a1fc4fee',
      starts_at: '2025-08-01T15:00:00.000Z',
      ends_at: '2025-08-04T11:00:00.000Z'
      instant_key_url: 'https://ik.seam.co/ABCXYZ',
      requested_access_methods: [
        {
          display_name: 'Plastic card',
          mode: 'card',
          // Note the access_method_id of the created card access method.
          created_access_method_ids: ["5f4e3d2c-1b0a-9f8e-7d6c-5b4a3c2d1e0f"],
          created_at: '2025-06-16T16:54:19.946606Z'
        }
      ],
      ...
    }
    ```
  </Tab>

  <Tab title="cURL">
    **Code**

    ```curl theme={null}
    # Identify the IDs of the entrances to which
    # you want to grant access.
    # Use the access system ID that you copied in the previous step.
    mapfile -t entrances < <(
      curl -s --request POST "https://connect.getseam.com/acs/entrances/list" \
        --header "Authorization: Bearer $SEAM_API_KEY" \
        --header "Content-Type: application/json" \
        --data "{\"acs_system_id\": \"$acs_system_id\"}" |
      jq -c '.acs_entrances[]'
    )

    # Create the Access Grant.
    # In this command:
    # - Create a new user identity to represent your user.
    # - Specify the IDs of the entrances to which you want to grant access.
    # - Specify that you want to issue a card access method.
    # - Specify the access schedule.
    access_grant=$(curl --include --request POST "https://connect.getseam.com/access_grants/create" \
      -H "Authorization: Bearer $SEAM_API_KEY" \
      -H 'Content-Type: application/json' \
      -d "{
        \"user_identity\": {
          \"full_name\": \"Jane Doe\",
          \"email_address\": \"jane.doe@example.com\",
          \"phone_number\": \"+15555551000\"
        },
        \"acs_entrance_ids\": [
          \"$(echo ${entrances[0]} | jq -r '.acs_entrance_id')\",
          \"$(echo ${entrances[1]} | jq -r '.acs_entrance_id')\"
        ],
        \"requested_access_methods\": [
          {
            \"mode\": \"card\"
          }
        ],
        \"starts_at\": \"2025-08-01T15:00:00.000Z\",
        \"ends_at\": \"2025-08-04T11:00:00.000Z\"
    }")
    ```

    **Output**

    ```json theme={null}
    {
      "access_grant":{
        "access_grant_id":"6d74aefc-5712-4a8b-82c1-73a51ae60b87",
        "user_identity_id":"8cc2633a-54ca-455a-8a2b-77e6a1fc4fee",
        "starts_at":"2025-08-01T15:00:00.000Z",
        "ends_at":"2025-08-04T11:00:00.000Z"
        "instant_key_url":"https://ik.seam.co/ABCXYZ",
        "requested_access_methods":[
          {
            "display_name":"Plastic Card",
            "mode":"card",
            # Note the access_method_id of the created card access method.
            "created_access_method_ids":["5f4e3d2c-1b0a-9f8e-7d6c-5b4a3c2d1e0f"],
            "created_at":"2025-06-16T16:54:19.946606Z"
          }
        ],
        ...
      },
      "ok":true
    }
    ```
  </Tab>

  <Tab title="Python">
    **Code**

    ```python theme={null}
    # Identify the IDs of the entrances to which
    # you want to grant access.
    entrances = seam.acs.entrances.list(
      # Use the access system ID that you copied in the previous step.
      acs_system_id=acs_system_id
    )

    # Create the Access Grant.
    access_grant = seam.access_grants.create(
      # Create a new user identity to represent your user.
      user_identity={
       "full_name": "Jane Doe",
       "email_address": "jane.doe@example.com",
       "phone_number": "+15555551000"
      },
      # Specify the IDs of the entrances to which you want to grant access.
      acs_entrance_ids=[
        entrances[0].acs_entrance_id,
        entrances[1].acs_entrance_id
      ],

      # Specify that you want to issue a card access method.
      requested_access_methods=[
        {"mode": "card"}
      ],
      # Specify the access schedule.
      starts_at="2025-08-01T15:00:00.000Z",
      ends_at="2025-08-04T11:00:00.000Z"
    )
    ```

    **Output**

    ```python theme={null}
    AccessGrant(
      access_grant_id='6d74aefc-5712-4a8b-82c1-73a51ae60b87',
      user_identity_id='8cc2633a-54ca-455a-8a2b-77e6a1fc4fee',
      starts_at='2025-08-01T15:00:00.000Z',
      ends_at='2025-08-04T11:00:00.000Z',
      instant_key_url='https://ik.seam.co/ABCXYZ',
      requested_access_methods=[
        {
          "display_name": "Plastic Card",
          "mode": "card",
          "created_at": "2025-06-16T16:54:19.946606Z",
          # Note the access_method_id of the created card access method.
          "created_access_method_ids": ["5f4e3d2c-1b0a-9f8e-7d6c-5b4a3c2d1e0f"]
        }
      ],
      ...
    )
    ```
  </Tab>

  <Tab title="Ruby">
    **Code**

    ```ruby theme={null}
    # Identify the IDs of the entrances to which
    # you want to grant access.
    entrances = seam.acs.entrances.list(
      # Use the access system ID that you copied in the previous step.
      acs_system_id: acs_system_id
    )

    # Create the Access Grant.
    access_grant = seam.access_grants.create(
      # Create a new user identity to represent your user.
      user_identity: {
        full_name: "Jane Doe",
        email_address: "jane.doe@example.com",
        phone_number: "+15555551000"
      },
      # Specify the IDs of the entrances to which you want to grant access.
      acs_entrance_ids: [
        entrances[0].acs_entrance_id,
        entrances[1].acs_entrance_id
      ],
      # Specify that you want to issue a card access method.
      requested_access_methods: [
        { mode: "card" }
      ],
      # Specify the access schedule.
      starts_at: "2025-08-01T15:00:00.000Z",
      ends_at: "2025-08-04T11:00:00.000Z"
    )
    ```

    **Output**

    ```ruby theme={null}
    <Seam::Resources::AccessGrant:0x005f0
      access_grant_id="6d74aefc-5712-4a8b-82c1-73a51ae60b87"
      user_identity_id="8cc2633a-54ca-455a-8a2b-77e6a1fc4fee"
      starts_at=2025-08-01 15:00:00 UTC
      ends_at=2025-08-04 11:00:00 UTC
      instant_key_url="https://ik.seam.co/ABCXYZ"
      requested_access_methods=[
        {
          "display_name"=>"Plastic card",
          "mode"=>"card",
          # Note the access_method_id of the created card access method.
          "created_access_method_ids"=>["5f4e3d2c-1b0a-9f8e-7d6c-5b4a3c2d1e0f"],
          "created_at"=>"2025-06-16T16:54:19.946606Z"
        }
      ]
      ...
    >
    ```
  </Tab>

  <Tab title="PHP">
    **Code**

    ```php theme={null}
    // Identify the IDs of the entrances to which
    // you want to grant access.
    $entrances = $seam->acs->entrances->list(
      // Use the access system ID that you copied in the previous step.
      acs_system_id: $acs_system_id
    );

    // Create the Access Grant.
    $access_grant = $seam->access_grants->create(
      // Create a new user identity to represent your user.
      user_identity: [
        "full_name" => "Jane Doe",
        "email_address" => "jane.doe@example.com",
        "phone_number" => "+15555551000"
      ],
      // Specify the IDs of the entrances to which you want to grant access.
      acs_entrance_ids: [
        $entrances[0]->acs_entrance_id,
        $entrances[1]->acs_entrance_id
      ],
      // Specify that you want to issue a card access method.
      requested_access_methods: [
        ["mode" => "card"]
      ],
      // Specify the access schedule.
      starts_at: '2025-08-01T15:00:00.000Z',
      ends_at: '2025-08-04T11:00:00.000Z'
    );
    ```

    **Output**

    ```php theme={null}
    {
      "access_grant_id":"6d74aefc-5712-4a8b-82c1-73a51ae60b87",
      "user_identity_id":"8cc2633a-54ca-455a-8a2b-77e6a1fc4fee",
      "starts_at":"2025-08-01T15:00:00.000Z",
      "ends_at":"2025-08-04T11:00:00.000Z"
      "instant_key_url":"https://ik.seam.co/ABCXYZ",
      "requested_access_methods":[
        {
          "display_name":"Plastic Card",
          "mode":"card",
          // Note the access_method_id of the created card access method.
          "created_access_method_ids":["5f4e3d2c-1b0a-9f8e-7d6c-5b4a3c2d1e0f"],
          "created_at":"2025-06-16T16:54:19.946606Z"
        }
      ],
      ...
    }
    ```
  </Tab>

  <Tab title="C#">
    **Code**

    ```csharp theme={null}
    // Coming soon!
    ```

    **Output**

    ```json theme={null}
    // Coming soon!
    ```
  </Tab>
</Tabs>

***

## 2. Retrieve Encoders

There may be multiple encoders at a location, so it’s important to select the right one to encode the credential.

This example shows how to retrieve all encoders in a building connected to a single access system. Once you've identified the encoder you'd like to use, save the `acs_encoder_id` of the chosen encoder for the next step.

**Code:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  await seam.acs.encoders.list({
    acs_system_ids: [buildingSystemId],
  })
  ```

  ```bash cURL theme={null}
  curl -X 'POST' \
    'https://connect.getseam.com/acs/encoders/list' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d "{
    \"acs_system_ids\": [\"${building_system_id}\"]
  }"
  ```

  ```python Python theme={null}
  seam.acs.encoders.list(
    acs_system_ids = [building_system_id]
  )
  ```

  ```ruby Ruby theme={null}
  seam.acs.encoders.list(
    acs_system_ids: [building_system_id]
  )
  ```

  ```php PHP theme={null}
  $seam->acs->encoders->list(
    acs_system_ids: [building_system_id]
  );
  ```

  ```csharp C# theme={null}
  // Coming Soon!
  ```
</CodeGroup>

**Output:**

<CodeGroup>
  ```json JavaScript theme={null}
  [
    {
      acs_encoder_id: '33333333-4444-5555-6666-777777777777',
      display_name: 'Front Desk',
      ...
    },
    ...
  ]
  ```

  ```json cURL theme={null}
  {
    "acs_encoders": [
      {
        "acs_encoder_id": "33333333-4444-5555-6666-777777777777",
        "display_name": "Front Desk",
        ...
      },
      ...
    ],
    "ok": true
  }
  ```

  ```json Python theme={null}
  [
    AcsEncoder(
      acs_encoder_id='33333333-4444-5555-6666-777777777777',
      display_name='Front Desk',
      ...
    )
    ...
  ]
  ```

  ```json Ruby theme={null}
  [
    <Seam::Resources::AcsEncoder:0x00410
      acs_encoder_id="33333333-4444-5555-6666-777777777777"
      display_name="Front Desk"
      ...
    >,
    ...
  ]
  ```

  ```json PHP theme={null}
  [
    {
      "acs_encoder_id": "33333333-4444-5555-6666-777777777777",
      "display_name": "Front Desk",
      ...
    },
    ...
  ]
  ```

  ```json C# theme={null}
  // Coming Soon!
  ```
</CodeGroup>

***

## 3. Encode the Card

Use `/acs/encoders/encode_credential` to start the card writing procedure that stores the access method data on the plastic key card.

**Code:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  const encodingActionAttempt = await seam.accessMethods.encode({
    access_method_id: accessMethodId,
    acs_encoder_id: encoder.acs_encoder_id,
  })
  ```

  ```bash cURL theme={null}
  encoding_action_attempt=$(curl -X 'POST' \
    'https://connect.getseam.com/access_methods/encode' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d "{
    \"access_method_id\": \"${access_method_id}",
    \"acs_encoder_id\": \"${acs_encoder_id}\"
  }")
  ```

  ```python Python theme={null}
  encoding_action_attempt = seam.access_methods.encode(
    access_method_id = access_method_id,
    acs_encoder_id = encoder.acs_encoder_id
  )
  ```

  ```ruby Ruby theme={null}
  encoding_action_attempt = seam.access_methods.encode(
    access_method_id: access_method_id,
    acs_encoder_id: encoder.acs_encoder_id
  )
  ```

  ```php PHP theme={null}
  $encoding_action_attempt = $seam->access_methods->encode(
    acs_credential_id: $access_method_id,
    acs_encoder_id: $encoder->acs_encoder_id
  );
  ```

  ```csharp C# theme={null}
  // Coming Soon!
  ```
</CodeGroup>

**Output:**

<CodeGroup>
  ```json JavaScript theme={null}
  {
    status: 'pending',
    action_attempt_id: '11111111-2222-3333-4444-555555555555",
    action_type: 'ENCODE_ACCESS_METHOD',
    result: null,
    error: null
  }
  ```

  ```json cURL theme={null}
  {
    "action_attempt": {
      "status": "pending",
      "action_attempt_id": "11111111-2222-3333-4444-555555555555",
      "action_type": "ENCODE_ACCESS_METHOD",
      "result": null,
      "error": null
    },
    "ok": true
  }
  ```

  ```json Python theme={null}
  ActionAttempt(
    status='pending',
    action_attempt_id='11111111-2222-3333-4444-555555555555',
    action_type='ENCODE_ACCESS_METHOD',
    result=null,
    error=null
  )
  ```

  ```json Ruby theme={null}
  <Seam::Resources::ActionAttempt:0x00410
    status="pending"
    action_attempt_id="11111111-2222-3333-4444-555555555555"
    action_type="ENCODE_ACCESS_METHOD"
    result=nil
    error=nil
  >
  ```

  ```json PHP theme={null}
  {
    "status": "pending",
    "action_attempt_id": "11111111-2222-3333-4444-555555555555",
    "action_type": "ENCODE_ACCESS_METHOD",
    "result": null,
    "error": null
  }
  ```

  ```json C# theme={null}
  // Coming Soon!
  ```
</CodeGroup>

***

## 4. Confirm Successful Encoding

Once you issue a request to encode the access method onto the card, it is important to confirm that the encoding process completes successfully. You can use polling or a [webhook](../../../developer-tools/webhooks).

### Confirm Successful Encoding by Polling

When you make an `/access_methods/encode` request, Seam returns an [action attempt](../../../core-concepts/action-attempts). To confirm that the card encoding was successful, you can poll this action attempt, until its `status` becomes `success`.

**Code:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  await seam.actionAttempts.get({
    action_attempt_id: encodingActionAttempt.action_attempt_id,
  })
  ```

  ```bash cURL theme={null}
  curl -X 'POST' \
    'https://connect.getseam.com/action_attempts/get' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d "{
    \"action_attempt_id\": \"$(jq -r '.action_attempt.action_attempt_id' <<< ${encoding_action_attempt})\"
  }"
  ```

  ```python Python theme={null}
  seam.action_attempts.get(
    action_attempt_id = encoding_action_attempt.action_attempt_id
  )
  ```

  ```ruby Ruby theme={null}
  seam.action_attempts.get(
    action_attempt_id: encoding_action_attempt.action_attempt_id
  )
  ```

  ```php PHP theme={null}
  $seam->action_attempts->get(
    action_attempt_id: $encoding_action_attempt->action_attempt_id
  );
  ```

  ```csharp C# theme={null}
  // Coming Soon!
  ```
</CodeGroup>

**Output:**

<CodeGroup>
  ```json JavaScript theme={null}
  {
    status: 'success',
    action_attempt_id: '11111111-2222-3333-4444-555555555555",
    action_type: 'ENCODE_ACCESS_METHOD',
    result: {
      access_method_id: "5f4e3d2c-1b0a-9f8e-7d6c-5b4a3c2d1e0f',
      card_number: '1234abc',
      is_issued: true,
      issued_at: '2025-06-16T16:56:00.000000Z',
      ...
    },
    error: null
  }
  ```

  ```json cURL theme={null}
  {
    "action_attempt":
      {
        "status": "success",
        "action_attempt_id": "11111111-2222-3333-4444-555555555555",
        "action_type": "ENCODE_ACCESS_METHOD",
        "result": {
          "access_method_id": "5f4e3d2c-1b0a-9f8e-7d6c-5b4a3c2d1e0f",
          "card_number": "1234abc",
          "is_issued": true,
          "issued_at": "2025-06-16T16:56:00.000000Z",
          ...
        },
        "error": null
      },
    "ok": true
  }
  ```

  ```json Python theme={null}
  ActionAttempt(
    status='success',
    action_attempt_id='11111111-2222-3333-4444-555555555555',
    action_type='ENCODE_ACCESS_METHOD',
    result={
      access_method_id='5f4e3d2c-1b0a-9f8e-7d6c-5b4a3c2d1e0f',
      card_number='1234abc',
      is_issued=True,
      issued_at='2025-06-16T16:56:00.000000Z',
      ...
    },
    error=null
  )
  ```

  ```json Ruby theme={null}
  <Seam::Resources::ActionAttempt:0x00410
    status="success"
    action_attempt_id="11111111-2222-3333-4444-555555555555"
    action_type="ENCODE_ACCESS_METHOD"
    result={
      access_method_id="5f4e3d2c-1b0a-9f8e-7d6c-5b4a3c2d1e0f"
      card_number="1234abc"
      is_issued=true,
      issued_at="2025-06-16T16:56:00.000000Z"
      ...
    }
    error=nil
  >
  ```

  ```json PHP theme={null}
  {
    "status": "success",
    "action_attempt_id": "11111111-2222-3333-4444-555555555555",
    "action_type": "ENCODE_ACCESS_METHOD",
    "result": {
      "access_method_id": "5f4e3d2c-1b0a-9f8e-7d6c-5b4a3c2d1e0f",
      "card_number": "1234abc",
      "is_issued": true,
      "issued_at": "2025-06-16T16:56:00.000000Z",
      ...
    },
    "error": null
  }
  ```

  ```json C# theme={null}
  // Coming Soon!
  ```
</CodeGroup>

#### View Access Method Properties

It is also useful to note that Seam assigns values to various card-related properties on the access method when the encoder has finished encoding the card. For example, `access_method.issued_at` receives a value. You can retrieve the access method to view these properties.

<Tabs>
  <Tab title="JavaScript">
    **Code**

    ```javascript theme={null}
    await seam.accessMethods.get({
      access_method_id: accessMethodId,
    })
    ```

    **Output**

    ```javascript theme={null}
    {
      "access_method_id": "5f4e3d2c-1b0a-9f8e-7d6c-5b4a3c2d1e0f",
      "issued_at": "2025-06-16T16:56:00.000000Z",
      ...
    }
    ```
  </Tab>

  <Tab title="cURL">
    **Code**

    ```curl theme={null}
    curl -X 'POST' \
      'https://connect.getseam.com/access_methods/get' \
      -H 'accept: application/json' \
      -H "Authorization: Bearer ${SEAM_API_KEY}" \
      -H 'Content-Type: application/json' \
      -d "{
      \"access_method_id\": \"${access_method_id}\"
    }"
    ```

    **Output**

    ```curl theme={null}
    {
      "access_method": {
        "access_method_id": "5f4e3d2c-1b0a-9f8e-7d6c-5b4a3c2d1e0f",
        "issued_at": "2025-06-16T16:56:00.000000Z",
        ...
      },
      ok: true
    }
    ```
  </Tab>

  <Tab title="Python">
    **Code**

    ```python theme={null}
    seam.access_methods.get(
      access_method_id=access_method_id
    )
    ```

    **Output**

    ```python theme={null}
    AccessMethod(
      access_method_id='5f4e3d2c-1b0a-9f8e-7d6c-5b4a3c2d1e0f',
      issued_at='2025-06-16T16:56:00.000000Z',
      ...
    )
    ```
  </Tab>

  <Tab title="Ruby">
    **Code**

    ```ruby theme={null}
    seam.access_methods.get(
      access_method_id: access_method_id
    )
    ```

    **Output**

    ```ruby theme={null}
    {
      "access_method_id" => "5f4e3d2c-1b0a-9f8e-7d6c-5b4a3c2d1e0f",
      "issued_at" => "2025-06-16T16:56:00.000000Z",
      ...
    }
    ```
  </Tab>

  <Tab title="PHP">
    **Code**

    ```php theme={null}
    $seam->access_methods->get(
        access_method_id: $access_method_id
    );
    ```

    **Output**

    ```php theme={null}
    [
      "access_method_id": "5f4e3d2c-1b0a-9f8e-7d6c-5b4a3c2d1e0f",
      "issued_at": "2025-06-16T16:56:00.000000Z",
      ...
    ];
    ```
  </Tab>

  <Tab title="C#">
    **Code:**

    ```csharp theme={null}
    // Coming Soon!
    ```

    **Output:**

    ```json theme={null}
    // Coming Soon!
    ```
  </Tab>
</Tabs>

***

### Confirm Successful Encoding by Using a Webhook

To confirm successful encoding, you can use a [webhook](../../../developer-tools/webhooks) to listen for an `access_method.issued` event that contains the `access_method_id` in the payload. If you are re-encoding a card, listen for `access_method.reissued` instead of `access_method.issued`.

```json theme={null}
{
  "event_id": "22222222-3333-4444-5555-666666666666",
  "event_description": "An access method was issued.",
  "event_type": "access_method.issued",
  "workspace_id": "00000000-0000-0000-0000-000000000000",
  "created_at": "2025-06-16T16:56:00.000000Z",
  "occurred_at": "2025-06-16T16:56:00.000000Z",
  "acs_system_id": "11111111-1111-1111-1111-111111111111",
  "access_method_id": "5f4e3d2c-1b0a-9f8e-7d6c-5b4a3c2d1e0f",
  "connected_account_id": "11111111-1111-1111-1111-222222222222"
}
```

***

## Common Encoding Errors

<table>
  <thead>
    <tr>
      <th>Error</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        <code>no\_card\_on\_encoder</code>
      </td>

      <td>No card was placed on the encoder.</td>
    </tr>

    <tr>
      <td>
        <code>incompatible\_card\_format</code>
      </td>

      <td>
        A card with an incompatible card format was placed on the encoder.
      </td>
    </tr>

    <tr>
      <td>
        <code>uncategorized\_error</code>
      </td>

      <td>Any other encoding error.</td>
    </tr>
  </tbody>
</table>


# Creating and Encoding Card-based Credentials
Source: https://docs.seam.co/low-level-apis/access-systems/working-with-card-encoders-and-scanners/creating-and-encoding-card-based-credentials

Learn how to create a card-based credential and then encode this credential onto a plastic card.

<img alt="" />

Some access control systems require encoding a plastic card with the data necessary to enable access. This process involves creating a credential with the required access permissions and then using a card encoder to write the credential onto the card.

This process consists of the following basic steps:

1. Set up an [access system user](../../../low-level-apis/access-systems/user-management) and create a [credential](../managing-credentials#create-a-card-based-credential) with the `access_method` set to `card`.\
   See the [system integration guide](/device-and-system-integration-guides#access-control-systems) for your access system provider to learn specific requirements, such as configuring entrances and access schedules.\
   See [Set Up an Access System User and Card Credential](#1-set-up-an-access-system-user-and-card-credential).
2. Use the `/acs/encoders/list` endpoint to retrieve a list of available encoders. Then, choose the encoder that you want to use to write the credential onto the card.\
   See [Retrieve Encoders](#2-retrieve-encoders).
3. Use the `/acs/encoders/encode_credential` endpoint to encode the credential onto the card, using the encoder that you have chosen.\
   See [Encode the Card](#3-encode-the-card).
4. Confirm that the card was encoded successfully using polling or a [webhook](../../../developer-tools/webhooks).\
   See [Confirm Successful Encoding](#4-confirm-successful-encoding). Also, see a list of [common encoding errors](#common-encoding-errors).

Once you have written a credential to a card, you cannot reuse the credential for another card. That is, you must create a separate credential for each card. However, you can reuse a card by re-encoding the card with a new credential.

***

## 1. **Set Up an Access System User and Card Credential**

This example shows how to create an access system user and card-based credential. Note that the `is_issued` property of the resulting credential is `false`, which means that the credential is ready to be written to a card and has not yet been used to encode a card.

<Info>
  Depending on your specific access control system, creating an access system
  user or credential may require additional parameters. For details, see the
  [system integration
  guide](/device-and-system-integration-guides#access-control-systems)
  for your access system.
</Info>

**Code:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  // Step 1:
  // Create the new access system user.
  const acsUser = await seam.acs.users.create({
    acs_system_id: '11111111-1111-1111-1111-111111111111',
    full_name: 'Jane Doe',
    email_address: 'jane@example.com',
  })

  // Step 2:
  // Create a card-based credential for each entrance for the access system user.
  const credential = await seam.acs.credentials.create({
    acs_user_id: acsUser.acs_user_id,
    access_method: 'card',
    allowed_acs_entrance_ids: [
      // List the IDs of the entrances to which
      // you want to grant access.
      room101.seam_acs_entrance_id,
    ],
    starts_at: '2024-12-01T15:00:00.000Z',
    ends_at: '2024-12-04T12:00:00.000Z',
  })
  ```

  ```bash cURL theme={null}
  # Step 1:
  # Create the new access system user.
  acs_user=$(curl -X 'POST' \
    'https://connect.getseam.com/acs/users/create' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d "{
    \"acs_system_id\": \"11111111-1111-1111-1111-111111111111\",
    \"full_name\": \"Jane Doe\",
    \"email_address\": \"jane@example.com\"
  }")

  # Step 2:
  # Create a card-based credential for each entrance for the access system user.
  # In allowed_entrance_ids, list the IDs of the entrances to
  # which you want to grant access.
  credential=$(curl -X 'POST' \
    'https://connect.getseam.com/acs/credentials/create' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d "{
    \"acs_user_id\": \"$(jq -r '.acs_user.acs_user_id' <<< ${acs_user})\",
    \"access_method\": \"card\",
    \"allowed_acs_entrance_ids\": [
      \"${entrance_id}\"
    ],
    \"starts_at\": \"2024-12-01T15:00:00.000Z\",
    \"ends_at\": \"2024-12-04T12:00:00.000Z\"
  }")
  ```

  ```python Python theme={null}
  # Step 1:
  # Create the new access system user.
  acs_user = seam.acs.users.create(
    acs_system_id = "11111111-1111-1111-1111-111111111111",
    full_name = "Jane Doe",
    email_address = "jane@example.com"
  )

  # Step 2:
  # Create a card-based credential for each entrance for the access system user.
  credential = seam.acs.credentials.create(
    acs_user_id = acs_user.acs_user_id,
    access_method = "card",
    # List the IDs of the entrances to which
    # you want to grant access.
    allowed_acs_entrance_ids = [
      room_101.seam_acs_entrance_id
    ],
    starts_at = "2024-12-01T15:00:00.000Z",
    ends_at = "2024-12-04T12:00:00.000Z"
  )
  ```

  ```ruby Ruby theme={null}
  # Step 1:
  # Create the new access system user.
  acs_user = seam.acs.users.create(
    acs_system_id: "11111111-1111-1111-1111-111111111111",
    full_name: "Jane Doe",
    email_address: "jane@example.com"
  )

  # Step 2:
  # Create a card-based credential for each entrance for the access system user.
  credential = seam.acs.credentials.create(
    acs_user_id: acs_user.acs_user_id,
    access_method: "card",
    # List the IDs of the entrances to which
    # you want to grant access.
    allowed_acs_entrance_ids: [
      room_101.seam_acs_entrance_id
    ],
    starts_at: "2024-12-01T15:00:00.000Z",
    ends_at: "2024-12-04T12:00:00.000Z"
  )
  ```

  ```php PHP theme={null}
  // Step 1:
  // Create the new access system user.
  $acs_user = $seam->acs->users->create(
    acs_system_id: "11111111-1111-1111-1111-111111111111",
    full_name: "Jane Doe",
    email_address: "jane@example.com"
  );

  // Step 2:
  // Create a card-based credential for each entrance for the access system user.
  $credential = $seam->acs->credentials->create(
    acs_user_id: $acs_user->acs_user_id,
    access_method: "card",
    allowed_acs_entrance_ids: [
      // List the IDs of the entrances to which
      // you want to grant access.
      $room_101->seam_acs_entrance_id
    ],
    starts_at: "2024-12-01T15:00:00.000Z",
    ends_at: "2024-12-04T12:00:00.000Z"
  );
  ```

  ```csharp C# theme={null}
  // Step 1:
  // Create the new access system user.
  AcsUser acsUser = seam.UsersAcs.Create(
    acsSystemId: "11111111-1111-1111-1111-111111111111",
    fullName: "Jane Doe",
    emailAddress: "jane@example.com"
  );

  // Step 2:
  // Create a card-based credential for each entrance for the access system user.
  AcsCredential credential = seam.CredentialsAcs.Create(
    acsUserId: acsUser.acsUserId,
    accessMethod: "card",
    allowedAcsEntranceIds: new List<string>
    {
      // List the IDs of the entrances to which
      // you want to grant access.
      room_101.acsEntranceId
    },
    startsAt: "2024-12-01T15:00:00.000Z",
    endsAt: "2024-12-04T12:00:00.000Z"
  );
  ```
</CodeGroup>

**Output:**

<CodeGroup>
  ```json JavaScript theme={null}
  {
    acs_credential_id: '66666666-6666-6666-6666-666666666666',
    acs_user_id: '33333333-3333-3333-3333-333333333333',
    access_method: 'card',
    starts_at: '2024-12-01T15:00:00.000Z',
    ends_at: '2024-12-04T12:00:00.000Z',
    is_issued: false,
    ...
  }
  ```

  ```json cURL theme={null}
  {
    "acs_credential":
      {
        "acs_credential_id": "66666666-6666-6666-6666-666666666666",
        "acs_user_id": "33333333-3333-3333-3333-333333333333",
        "access_method": "card",
        "starts_at": "2024-12-01T15:00:00.000Z",
        "ends_at": "2024-12-04T12:00:00.000Z",
        "is_issued": false,
        ...
      },
    "ok":true
  }
  ```

  ```json Python theme={null}
  AcsCredential(
    acs_credential_id='66666666-6666-6666-6666-666666666666',
    acs_user_id='33333333-3333-3333-3333-333333333333',
    access_method='card',
    starts_at='2024-12-01T15:00:00.000Z',
    ends_at='2024-12-04T12:00:00.000Z',
    is_issued=False
    ...
  )
  ```

  ```json Ruby theme={null}
  <Seam::Resources::AcsCredential:0x00410
    acs_credential_id="66666666-6666-6666-6666-666666666666"
    acs_user_id="33333333-3333-3333-3333-333333333333"
    access_method="card"
    starts_at="2024-12-01T15:00:00.000Z"
    ends_at="2024-12-04T12:00:00.000Z"
    is_issued=false
    ...
  >
  ```

  ```json PHP theme={null}
  {
    "acs_credential_id": "66666666-6666-6666-6666-666666666666",
    "acs_user_id": "33333333-3333-3333-3333-333333333333",
    "access_method": "card",
    "starts_at": "2024-12-01T15:00:00.000Z",
    "ends_at": "2024-12-04T12:00:00.000Z",
    "is_issued": false,
    ...
  }
  ```

  ```json C# theme={null}
  {
    "acs_credential_id": "66666666-6666-6666-6666-666666666666",
    "acs_user_id": "33333333-3333-3333-3333-333333333333",
    "access_method": "card",
    "starts_at": "2024-12-01T15:00:00Z",
    "ends_at": "2024-12-04T12:00:00Z",
    "is_issued": false,
    ...
  }
  ```
</CodeGroup>

***

## 2. Retrieve Encoders

There may be multiple encoders at a location, so it’s important to select the right one to encode the credential.

This example shows how to retrieve all encoders in a building connected to a single access system. Once you've identified the encoder you'd like to use, save the `acs_encoder_id` of the chosen encoder for the next step.

**Code:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  await seam.acs.encoders.list({
    acs_system_ids: [buildingSystemId],
  })
  ```

  ```bash cURL theme={null}
  curl -X 'POST' \
    'https://connect.getseam.com/acs/encoders/list' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d "{
    \"acs_system_ids\": [\"${building_system_id}\"]
  }"
  ```

  ```python Python theme={null}
  seam.acs.encoders.list(
    acs_system_ids = [building_system_id]
  )
  ```

  ```ruby Ruby theme={null}
  seam.acs.encoders.list(
    acs_system_ids: [building_system_id]
  )
  ```

  ```php PHP theme={null}
  $seam->acs->encoders->list(
    acs_system_ids: [building_system_id]
  );
  ```

  ```csharp C# theme={null}
  seam.EncodersAcs.List(
    acsSystemIds: new List<string>
    {
      buildingSystemId
    }
  );
  ```
</CodeGroup>

**Output:**

<CodeGroup>
  ```json JavaScript theme={null}
  [
    {
      acs_encoder_id: '33333333-4444-5555-6666-777777777777',
      display_name: 'Front Desk',
      ...
    },
    ...
  ]
  ```

  ```json cURL theme={null}
  {
    "acs_encoders": [
      {
        "acs_encoder_id": "33333333-4444-5555-6666-777777777777",
        "display_name": "Front Desk",
        ...
      },
      ...
    ],
    "ok": true
  }
  ```

  ```json Python theme={null}
  [
    AcsEncoder(
      acs_encoder_id='33333333-4444-5555-6666-777777777777',
      display_name='Front Desk',
      ...
    )
    ...
  ]
  ```

  ```json Ruby theme={null}
  [
    <Seam::Resources::AcsEncoder:0x00410
      acs_encoder_id="33333333-4444-5555-6666-777777777777"
      display_name="Front Desk"
      ...
    >,
    ...
  ]
  ```

  ```json PHP theme={null}
  [
    {
      "acs_encoder_id": "33333333-4444-5555-6666-777777777777",
      "display_name": "Front Desk",
      ...
    },
    ...
  ]
  ```

  ```json C# theme={null}
  {
    "acs_encoder_id": "33333333-4444-5555-6666-777777777777",
    "display_name": "Front Desk",
    ...
  }
  ...
  ```
</CodeGroup>

***

## 3. Encode the Card

Use `/acs/encoders/encode_credential` to start the card writing procedure that stores the credential data on the plastic key card.

**Code:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  const encodingActionAttempt = await seam.acs.encoders.encodeCredential({
    acs_credential_id: credential.acs_credential_id,
    acs_encoder_id: encoder.acs_encoder_id,
  })
  ```

  ```bash cURL theme={null}
  encoding_action_attempt=$(curl -X 'POST' \
    'https://connect.getseam.com/acs/encoders/encode_credential' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d "{
    \"acs_credential_id\": \"$(jq -r '.acs_credential.acs_credential_id' <<< ${credential})\",
    \"acs_encoder_id\": \"${acs_encoder_id}\"
  }")
  ```

  ```python Python theme={null}
  encoding_action_attempt = seam.acs.encoders.encode_credential(
    acs_credential_id = credential.acs_credential_id,
    acs_encoder_id = encoder.acs_encoder_id
  )
  ```

  ```ruby Ruby theme={null}
  encoding_action_attempt = seam.acs.encoders.encode_credential(
    acs_credential_id: credential.acs_credential_id,
    acs_encoder_id: encoder.acs_encoder_id
  )
  ```

  ```php PHP theme={null}
  $encoding_action_attempt = $seam->acs->encoders->encode_credential(
    acs_credential_id: $credential->acs_credential_id,
    acs_encoder_id: $encoder->acs_encoder_id
  );
  ```

  ```csharp C# theme={null}
  actionAttempt encodingActionAttempt = seam.EncodersAcs.EncodeCredential(
    acsCredentialId: credential.acsCredentialId,
    acsEncoderId: encoder.acsEncoderId
  );
  ```
</CodeGroup>

**Output:**

<CodeGroup>
  ```json JavaScript theme={null}
  {
    status: 'pending',
    action_attempt_id: '11111111-2222-3333-4444-555555555555",
    action_type: 'ENCODE_CREDENTIAL',
    result: null,
    error: null
  }
  ```

  ```json cURL theme={null}
  {
    "action_attempt": {
      "status": "pending",
      "action_attempt_id": "11111111-2222-3333-4444-555555555555",
      "action_type": "ENCODE_CREDENTIAL",
      "result": null,
      "error": null
    },
    "ok": true
  }
  ```

  ```json Python theme={null}
  ActionAttempt(
    status='pending',
    action_attempt_id='11111111-2222-3333-4444-555555555555',
    action_type='ENCODE_CREDENTIAL',
    result=null,
    error=null
  )
  ```

  ```json Ruby theme={null}
  <Seam::Resources::ActionAttempt:0x00410
    status="pending"
    action_attempt_id="11111111-2222-3333-4444-555555555555"
    action_type="ENCODE_CREDENTIAL"
    result=nil
    error=nil
  >
  ```

  ```json PHP theme={null}
  {
    "status": "pending",
    "action_attempt_id": "11111111-2222-3333-4444-555555555555",
    "action_type": "ENCODE_CREDENTIAL",
    "result": null,
    "error": null
  }
  ```

  ```json C# theme={null}
  {
    "status": "pending",
    "action_attempt_id": "11111111-2222-3333-4444-555555555555",
    "action_type": "ENCODE_CREDENTIAL",
    "result": null,
    "error": null
  }
  ```
</CodeGroup>

***

## 4. Confirm Successful Encoding

Once you issue a request to encode the credential onto the card, it is important to confirm that the encoding process completes successfully. You can use polling or a [webhook](../../../developer-tools/webhooks).

### Confirm Successful Encoding by Polling

When you make an `/acs/encoders/encode_credential` request, Seam returns an [action attempt](../../../core-concepts/action-attempts). To confirm that the card encoding was successful, you can poll this action attempt, until its `status` becomes `success`.

**Code:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  await seam.actionAttempts.get({
    action_attempt_id: encodingActionAttempt.action_attempt_id,
  })
  ```

  ```bash cURL theme={null}
  curl -X 'POST' \
    'https://connect.getseam.com/action_attempts/get' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d "{
    \"action_attempt_id\": \"$(jq -r '.action_attempt.action_attempt_id' <<< ${encoding_action_attempt})\"
  }"
  ```

  ```python Python theme={null}
  seam.action_attempts.get(
    action_attempt_id = encoding_action_attempt.action_attempt_id
  )
  ```

  ```ruby Ruby theme={null}
  seam.action_attempts.get(
    action_attempt_id: encoding_action_attempt.action_attempt_id
  )
  ```

  ```php PHP theme={null}
  $seam->action_attempts->get(
    action_attempt_id: $encoding_action_attempt->action_attempt_id
  );
  ```

  ```csharp C# theme={null}
  seam.ActionAttempts.Get(
    actionAttemptId: encodingActionAttempt.actionAttemptId
  );
  ```
</CodeGroup>

**Output:**

<CodeGroup>
  ```json JavaScript theme={null}
  {
    status: 'success',
    action_attempt_id: '11111111-2222-3333-4444-555555555555",
    action_type: 'ENCODE_CREDENTIAL',
    result: {
      acs_credential_id: "66666666-6666-6666-6666-666666666666',
      card_number: '1234abc',
      is_issued: true,
      issued_at: '2024-10-23T19:46:06.113Z',
      ...
    },
    error: null
  }
  ```

  ```json cURL theme={null}
  {
    "action_attempt":
      {
        "status": "success",
        "action_attempt_id": "11111111-2222-3333-4444-555555555555",
        "action_type": "ENCODE_CREDENTIAL",
        "result": {
          "acs_credential_id": "66666666-6666-6666-6666-666666666666",
          "card_number": "1234abc",
          "is_issued": true,
          "issued_at": "2024-10-23T19:46:06.113Z",
          ...
        },
        "error": null
      },
    "ok": true
  }
  ```

  ```json Python theme={null}
  ActionAttempt(
    status='success',
    action_attempt_id='11111111-2222-3333-4444-555555555555',
    action_type='ENCODE_CREDENTIAL',
    result={
      acs_credential_id='66666666-6666-6666-6666-666666666666',
      card_number='1234abc',
      is_issued=True,
      issued_at='2024-10-23T19:46:06.113Z',
      ...
    },
    error=null
  )
  ```

  ```json Ruby theme={null}
  <Seam::Resources::ActionAttempt:0x00410
    status="success"
    action_attempt_id="11111111-2222-3333-4444-555555555555"
    action_type="ENCODE_CREDENTIAL"
    result={
      acs_credential_id="66666666-6666-6666-6666-666666666666"
      card_number="1234abc"
      is_issued=true,
      issued_at="2024-10-23T19:46:06.113Z"
      ...
    }
    error=nil
  >
  ```

  ```json PHP theme={null}
  {
    "status": "success",
    "action_attempt_id": "11111111-2222-3333-4444-555555555555",
    "action_type": "ENCODE_CREDENTIAL",
    "result": {
      "acs_credential_id": "66666666-6666-6666-6666-666666666666",
      "card_number": "1234abc",
      "is_issued": true,
      "issued_at": "2024-10-23T19:46:06.113Z",
      ...
    },
    "error": null
  }
  ```

  ```json C# theme={null}
  {
    "status": "success",
    "action_attempt_id": "11111111-2222-3333-4444-555555555555",
    "action_type": "ENCODE_CREDENTIAL",
    "result": {
      "acs_credential_id": "66666666-6666-6666-6666-666666666666",
      "card_number": "1234abc",
      "is_issued": true,
      "issued_at": "2024-10-23T19:46:06.113Z",
      ...
    },
    "error": null
  }
  ```
</CodeGroup>

#### View Credential Properties

It is also useful to note that Seam assigns values to various card-related properties on the credential when the encoder has finished encoding the card. For example, `acs_credential.is_issued` becomes `true`, and `acs_credential.card_number` and `acs_credential.issued_at` receive values. You can retrieve the credential to view these properties.

**Code:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  await seam.acs.credentials.get({
    acs_credential_id: credential.acs_credential_id,
  })
  ```

  ```bash cURL theme={null}
  curl -X 'POST' \
    'https://connect.getseam.com/acs/credentials/get' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d "{
    \"acs_credential_id\": \"$(jq -r '.acs_credential.acs_credential_id' <<< ${credential})\"
  }"
  ```

  ```python Python theme={null}
  seam.acs.credentials.get(
    acs_credential_id = credential.acs_credential_id
  )
  ```

  ```ruby Ruby theme={null}
  seam.acs.credentials.get(
    acs_credential_id: credential.acs_credential_id
  )
  ```

  ```php PHP theme={null}
  $seam->acs->credentials->get(
    acs_credential_id: $credential->acs_credential_id
  );
  ```

  ```csharp C# theme={null}
  seam.CredentialsAcs.Get(
    acsCredentialId: credential.acsCredentialId
  );
  ```
</CodeGroup>

**Output:**

<CodeGroup>
  ```json JavaScript theme={null}
  {
    acs_credential_id: '66666666-6666-6666-6666-666666666666',
    acs_user_id: '33333333-3333-3333-3333-333333333333',
    access_method: 'card',
    starts_at: '2024-12-01T15:00:00.000Z',
    ends_at: '2024-12-04T12:00:00.000Z',
    is_issued: true,
    card_number: '1234abc',
    issued_at: '2024-10-23T19:46:06.113Z',
    ...
  }
  ```

  ```json cURL theme={null}
  {
    "acs_credential":
      {
        "acs_credential_id": "66666666-6666-6666-6666-666666666666",
        "acs_user_id": "33333333-3333-3333-3333-333333333333",
        "access_method": "card",
        "starts_at": "2024-12-01T15:00:00.000Z",
        "ends_at": "2024-12-04T12:00:00.000Z",
        "is_issued": true,
        "card_number": "1234abc",
        "issued_at": "2024-10-23T19:46:06.113Z",
        ...
      },
    "ok":true
  }
  ```

  ```json Python theme={null}
  AcsCredential(
    acs_credential_id='66666666-6666-6666-6666-666666666666',
    acs_user_id='33333333-3333-3333-3333-333333333333',
    access_method='card',
    starts_at='2024-12-01T15:00:00.000Z',
    ends_at='2024-12-04T12:00:00.000Z',
    is_issued=True,
    card_number='1234abc',
    issued_at='2024-10-23T19:46:06.113Z',
    ...
  )
  ```

  ```json Ruby theme={null}
  <Seam::Resources::AcsCredential:0x00410
    acs_credential_id="66666666-6666-6666-6666-666666666666"
    acs_user_id="33333333-3333-3333-3333-333333333333"
    access_method="card"
    starts_at="2024-12-01T15:00:00.000Z"
    ends_at="2024-12-04T12:00:00.000Z"
    is_issued=true
    card_number="1234abc"
    issued_at="2024-10-23T19:46:06.113Z"
    ...
  >
  ```

  ```json PHP theme={null}
  {
    "acs_credential_id": "66666666-6666-6666-6666-666666666666",
    "acs_user_id": "33333333-3333-3333-3333-333333333333",
    "access_method": "card",
    "starts_at": "2024-12-01T15:00:00.000Z",
    "ends_at": "2024-12-04T12:00:00.000Z",
    "is_issued": true,
    "card_number": "1234abc",
    "issued_at": "2024-10-23T19:46:06.113Z",
    ...
  }
  ```

  ```json C# theme={null}
  {
    "acs_credential_id": "66666666-6666-6666-6666-666666666666",
    "acs_user_id": "33333333-3333-3333-3333-333333333333",
    "access_method": "card",
    "starts_at": "2024-12-01T15:00:00.000Z",
    "ends_at": "2024-12-04T12:00:00.000Z",
    "is_issued": true,
    "card_number": "1234abc",
    "issued_at": "2024-10-23T19:46:06.113Z",
    ...
  }
  ```
</CodeGroup>

***

### Confirm Successful Encoding by Using a Webhook

To confirm successful encoding, you can use a [webhook](../../../developer-tools/webhooks) to listen for an `acs_credential.issued` event that contains the `acs_credential_id` in the payload. If you are re-encoding a card, listen for `acs_credential.reissued` instead of `acs_credential.issued`.

```json theme={null}
{
  "event_id": "22222222-3333-4444-5555-666666666666",
  "event_description": "An ACS credential was issued.",
  "event_type": "acs_credential.issued",
  "workspace_id": "00000000-0000-0000-0000-000000000000",
  "created_at": "2024-10-23T19:47:35.375Z",
  "occurred_at": "2024-10-23T19:47:35.356Z",
  "acs_system_id": "11111111-1111-1111-1111-111111111111",
  "acs_credential_id": "66666666-6666-6666-6666-666666666666",
  "connected_account_id": "11111111-1111-1111-1111-222222222222"
}
```

***

## Common Encoding Errors

<table>
  <thead>
    <tr>
      <th>Error</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        <code>no\_card\_on\_encoder</code>
      </td>

      <td>No card was placed on the encoder.</td>
    </tr>

    <tr>
      <td>
        <code>incompatible\_card\_format</code>
      </td>

      <td>
        A card with an incompatible card format was placed on the encoder.
      </td>
    </tr>

    <tr>
      <td>
        <code>uncategorized\_error</code>
      </td>

      <td>Any other encoding error.</td>
    </tr>
  </tbody>
</table>


# Working with Card Encoders and Scanners
Source: https://docs.seam.co/low-level-apis/access-systems/working-with-card-encoders-and-scanners/index

Learn how to encode plastic cards and then scan these cards.

<img alt="" />

Some access control systems require credentials to be [encoded onto plastic key cards](/low-level-apis/access-systems/working-with-card-encoders-and-scanners/creating-and-encoding-card-based-credentials) using a card encoder. This process involves the following two key steps:

1. Credential or access method creation

   Configure the access parameters for the credential or access method.

   Note that to create a card access method, you create an Access Grant that includes a request for a card access method. The resulting Access Grant includes the card access method.

2. Card encoding

   Write the credential or access method data onto the card using a compatible card encoder.

Separately, the Seam API also supports [card scanning](/low-level-apis/access-systems/working-with-card-encoders-and-scanners/scanning-encoded-cards), which enables you to scan and read the encoded data on a card. You can use this action to confirm consistency with ACS records or diagnose discrepancies if needed.

To verify if your ACS requires a card encoder, see the [system integration guide](/low-level-apis/access-systems/index) for your ACS.

***

<CardGroup>
  <Card title="Creating and Encoding Card-based Credentials" href="/low-level-apis/access-systems/working-with-card-encoders-and-scanners/creating-and-encoding-card-based-credentials" />

  <Card title="Creating and Encoding Card Access Methods" href="/low-level-apis/access-systems/working-with-card-encoders-and-scanners/creating-and-encoding-card-access-methods" />

  <Card title="Scanning Encoded Cards" href="/low-level-apis/access-systems/working-with-card-encoders-and-scanners/scanning-encoded-cards" />
</CardGroup>


# Scanning Encoded Cards
Source: https://docs.seam.co/low-level-apis/access-systems/working-with-card-encoders-and-scanners/scanning-encoded-cards

Learn how to scan an encoded card to retrieve useful information about the card.

<img alt="" />

You can use an encoder to scan a plastic key card to read its encoded parameters. The scan result includes the card's properties, such as its card number, serial number, and other useful details. The returned payload can also reveal whether the card is up to date with the server. If discrepancies are detected, Seam also provides warnings to indicate that the card is out of date and needs re-encoding.

The scanning process consists of the following basic steps:

1. Initiate the scanning process.\
   Use the `/acs/encoders/scan_credential` endpoint. Specify the `acs_encoder_id` of the encoder that you want to use to scan the card.\
   This request returns an action attempt that tracks the status of the scan.\
   See [Initiate the Scanning Process](#1-initiate-the-scanning-process).
2. Poll the returned action attempt, until its `status` becomes `success`.\
   See [Confirm Successful Scan](#2-confirm-successful-scan).
3. View the scanned card payload.\
   Once the `status` of the action attempt is `success`, view the card payload within the action attempt. Note any `action_attempt.result.warnings`. Warning messages show which properties are out of sync.\
   See [View the Scanned Card Payload](#3-view-the-scanned-card-payload). Also, see a list of [common scanning errors](#common-scanning-errors).

***

## 1. Initiate the Scanning Process

To scan a card, first, identify the `acs_encoder_id` of the encoder that you want to use to scan the card. Then, initiate the scan using the `/acs/encoders/scan_credential` endpoint.

**Code:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  // Retrieve a list of all available encoders in a building,
  // that is, connected to a single acs_system.
  await seam.acs.encoders.list({
    acs_system_ids: [buildingSystemId],
  })

  // Scan the card using the desired encoder.
  const scanningActionAttempt = await seam.acs.encoders.scanCredential({
    acs_encoder_id: encoder.acs_encoder_id,
  })
  ```

  ```bash cURL theme={null}
  # Retrieve a list of all available encoders in a building,
  # that is, connected to a single acs_system.
  curl -X 'POST' \
    'https://connect.getseam.com/acs/encoders/list' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d "{
    \"acs_system_ids\": [\"${building_system_id}\"]
  }"

  # Scan the card using the desired encoder.
  scanning_action_attempt=$(curl -X 'POST' \
    'https://connect.getseam.com/acs/encoders/scan_credential' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d "{
    \"acs_encoder_id\": \"${acs_encoder_id}\"
  }")
  ```

  ```python Python theme={null}
  # Retrieve a list of all available encoders in a building,
  # that is, connected to a single acs_system.
  seam.acs.encoders.list(
    acs_system_ids = [building_system_id]
  )

  # Scan the card using the desired encoder.
  scanning_action_attempt = seam.acs.encoders.scan_credential(
    acs_encoder_id = encoder.acs_encoder_id
  )
  ```

  ```ruby Ruby theme={null}
  # Retrieve a list of all available encoders in a building,
  # that is, connected to a single acs_system.
  seam.acs.encoders.list(
    acs_system_ids: [building_system_id]
  )

  # Scan the card using the desired encoder.
  scanning_action_attempt = seam.acs.encoders.scan_credential(
    acs_encoder_id: encoder.acs_encoder_id
  )
  ```

  ```php PHP theme={null}
  // Retrieve a list of all available encoders in a building,
  // that is, connected to a single acs_system.
  $seam->acs->encoders->list(
    acs_system_ids: [building_system_id]
  );

  // Scan the card using the desired encoder.
  $scanning_action_attempt = $seam->acs->encoders->scan_credential(
    acs_encoder_id: $encoder->acs_encoder_id
  );
  ```

  ```csharp C# theme={null}
  // Retrieve a list of all available encoders in a building,
  // that is, connected to a single acs_system.
  seam.EncodersAcs.List(
    acsSystemIds: new List<string>
    {
      buildingSystemId
    }
  );

  // Scan the card using the desired encoder.
  actionAttempt scanningActionAttempt = seam.EncodersAcs.ScanCredential(
    acsEncoderId: encoder.acsEncoderId
  );
  ```
</CodeGroup>

**Output:**

<CodeGroup>
  ```json JavaScript theme={null}
  {
    "status": "pending",
    "action_attempt_id": "11111111-2222-3333-4444-666666666666",
    "action_type": "SCAN_CREDENTIAL",
    "result": null,
    "error": null
  }
  ```

  ```json cURL theme={null}
  {
    "action_attempt": {
      "status": "pending",
      "action_attempt_id": "11111111-2222-3333-4444-666666666666",
      "action_type": "SCAN_CREDENTIAL",
      "result": null,
      "error": null
    },
    "ok": true
  }
  ```

  ```json Python theme={null}
  ActionAttempt(
    status='pending',
    action_attempt_id='11111111-2222-3333-4444-666666666666',
    action_type='SCAN_CREDENTIAL',
    result=null,
    error=null
  )
  ```

  ```json Ruby theme={null}
  <Seam::Resources::ActionAttempt:0x00410
    status="pending"
    action_attempt_id="11111111-2222-3333-4444-666666666666"
    action_type="SCAN_CREDENTIAL"
    result=nil
    error=nil
  >
  ```

  ```json PHP theme={null}
  {
    "status": "pending",
    "action_attempt_id": "11111111-2222-3333-4444-666666666666",
    "action_type": "SCAN_CREDENTIAL",
    "result": null,
    "error": null
  }
  ```

  ```json C# theme={null}
  {
    "status": "pending",
    "action_attempt_id": "11111111-2222-3333-4444-666666666666",
    "action_type": "SCAN_CREDENTIAL",
    "result": null,
    "error": null
  }
  ```
</CodeGroup>

***

## 2. Confirm Successful Scan

When you make an `/acs/encoders/scan_credential` request, Seam returns an [action attempt](../../../core-concepts/action-attempts). To identify when the scan has completed and to confirm that the scan was successful, poll this action attempt, until its `status` becomes `success`.

**Code:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  await seam.actionAttempts.get({
    action_attempt_id: scanningActionAttempt.action_attempt_id,
  })
  ```

  ```bash cURL theme={null}
  curl -X 'POST' \
    'https://connect.getseam.com/action_attempts/get' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d "{
    \"action_attempt_id\": \"$(jq -r '.action_attempt.action_attempt_id' <<< ${scanning_action_attempt})\"
  }"
  ```

  ```python Python theme={null}
  seam.action_attempts.get(
    action_attempt_id = scanning_action_attempt.action_attempt_id
  )
  ```

  ```ruby Ruby theme={null}
  seam.action_attempts.get(
    action_attempt_id: scanning_action_attempt.action_attempt_id
  )
  ```

  ```php PHP theme={null}
  $seam->action_attempts->get(
    action_attempt_id: $scanning_action_attempt->action_attempt_id
  );
  ```

  ```csharp C# theme={null}
  seam.ActionAttempts.Get(
    actionAttemptId: scanningActionAttempt.actionAttemptId
  );
  ```
</CodeGroup>

**Output:**

<CodeGroup>
  ```json JavaScript theme={null}
  {
    status: 'success',
    action_attempt_id: '11111111-2222-3333-4444-666666666666",
    action_type: 'SCAN_CREDENTIAL',
    result: {
      ...
    },
    error: null
  }
  ```

  ```json cURL theme={null}
  {
    "action_attempt":
      {
        "status": "success",
        "action_attempt_id": "11111111-2222-3333-4444-666666666666",
        "action_type": "SCAN_CREDENTIAL",
        "result": {
          ...
        },
        "error": null
      },
    "ok": true
  }
  ```

  ```json Python theme={null}
  ActionAttempt(
    status='success',
    action_attempt_id='11111111-2222-3333-4444-666666666666',
    action_type='SCAN_CREDENTIAL',
    result={
      ...
    },
    error=null
  )
  ```

  ```json Ruby theme={null}
  <Seam::Resources::ActionAttempt:0x00410
    status="success"
    action_attempt_id="11111111-2222-3333-4444-666666666666"
    action_type="SCAN_CREDENTIAL"
    result={
      ...
    }
    error=nil
  >
  ```

  ```json PHP theme={null}
  {
    "status": "success",
    "action_attempt_id": "11111111-2222-3333-4444-666666666666",
    "action_type": "SCAN_CREDENTIAL",
    "result": {
      ...
    },
    "error": null
  }
  ```

  ```json C# theme={null}
  {
    "status": "success",
    "action_attempt_id": "11111111-2222-3333-4444-666666666666",
    "action_type": "SCAN_CREDENTIAL",
    "result": {
      ...
    },
    "error": null
  }
  ```
</CodeGroup>

***

## 3. View the Scanned Card Payload

Once the action attempt's `status` is `success`, view the action attempt payload to view information about the scanned card. Pay special attention to the following parts of the returned payload:

* `action_attempt.result.warnings` list any properties that Seam has detected are out-of-sync between the card and the encoder.
* `action_attempt.result.acs_credential_on_seam` lists the properties of the credential as stored on the ACS server.
* `action_attempt.result.acs_credential_on_encoder` lists the properties of the credential as stored on the card.

```json theme={null}
{
  "status": "success",
  "action_attempt_id": "11111111-2222-3333-4444-666666666666",
  "action_type": "SCAN_CREDENTIAL",
  "result": {
    "warnings": [
      {
        "warning_code": "acs_credential_on_encoder_out_of_sync",
        "warning_message": "The following properties are out of sync
                            between acs_credential_on_encoder and
                            acs_credential_on_seam: ends_at"
      }
    ],
    "acs_credential_on_seam": {
      "starts_at": "2024-12-01T15:00:00.000Z",
      "ends_at": "2024-12-04T12:00:00.000Z",
      "card_number": "1234abc",
      "display_name": "Card 1234abc",
      "access_method": "card",
      "acs_system_id": "11111111-1111-1111-1111-111111111111",
      "acs_credential_id": "66666666-6666-6666-6666-666666666666",
      ...
    },
    "acs_credential_on_encoder": {
      "starts_at": "2024-12-01T15:00:00.000Z",
      "ends_at": "2024-10-30T19:00:00.000Z",
      "card_number": "1234abc",
      ...
    }
  },
  "error": null
}
```

***

### Common Scanning Errors

<table>
  <thead>
    <tr>
      <th>Error</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        <code>no\_card\_on\_encoder</code>
      </td>

      <td>No card was placed on the encoder.</td>
    </tr>

    <tr>
      <td>
        <code>uncategorized\_error</code>
      </td>

      <td>Any other encoding error.</td>
    </tr>
  </tbody>
</table>


# Access Code Requirements for Door Locks
Source: https://docs.seam.co/low-level-apis/smart-locks/access-codes/access-code-requirements-for-door-locks

Learn about the specific requirements and constraints for setting access codes on door locks.

Some models of door locks have specific requirements and constraints when it comes to setting PIN codes. It's essential to be aware of these to ensure seamless functionality and security. The requirements can be fetched by making a [Get Device](/api/devices/get) or [List Devices](/api/devices/list) (or [List Locks](/api/locks/list)) request.

Sample set of access code requirements:

```json theme={null}
{
  "device": {
    "device_id": "00000000-0000-0000-0000-000000000000",
    "capabilities_supported": [
      "access_code",
      "lock"
    ],
    "properties": {
      "supported_code_lengths": [
        4,
        5,
        6,
        7,
        8
      ],
      "max_active_codes_supported": 250,
      "code_constraints": [
        {
          "constraint_type": "no_zeros"
        },
        {
          "constraint_type": "name_length",
          "min_length": 1,
          "max_length": 12
        }
      ],
      "supports_backup_access_code_pool": true
      ...
    },
    ...
  },
  ...
}
```

**Request:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  const device = await seam.devices.get({
    device_id: 'ed4bb795-f29f-43e5-bc0f-35f69f9141b5',
  })

  console.log(device)
  console.log(device.properties.code_constraints)
  ```

  ```bash cURL theme={null}
  # 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": "ed4bb795-f29f-43e5-bc0f-35f69f9141b5"
  }'
  ```

  ```python Python theme={null}
  pprint(seam.locks.get(device="ed4bb795-f29f-43e5-bc0f-35f69f9141b5"))
  ```

  ```ruby Ruby theme={null}
  puts client.devices.get(device_id: "ed4bb795-f29f-43e5-bc0f-35f69f9141b5").inspect
  ```

  ```php PHP theme={null}
  use Seam\SeamClient;

  $seam = new SeamClient("YOUR_API_KEY");

  $device = $seam->devices->get("0e2e6262-7f91-4970-a58d-47ef30b41e2e");

  # Inspect this device to see which capabilities it supports
  echo json_encode($device->properties, JSON_PRETTY_PRINT);

  // {
  //     "online": true,
  //     "locked": false,
  //     "name": "Office Lock",
  //     "battery_level": 0.86,
  //     "battery": {
  //         "level": 0.86,
  //         "status": "full"
  //     },
  //     "manufacturer": "nuki",
  //     "supported_code_lengths": [
  //         6
  //     ],
  //     "code_constraints": [
  //         {
  //             "constraint_type": "cannot_start_with_12"
  //         },
  //         {
  //             "constraint_type": "no_zeros"
  //         },
  //         {
  //             "constraint_type": "name_length",
  //             "max_length": 20
  //         }
  //     ],
  //     "model": {
  //         "display_name": "Lock",
  //         "manufacturer_display_name": "Nuki"
  //     },
  //     "image_url": "https:\/\/connect.getseam.com\/assets\/images\/devices\/nuki_smart_lock_3_pro_black.png",
  //     "image_alt_text": "Nuki Smart Lock 3.0 Pro Black, Front",
  //     "nuki_metadata": {
  //         "device_id": "545636389",
  //         "device_name": "Office Lock",
  //         "keypad_battery_critical": false
  //     }
  // }
  ```

  ```csharp C# theme={null}
  var device = seam.Devices.Get(deviceId: "ed4bb795-f29f-43e5-bc0f-35f69f9141b5");
  Console.WriteLine("Device ID: " + device.DeviceId);
  Console.WriteLine("Type: " + device.DeviceType);
  Console.WriteLine("Capabilities supported:");
  foreach (var capability in device.CapabilitiesSupported)
  {
    Console.WriteLine(capability);
  }
  Console.WriteLine("Supported code lengths:");
  if (device.Properties.SupportedCodeLengths is not null)
  {
    foreach (var supportedCodeLength in device.Properties.SupportedCodeLengths)
    {
      Console.WriteLine(supportedCodeLength);

    }
  }
  Console.WriteLine("Code constraints:");
  if (device.Properties.CodeConstraints is not null)
  {
    foreach (var codeConstraint in device.Properties.CodeConstraints)
    {
      Console.WriteLine(codeConstraint);
    }
  }
  Console.WriteLine("Supports backup access code pool: " + device.Properties.SupportsBackupAccessCodePool);
  ```
</CodeGroup>

**Response:**

<CodeGroup>
  ```json JavaScript theme={null}
  {
    device_id: 'ed4bb795-f29f-43e5-bc0f-35f69f9141b5',
    device_type: 'nuki_lock',
    capabilities_supported: [ 'access_code', 'lock' ],
    properties: {
      locked: false,
      online: true,
      manufacturer: 'nuki',
      battery_level: 0.86,
      nuki_metadata: {
        device_id: '3',
        device_name: 'Office Lock',
        keypad_battery_critical: false
      },
      keypad_battery: { level: 1 },
      supported_code_lengths: [ 6 ],
      has_native_entry_events: true,
      name: 'Office Lock',
      model: { display_name: 'Lock', manufacturer_display_name: 'Nuki' },
      battery: { level: 0.86, status: 'full' },
      image_url: 'https://connect.getseam.com/assets/images/devices/nuki_smart_lock_3_pro_black.png',
      image_alt_text: 'Nuki Smart Lock 3.0 Pro Black, Front',
      code_constraints: [ [Object], [Object], [Object] ],
      supports_backup_access_code_pool: true
    },
    location: null,
    connected_account_id: 'cac74c00-443b-440f-820e-e2907277fd9f',
    workspace_id: '398d80b7-3f96-47c2-b85a-6f8ba21d07be',
    created_at: '2023-10-19T04:43:40.852Z',
    errors: [],
    warnings: [],
    is_managed: true
  }
  [
    { constraint_type: 'cannot_start_with_12' },
    { constraint_type: 'no_zeros' },
    { constraint_type: 'name_length', max_length: 20 }
  ]
  ```

  ```json cURL theme={null}
  {
    "device": {
      "device_id": "ed4bb795-f29f-43e5-bc0f-35f69f9141b5",
      "device_type": "nuki_lock",
      "capabilities_supported": ["access_code", "lock"],
      "properties": {
        "locked": false,
        "online": true,
        "manufacturer": "nuki",
        "battery_level": 0.86,
        "nuki_metadata": {
          "device_id": "3",
          "device_name": "Office Lock",
          "keypad_battery_critical": false
        },
        "keypad_battery": {
          "level": 1
        },
        "supported_code_lengths": [6],
        "has_native_entry_events": true,
        "name": "Office Lock",
        "model": {
          "display_name": "Lock",
          "manufacturer_display_name": "Nuki"
        },
        "battery": {
          "level": 0.86,
          "status": "full"
        },
        "image_url": "https://connect.getseam.com/assets/images/devices/nuki_smart_lock_3_pro_black.png",
        "image_alt_text": "Nuki Smart Lock 3.0 Pro Black, Front",
        "code_constraints": [
          {
            "constraint_type": "cannot_start_with_12"
          },
          {
            "constraint_type": "no_zeros"
          },
          {
            "constraint_type": "name_length",
            "max_length": 20
          }
        ],
        "supports_backup_access_code_pool": true
      },
      "location": null,
      "connected_account_id": "cac74c00-443b-440f-820e-e2907277fd9f",
      "workspace_id": "398d80b7-3f96-47c2-b85a-6f8ba21d07be",
      "created_at": "2023-10-19T04:43:40.852Z",
      "errors": [],
      "warnings": [],
      "is_managed": true
    },
    "ok": true
  }
  ```

  ```json Python theme={null}
  Device(device_id='ed4bb795-f29f-43e5-bc0f-35f69f9141b5',
         device_type='nuki_lock',
         location=None,
         properties={'battery': {'level': 0.86, 'status': 'full'},
                     'battery_level': 0.86,
                     'code_constraints': [{'constraint_type': 'cannot_start_with_12'},
                                          {'constraint_type': 'no_zeros'},
                                          {'constraint_type': 'name_length',
                                           'max_length': 20}],
                     'has_native_entry_events': True,
                     'image_alt_text': 'Nuki Smart Lock 3.0 Pro Black, Front',
                     'image_url': 'https://connect.getseam.com/assets/images/devices/nuki_smart_lock_3_pro_black.png',
                     'keypad_battery': {'level': 1},
                     'locked': False,
                     'manufacturer': 'nuki',
                     'model': {'display_name': 'Lock',
                               'manufacturer_display_name': 'Nuki'},
                     'name': 'Office Lock',
                     'nuki_metadata': {'device_id': '3',
                                       'device_name': 'Office Lock',
                                       'keypad_battery_critical': False},
                     'online': True,
                     'supported_code_lengths': [6],
                     'supports_backup_access_code_pool': True},
         capabilities_supported=['access_code', 'lock'],
         errors=[],
         warnings=[],
         connected_account_id='cac74c00-443b-440f-820e-e2907277fd9f',
         workspace_id='398d80b7-3f96-47c2-b85a-6f8ba21d07be',
         created_at='2023-10-19T04:43:40.852Z',
         is_managed=True)
  ```

  ```json Ruby theme={null}
  <Seam::Device:0x00438
    device_id="ed4bb795-f29f-43e5-bc0f-35f69f9141b5"
    device_type="nuki_lock"
    capabilities_supported=["access_code", "lock"]
    properties={"locked"=>false, "online"=>true, "manufacturer"=>"nuki", "battery_level"=>0.86, "nuki_metadata"=>{"device_id"=>"3", "device_name"=>"Office Lock", "keypad_battery_critical"=>false}, "keypad_battery"=>{"level"=>1}, "supported_code_lengths"=>[6], "has_native_entry_events"=>true, "name"=>"Office Lock", "model"=>{"display_name"=>"Lock", "manufacturer_display_name"=>"Nuki"}, "battery"=>{"level"=>0.86, "status"=>"full"}, "image_url"=>"https://connect.getseam.com/assets/images/devices/nuki_smart_lock_3_pro_black.png", "image_alt_text"=>"Nuki Smart Lock 3.0 Pro Black, Front", "code_constraints"=>[{"constraint_type"=>"cannot_start_with_12"}, {"constraint_type"=>"no_zeros"}, {"constraint_type"=>"name_length", "max_length"=>20}], "supports_backup_access_code_pool"=>true}
    connected_account_id="cac74c00-443b-440f-820e-e2907277fd9f"
    workspace_id="398d80b7-3f96-47c2-b85a-6f8ba21d07be"
    created_at=2023-10-19 04:43:40.852 UTC
    errors=[]
    warnings=[]
    is_managed=true>
  ```

  ```json C# theme={null}
  Device ID: ed4bb795-f29f-43e5-bc0f-35f69f9141b5
  Type: NukiLock
  Capabilities supported:
  AccessCode
  Lock
  Supported code lengths:
  6
  Code constraints:
  {
    "constraint_type": "cannot_start_with_12"
  }
  {
    "constraint_type": "no_zeros"
  }
  {
    "constraint_type": "name_length",
    "max_length": 20
  }
  Supports backup access code pool: True
  ```
</CodeGroup>

***

## Supported Code Lengths

This property is denoted as `supported_code_lengths` and contains an array of numbers. These numbers represent the various lengths (in terms of digits) allowed for a PIN code. For example, if the array contains `[4, 6]`, it means the door lock can accept 4-digit or 6-digit PIN codes.

**Example Payload:**

```json theme={null}
"supported_code_lengths": [
    4,
    5,
    6,
    7,
    8
]
```

***

## Maximum Set Codes

The property `max_active_codes_supported` indicates the total number of codes that can be simultaneously set on a door lock. For the door locks that accommodate [native scheduling](/low-level-apis/smart-locks/access-codes#native-scheduling), this count will includes future scheduled codes that are set on the lock.

**Example Payload:**

```json theme={null}
"max_active_codes_supported": 250
```

***

## PIN Code Constraints

The `code_constraints` property gives insight into various conditions or limitations that apply to PIN codes. Each constraint in the `code_constraints` array is an object with at least the `constraint_type` property.

**Example Payload:**

```json theme={null}
"code_constraints": [
    {
        "constraint_type": "no_zeros"
    },
    {
        "constraint_type": "name_length",
        "min_length": 1,
        "max_length": 12
    }
]
```

The `constraint_type` property can be one of the following:

| Constraint Type                           | Description                                                                                                                                                                                                                           |
| ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **`no_zeros`**                            | `0`s cannot be used as digits in the pin code.                                                                                                                                                                                        |
| **`cannot_start_with_12`**                | The pin code cannot start with the sequence of digits `12`.                                                                                                                                                                           |
| **`no_triple_consecutive_ints`**          | No more than 3 digits in a row can be consecutive or the same in the pin code.                                                                                                                                                        |
| **`cannot_specify_pin_code`**             | A pin code cannot be specified - it has to be left empty and one will be generated by the lock provider.                                                                                                                              |
| **`pin_code_matches_existing_set`**       | If a pin code is specified, it must match an existing set of pin codes used in the account (for example, pin code matches the code assigned to a user in the system).                                                                 |
| **`start_date_in_future`**                | For time-bound codes, the start date has to be in the future.                                                                                                                                                                         |
| **`no_ascending_or_descending_sequence`** | The PIN code cannot be a purely ascending (for example, `1234`) or descending (for example, `9876`) sequence.                                                                                                                         |
| **`at_least_three_unique_digits`**        | The PIN code must contain at least three distinct digits (for example, `1122` is invalid; `1123` is valid).                                                                                                                           |
| **`no_all_same_digits`**                  | The PIN code cannot consist entirely of the same repeated digit (for example, `1111` is invalid).                                                                                                                                     |
| **`unique_first_four_digits`**            | The first four digits of the PIN code must all be distinct.                                                                                                                                                                           |
| **`cannot_contain_089`**                  | The PIN code cannot contain any of the digits `0`, `8`, or `9`.                                                                                                                                                                       |
| **`cannot_contain_0789`**                 | The PIN code cannot contain any of the digits `0`, `7`, `8`, or `9`. Only digits `1`–`6` are permitted. This constraint applies to TTLock cylinder devices whose physical keypad only includes buttons numbered 1 through 6.          |
| **`name_length`**                         | The name of the code has some restrictions on length. When the `constraint_type` is `name_length`, the constraint object has one or two additional properties called `min_length` and `max_length` to specify the length constraints. |
| **`name_must_be_unique`**                 | The name of the access code must be unique across all codes on the device.                                                                                                                                                            |

***

## TTLock Devices with Limited Keypads

Some TTLock devices—particularly certain cylinder lock models—have a physical keypad with buttons numbered 1 through 6 only (no 0, 7, 8, or 9 keys). When Seam detects this hardware configuration, it automatically applies the `cannot_contain_0789` constraint to the device.

If you check `device.properties.code_constraints` for one of these devices, you will see:

```json theme={null}
{
  "code_constraints": [
    { "constraint_type": "cannot_contain_0789" },
    { "constraint_type": "cannot_contain_089" }
  ]
}
```

When generating access codes for these devices, Seam automatically ensures that only digits 1–6 are used. If you attempt to set a code that contains a digit outside this range (for example, `9821`), the request will be rejected with a descriptive error message indicating which digits are not supported.

Seam detects this constraint automatically from the device's reported hardware capabilities—no manual configuration is required.


# Streamlining Access Code Management from the Manufacturer App
Source: https://docs.seam.co/low-level-apis/smart-locks/access-codes/accommodating-manufacturer-mobile-apps

This guide covers how to ensure that codes created via the Seam API are easily identified and can be editable within the smart lock manufacturer app.

Most smart lock manufacturers provide a mobile (or web) app that device owners can use to manage their devices. This includes seeing and editing access codes that are programmed on their smart locks. When creating access codes using the Seam API, it's important to keep in mind that smart lock device owners may also be using their device manufacturer app to look up codes you've created and perhaps edit them. To ensure that these can easily be done, Seam provides a couple of API features for enabling this.

## Access Code Name

When creating an access code, the Seam API lets you set a `name` attribute for the code. This `name` can be used to identify the code on Seam. In addition, smart lock device owners can also use this name to identify the code you created inside their smart lock manufacturer app.&#x20;

### Naming Codes & Best Practices

When creating an access code, it's important to use a simple & recognizable name to help device owners identify code(s) you've created. For example, if the access code is for an Airbnb reservation, it may be helpful to name the code "Anna Smith, Reservation-12345". Long `uuid` or random strings are generally not recommended.

### Code Name vs. Appearance in App

The `name` you set for an access code may not necessarily match exactly the name that appears inside the smart lock manufacturer app. This is because Seam has to account for manufacturer naming constraints.&#x20;

For example, some lock providers may restrict name length, uniqueness, or the use of certain characters (e.g. emojis). Some lock providers may even break down access code names into components such as first name and last name. Seam automatically takes these factors into consideration.

Since the exact name displayed inside the app may differ as a result, Seam provides an `appearance` property on the access code object. This property shows the exact name used inside the smart lock manufacturer app, which can be helpful for your customer support when guiding a device owner.

## Access Code Editing by User

At times, a smart lock device owner may wish to edit the access code that you've created using the Seam API. For example, they may wish to edit the `starts_at` time of the code to allow for early access to their home. Alternatively, they want want to delete the code altogether to restrict access to their home.

### Default Overwriting Behavior

The default behavior of the Seam API is to immediately override those changes made by the device owner. This is because Seam's default behavior is to keep the access code on the device in sync with the declared state of the access code on Seam.&#x20;

### Get Notified of Changes

When external modifications are detected, Seam will send an `access_code.modified_external_to_seam` event to your application. Seam will also add a `code_modified_external_to_seam` error on the access code. You can use these to inform your user that changes made inside their smart lock device manufacturer app are automatically overwritten.

### Allow for Access Code Modification

If you want to allow device owners to be able to edit access codes that you have created through the Seam API, set the `allow_external_modification` flag to `true` when creating an access code. This prevents Seam from overwriting any changes made by the device owner to the access code. Seam also sets `code_modified_external_to_seam` as a warning on the code, instead of an error, when a change is detected. Note that the `allow_external_modification` flag can also be passed when updating an access code or when converting an access code from unmanaged to managed.

**Request:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  const deviceId = '6aae9d08-fed6-4ca5-8328-e36849ab48fe'

  const createdAccessCode = await seam.accessCodes.create({
    device_id: deviceId,
    name: 'my ongoing code',
    allow_external_modification: true,
  })

  console.log(createdAccessCode)
  ```

  ```sh cURL theme={null}
  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": "6aae9d08-fed6-4ca5-8328-e36849ab48fe",
    "name": "my ongoing code",
    "allow_external_modification": true
  }'
  ```

  ```python Python theme={null}
  device_id = "6aae9d08-fed6-4ca5-8328-e36849ab48fe"

  created_access_code = seam.access_codes.create(
    device = device_id,
    name = "my ongoing code",
    allow_external_modification = True
  )

  pprint(created_access_code)
  ```

  ```ruby Ruby theme={null}
  device_id = "6aae9d08-fed6-4ca5-8328-e36849ab48fe"

  created_access_code = client.access_codes.create(
    device_id: device_id,
    name: "my ongoing code",
    allow_external_modification: true
  )

  puts created_access_code.inspect
  ```

  ```php PHP theme={null}
  $seam = new SeamClient("YOUR_API_KEY");

  $device_id = "0e2e6262-7f91-4970-a58d-47ef30b41e2e";

  $access_code = $seam->access_codes->create(
    device_id: $device_id,
    name: 'my ongoing code',
    allow_external_modification: true
  );

  # Inspect this created code
  echo json_encode($access_code, JSON_PRETTY_PRINT);

  // {
  //     "access_code_id": "bd7e8681-4df6-437c-a12a-e965ecca9caf",
  //     "device_id": "0e2e6262-7f91-4970-a58d-47ef30b41e2e",
  //     "name": "my ongoing code",
  //     "type": "ongoing",
  //     "status": "setting",
  //     "starts_at": null,
  //     "ends_at": null,
  //     "code": "453419",
  //     "created_at": "2023-09-04T05:29:08.084Z",
  //     "errors": [],
  //     "warnings": [],
  //     "is_managed": true,
  //     "common_code_key": null,
  //     "is_waiting_for_code_assignment": null
  // }
  ```

  ```csharp C# theme={null}
  var deviceId = "6aae9d08-fed6-4ca5-8328-e36849ab48fe";
  var createdAccessCode = seam.AccessCodes.Create(
    deviceId: deviceId,
    name: "my ongoing code",
    allowExternalModification: true
  );

  Console.WriteLine("Created access code ID: " + createdAccessCode.AccessCodeId);
  Console.WriteLine("Allow external modification: " + createdAccessCode.IsExternalModificationAllowed);
  ```
</CodeGroup>

**Response:**

<CodeGroup>
  ```json JavaScript theme={null}
  {
    "access_code_id": "38a569bb-40b9-4e42-97bd-bb78f8d96777",
    "device_id": "6aae9d08-fed6-4ca5-8328-e36849ab48fe",
    "name": "my ongoing code",
    "appearance": null,
    "code": "1525",
    "common_code_key": null,
    "type": "ongoing",
    "status": "setting",
    "pulled_backup_access_code_id": null,
    "is_backup_access_code_available": true,
    "created_at": "2023-10-19T11:22:45.732Z",
    "errors": [],
    "warnings": [],
    "is_managed": true,
    "is_external_modification_allowed": true
  }
  ```

  ```json cURL theme={null}
  {
    "action_attempt": {
      "status": "pending",
      "action_type": "CREATE_ACCESS_CODE",
      "action_attempt_id": "8e2dace7-7304-43f1-b5f2-bd44b2a072a8",
      "result": null,
      "error": null
    },
    "access_code": {
      "access_code_id": "a7b85c1f-9963-4fa8-b106-7ce580a41256",
      "device_id": "6aae9d08-fed6-4ca5-8328-e36849ab48fe",
      "name": "my ongoing code",
      "appearance": null,
      "code": "5048",
      "common_code_key": null,
      "type": "ongoing",
      "status": "setting",
      "pulled_backup_access_code_id": null,
      "is_backup_access_code_available": true,
      "created_at": "2023-10-19T08:10:24.248Z",
      "errors": [],
      "warnings": [],
      "is_managed": true,
      "is_external_modification_allowed": true
    },
    "ok": true
  }
  ```

  ```json Python theme={null}
  AccessCode(access_code_id='1d9fe873-3393-4b29-b93e-87fe7f923462',
             device_id='6aae9d08-fed6-4ca5-8328-e36849ab48fe',
             type='ongoing',
             code='5629',
             created_at='2023-10-19T04:50:50.275Z',
             errors=[],
             warnings=[],
             starts_at=None,
             ends_at=None,
             name='my ongoing code',
             status='setting',
             common_code_key=None,
             is_managed=True,
             is_waiting_for_code_assignment=None,
             is_scheduled_on_device=None,
             pulled_backup_access_code_id=None,
             is_backup_access_code_available=False,
             is_backup=None,
             appearance=None,
             is_external_modification_allowed=True)
  ```

  ```json Ruby theme={null}
  <Seam::AccessCode:0x00438
    code="8667"
    name="my ongoing code"
    type="ongoing"
    errors=[]
    status="setting"
    warnings=[]
    device_id="6aae9d08-fed6-4ca5-8328-e36849ab48fe"
    appearance=nil
    created_at=2023-10-25 03:54:05.532 UTC
    is_managed=true
    access_code_id="8f1f576f-ee52-4f12-97f6-7a1593965dec"
    pulled_backup_access_code_id=nil
    is_backup_access_code_available=true
    is_external_modification_allowed=true>
  ```

  ```json C# theme={null}
  Created access code ID: 65f4a1d3-5f3a-45a4-a6b7-372c7f16c007
  Allow external modification: True
  ```
</CodeGroup>


# Managing Backup Access Codes
Source: https://docs.seam.co/low-level-apis/smart-locks/access-codes/backup-access-codes

Learn how to bullet proof your access code implementation with back up access codes.

A backup access code pool is a collection of pre-programmed access codes stored on a device, ready for use. These codes are programmed in addition to the regular access codes on Seam, serving as a safety net for any issues with the primary codes.

If there's ever a complication with a primary access code—be it due to intermittent connectivity, manual removal from a device, or provider outages—a backup code can be retrieved. Its end time can then be adjusted to align with the original code, facilitating seamless and uninterrupted access.

To bulletproof your implementation of access codes, it's essential to maintain a pool of backup access codes for each device. Seam provides a robust implementation of this backup pool system, and this article will help you learn how to use our backup access pool system.

<Info>
  Seam supports backup access codes for [time-bound access
  codes](/low-level-apis/smart-locks/access-codes#time-bound-access-codes) only.
</Info>

***

## Before You Begin

To confirm that Seam supports back up code pools for your device, check the device's `properties` by inspecting the response from [Get Device](/api/devices/get) or [List Devices](/api/devices/list). Ensure that the device's `properties.supports_backup_access_code_pool` is `true`.

After you've done that, come back here and keep reading.

**Example Payload:**

```
{
    "device_id": "00000000-0000-0000-0000-000000000000",
    "properties": {
        "supports_backup_access_code_pool": true,
        ...
    },
    ...
}
```

**Request:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  console.log(
    await seam.devices.get({
      device_id: '6aae9d08-fed6-4ca5-8328-e36849ab48fe',
    }),
  )
  ```

  ```bash cURL theme={null}
  # 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": "6aae9d08-fed6-4ca5-8328-e36849ab48fe"
  }'
  ```

  ```python Python theme={null}
  device = seam.devices.get("6aae9d08-fed6-4ca5-8328-e36849ab48fe")
  pprint("Supports backup access code pool: "
      + str(device.properties.supports_backup_access_code_pool))
  ```

  ```ruby Ruby theme={null}
  puts client.devices.get(device_id: "6aae9d08-fed6-4ca5-8328-e36849ab48fe").inspect
  ```

  ```php PHP theme={null}
  # not yet implemented
  ```

  ```csharp C# theme={null}
  var device = seam.Devices.Get(deviceId: "6aae9d08-fed6-4ca5-8328-e36849ab48fe");
  Console.WriteLine("Device ID: " + device.DeviceId);
  Console.WriteLine("Supports backup access code pool: " + device.Properties.SupportsBackupAccessCodePool);
  ```
</CodeGroup>

**Response:**

<CodeGroup>
  ```json JavaScript theme={null}
  {
    device_id: '6aae9d08-fed6-4ca5-8328-e36849ab48fe',
    .
    .
    .
    properties: {
      .
      .
      .
      supports_backup_access_code_pool: true
    },
    .
    .
    .
  }
  ```

  ```json cURL theme={null}
  {
    "device": {
      "device_id": "6aae9d08-fed6-4ca5-8328-e36849ab48fe",
      .
      .
      .

      "properties": {
        .
        .
        .
        "supports_backup_access_code_pool": true
      },
      .
      .
      .
    },
    "ok": true
  }
  ```

  ```json Python theme={null}
  'Supports backup access code pool: True'
  ```

  ```json Ruby theme={null}
  <Seam::Device:0x00438
    device_id="6aae9d08-fed6-4ca5-8328-e36849ab48fe"
    .
    .
    .
    properties={..."supports_backup_access_code_pool"=>true}
    .
    .
    .
    >
  ```

  ```json C# theme={null}
  Device ID: 6aae9d08-fed6-4ca5-8328-e36849ab48fe
  Supports backup access code pool: True
  ```
</CodeGroup>

***

## Enabling and Retrieving Backup Codes

### 1. Activate the backup access code pool

To activate the backup pool, set `use_backup_access_code_pool` to `true` when [creating an access code](/api/access_codes/create). After activation, the backup access code pool cannot be turned off for that device. However, if you unmanage the device, any backup access codes are removed.

This activation is a one-time process for each device. Once initiated, Seam consistently maintains a backup code pool for the device. All access codes associated with the device utilize the same backup code pool.

<Info>
  In the smart lock app, backup access codes appear as "Backup `{CODE_ID}` (Seam)".
</Info>

**Request:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  const deviceId = '6aae9d08-fed6-4ca5-8328-e36849ab48fe'

  const createdAccessCode = await seam.accessCodes.create({
    device_id: deviceId,
    name: 'my time-bound code',
    starts_at: '2025-01-01T16:00:00Z',
    ends_at: '2025-01-22T12:00:00Z',
    use_backup_access_code_pool: true,
  })

  console.log(createdAccessCode)
  ```

  ```bash cURL theme={null}
  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": "6aae9d08-fed6-4ca5-8328-e36849ab48fe",
    "name": "my time-bound code",
    "starts_at": "2025-01-01T16:00:00Z",
    "ends_at": "2025-01-22T12:00:00Z",
    "use_backup_access_code_pool": true
  }'
  ```

  ```python Python theme={null}
  device_id = "6aae9d08-fed6-4ca5-8328-e36849ab48fe"

  created_access_code = seam.access_codes.create(
    device = device_id,
    name = "my time-bound code",
    starts_at = "2025-01-01T16:00:00Z",
    ends_at = "2025-01-22T12:00:00Z",
    use_backup_access_code_pool = True
  )

  pprint(created_access_code)
  ```

  ```ruby Ruby theme={null}
  device_id = "6aae9d08-fed6-4ca5-8328-e36849ab48fe"

  created_access_code = client.access_codes.create(
    device_id: device_id,
    name: "my time-bound code",
    starts_at: "2025-01-01T16:00:00Z",
    ends_at: "2025-01-22T12:00:00Z",
    use_backup_access_code_pool: true
  )

  puts created_access_code.inspect
  ```

  ```php PHP theme={null}
  $device_id = "5a9dee23-e50f-4da7-88f3-fef38bf07857";

  $access_code = $seam->access_codes->create(
    device_id: $device_id,
    name: 'my timebound code',
    starts_at:  "2025-01-01T16:00:00Z",
    ends_at: "2025-01-22T12:00:00Z",
    use_backup_access_code_pool: true
  );

  # Inspect this timebound code
  echo json_encode($access_code, JSON_PRETTY_PRINT);


  // {
  //   "access_code_id": "a91604eb-ebae-420c-a51e-07a30422fd94",
  //   "device_id": "5a9dee23-e50f-4da7-88f3-fef38bf07857",
  //   "name": "my timebound code",
  //   "type": "time_bound",
  //   "status": "unset",
  //   "starts_at": "2025-01-01T16:00:00.000Z",
  //   "ends_at": "2025-01-22T12:00:00.000Z",
  //   "code": "6837",
  //   "created_at": "2023-09-16T20:54:20.872Z",
  //   "errors": [],
  //   "warnings": [],
  //   "is_managed": true,
  //   "common_code_key": null,
  //   "is_waiting_for_code_assignment": null,
  //   "is_scheduled_on_device": false,
  //   "pulled_backup_access_code_id": null,
  //   "is_backup_access_code_available": true,
  //   "is_backup": null
  // }
  ```

  ```csharp C# theme={null}
  var deviceId = "6aae9d08-fed6-4ca5-8328-e36849ab48fe";
  var createdAccessCode = seam.AccessCodes.Create(
    deviceId: deviceId,
    name: "my time-bound code",
    startsAt: "2025-01-01T16:00:00Z",
    endsAt: "2025-01-22T12:00:00Z",
    useBackupAccessCodePool: true
  );

  Console.WriteLine("Created access code ID: " + createdAccessCode.AccessCodeId);
  Console.WriteLine("Is backup access code available: " + createdAccessCode.IsBackupAccessCodeAvailable);
  ```
</CodeGroup>

**Response:**

<CodeGroup>
  ```json JavaScript theme={null}
  {
    "access_code_id": "f863cb36-7f96-4b56-ac91-115742c31c00",
    "device_id": "6aae9d08-fed6-4ca5-8328-e36849ab48fe",
    "name": "my time-bound code",
    "appearance": null,
    "code": "8030",
    "common_code_key": null,
    "type": "time_bound",
    "status": "unset",
    "is_scheduled_on_device": false,
    "starts_at": "2025-01-01T16:00:00.000Z",
    "ends_at": "2025-01-22T12:00:00.000Z",
    "pulled_backup_access_code_id": null,
    "is_backup_access_code_available": true,
    "created_at": "2023-10-19T11:41:27.273Z",
    "errors": [],
    "warnings": [],
    "is_managed": true,
    "is_external_modification_allowed": false
  }
  ```

  ```json cURL theme={null}
  {
    "action_attempt": {
      "status": "pending",
      "action_type": "CREATE_ACCESS_CODE",
      "action_attempt_id": "7177edd7-3f99-46b9-bf4b-d3a9a16f6da9",
      "result": null,
      "error": null
    },
    "access_code": {
      "access_code_id": "ddb6e6b7-7156-471e-9199-4106db2f2e57",
      "device_id": "6aae9d08-fed6-4ca5-8328-e36849ab48fe",
      "name": "my time-bound code",
      "appearance": null,
      "code": "1185",
      "common_code_key": null,
      "type": "time_bound",
      "status": "unset",
      "is_scheduled_on_device": false,
      "starts_at": "2025-01-01T16:00:00.000Z",
      "ends_at": "2025-01-22T12:00:00.000Z",
      "pulled_backup_access_code_id": null,
      "is_backup_access_code_available": true,
      "created_at": "2023-10-19T08:23:50.789Z",
      "errors": [],
      "warnings": [],
      "is_managed": true,
      "is_external_modification_allowed": false
    },
    "ok": true
  }
  ```

  ```json Python theme={null}
  AccessCode(access_code_id='dc83d82d-55d2-4178-8c8c-10382311aed2',
             device_id='6aae9d08-fed6-4ca5-8328-e36849ab48fe',
             type='time_bound',
             code='9132',
             created_at='2023-10-19T05:07:03.693Z',
             errors=[],
             warnings=[],
             starts_at='2025-01-01T16:00:00.000Z',
             ends_at='2025-01-22T12:00:00.000Z',
             name='my time-bound code',
             status='unset',
             common_code_key=None,
             is_managed=True,
             is_waiting_for_code_assignment=None,
             is_scheduled_on_device=False,
             pulled_backup_access_code_id=None,
             is_backup_access_code_available=True,
             is_backup=None,
             appearance=None,
             is_external_modification_allowed=False)
  ```

  ```json Ruby theme={null}
  <Seam::AccessCode:0x00438
    code="2239"
    name="my time-bound code"
    type="time_bound"
    errors=[]
    status="unset"
    ends_at=2025-01-22 12:00:00 UTC
    warnings=[]
    device_id="6aae9d08-fed6-4ca5-8328-e36849ab48fe"
    starts_at=2025-01-01 16:00:00 UTC
    appearance=nil
    created_at=2023-10-25 04:17:43.323 UTC
    is_managed=true
    access_code_id="995d1927-e0db-4a97-b759-515193e6edbc"
    is_scheduled_on_device=false
    pulled_backup_access_code_id=nil
    is_backup_access_code_available=true
    is_external_modification_allowed=false>
  ```

  ```json C# theme={null}
  Created access code ID: 4ea6c172-cff7-4502-a766-f9293f36cba5
  Is backup access code available: True
  ```
</CodeGroup>

### 2. Detect when an access code has failed to program

When you receive an `access_code.failed_to_set_on_device` event through your Webhook, or notice a `failed_to_set_on_device` error on the access code object, that means that the access code has failed to program.

You can retrieve a backup access code to use instead.

### 3. Confirm the availability of a backup access code

To confirm that a backup access code is available for retrieval, check the `is_backup_access_code_available` property on the access code by inspecting the response from [Get Access Code](/api/access_codes/get) or [List Access Codes](/api/access_codes/list). If the backup code pool has been exhausted, this property returns `false`.

<Info>
  Note that we only support pulling backup codes for `time_bound` codes at this
  time.
</Info>

**Request:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  const accessCode = await seam.accessCodes.get({
    access_code_id: 'f863cb36-7f96-4b56-ac91-115742c31c00',
  })

  console.log(
    'Is backup access code available: ' +
      accessCode.is_backup_access_code_available,
  )
  ```

  ```bash cURL theme={null}
  # Use GET or POST.
  curl -X 'GET' \
    'https://connect.getseam.com/access_codes/get' \
    -H 'accept: application/json' \
    -H 'Authorization: Bearer ${API_KEY}' \
    -H 'Content-Type: application/json' \
    -d '{
    "access_code_id": "ddb6e6b7-7156-471e-9199-4106db2f2e57"
  }'
  ```

  ```python Python theme={null}
  access_code = seam.access_codes.get("dc83d82d-55d2-4178-8c8c-10382311aed2")

  pprint("Is backup access code available: "
      + str(access_code.is_backup_access_code_available))
  ```

  ```ruby Ruby theme={null}
  access_code = client.access_codes.get(access_code_id: "995d1927-e0db-4a97-b759-515193e6edbc")
  puts "Is backup access code available: #{access_code.is_backup_access_code_available}"
  ```

  ```php PHP theme={null}
  $access_code_id = "a91604eb-ebae-420c-a51e-07a30422fd94";

  $access_code = $seam->access_codes->get(
    access_code_id: $access_code_id
  );

  # Inspect access code is_backup_access_code_available
  echo json_encode($access_code->is_backup_access_code_available);
  # => true
  ```

  ```csharp C# theme={null}
  var accessCode = seam.AccessCodes.Get(accessCodeId: "4ea6c172-cff7-4502-a766-f9293f36cba5");
  Console.WriteLine("Created access code ID: " + accessCode.AccessCodeId);
  Console.WriteLine("Is backup access code available: " + accessCode.IsBackupAccessCodeAvailable);
  ```
</CodeGroup>

**Response:**

<CodeGroup>
  ```json JavaScript theme={null}
  Is backup access code available: true
  ```

  ```json cURL theme={null}
  {
    "access_code": {
      "access_code_id": "ddb6e6b7-7156-471e-9199-4106db2f2e57",
      .
      .
      .
      "is_backup_access_code_available": true,
      .
      .
      .
    },
    "ok": true
  }
  ```

  ```json Python theme={null}
  'Is backup access code available: True'
  ```

  ```json Ruby theme={null}
  Is backup access code available: true
  ```

  ```json C# theme={null}
  Created access code ID: 4ea6c172-cff7-4502-a766-f9293f36cba5
  Is backup access code available: True
  ```
</CodeGroup>

### 4. Retrieve a backup access code

To retrieve a backup access code for an access code, include the `access_code_id` in the [Pull Backup Access Codes](/api/access_codes/pull_backup_access_code) request. In the response, you receive the new backup access code. Be sure to share the new backup PIN code with the user of the original access code.

Upon executing this action, Seam performs the following additional actions:

* Mark the backup access code as pulled (`"pulled": true`), meaning that it has been removed from the pool.
* Associate the backup access code with the original access code, ensuring that any future requests to the [Pull Backup Access Code](/api/access_codes/pull_backup_access_code) request return the same backup access code.
* Update the `ends_at` date for the backup access code to match that of the original access code.
* Attempt to refill the backup access code pool with a new backup code.

**Request:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  const backupAccessCode = await seam.accessCodes.pullBackupAccessCode({
    access_code_id: 'f863cb36-7f96-4b56-ac91-115742c31c00',
  })

  console.log(backupAccessCode)
  ```

  ```bash cURL theme={null}
  curl -X 'POST' \
    'https://connect.getseam.com/access_codes/pull_backup_access_code' \
    -H 'accept: application/json' \
    -H 'Authorization: Bearer ${API_KEY}' \
    -H 'Content-Type: application/json' \
    -d '{
    "access_code_id": "ddb6e6b7-7156-471e-9199-4106db2f2e57"
  }'
  ```

  ```python Python theme={null}
  access_code_id = "dc83d82d-55d2-4178-8c8c-10382311aed2"

  backup_code = seam.access_codes.pull_backup_access_code(
      access_code = access_code_id
  )

  pprint(backup_code)
  ```

  ```ruby Ruby theme={null}
  access_code_id="995d1927-e0db-4a97-b759-515193e6edbc"
  puts client.access_codes.pull_backup_access_code(access_code_id: access_code_id).inspect
  ```

  ```php PHP theme={null}
  $access_code_id = "a91604eb-ebae-420c-a51e-07a30422fd94";

  $backup_code = $seam->access_codes->pull_backup_access_code(
    access_code_id: $access_code_id
  );

  # Inspect access codes
  echo json_encode($backup_code, JSON_PRETTY_PRINT);

  // {
  //     "access_code_id": "e9e353c9-acb1-454f-970b-2c011ba504d0",
  //     "device_id": "5a9dee23-e50f-4da7-88f3-fef38bf07857",
  //     "name": "Backup e9e353c9-acb1-454f-970b-2c011ba504d0 (Seam)",
  //     "type": "time_bound",
  //     "status": "set",
  //     "starts_at": "2023-09-16T20:59:37.069Z",
  //     "ends_at": "2025-01-22T12:00:00.000Z",
  //     "code": "3835",
  //     "created_at": "2023-09-16T20:18:26.070Z",
  //     "errors": [],
  //     "warnings": [],
  //     "is_managed": true,
  //     "common_code_key": null,
  //     "is_waiting_for_code_assignment": null,
  //     "is_scheduled_on_device": null,
  //     "pulled_backup_access_code_id": null,
  //     "is_backup_access_code_available": false,
  //     "is_backup": true
  // }
  ```

  ```csharp C# theme={null}
  var backupAccessCode = seam.AccessCodes.PullBackupAccessCode(accessCodeId: "4ea6c172-cff7-4502-a766-f9293f36cba5");
  Type t = backupAccessCode.GetType();
  foreach (var property in t.GetProperties())
  {
    Console.WriteLine(property.Name + ": " + property.GetValue(backupAccessCode));
  }
  ```
</CodeGroup>

**Response:**

<CodeGroup>
  ```json JavaScript theme={null}
  {
    "access_code_id": "284cc090-5d89-4e9d-a4ed-518c6cb68d99",
    "device_id": "6aae9d08-fed6-4ca5-8328-e36849ab48fe",
    "name": "Backup 284cc090-5d89-4e9d-a4ed-518c6cb68d99 (Seam)",
    "appearance": {
      "name": "Backup 284cc090-5d89-4e9d-a4ed-518c6cb68d99 (Seam)",
      "last_name": "284cc090-5d89-4e9d-a4ed-518c6cb68d99 (Seam)",
      "first_name": "Backup"
    },
    "code": "1275",
    "common_code_key": null,
    "type": "time_bound",
    "status": "set",
    "starts_at": "2023-10-19T11:50:21.092Z",
    "ends_at": "2025-01-22T12:00:00.000Z",
    "is_backup": true,
    "is_backup_access_code_available": false,
    "created_at": "2023-10-19T05:07:05.369Z",
    "errors": [],
    "warnings": [],
    "is_managed": true,
    "is_external_modification_allowed": false
  }
  ```

  ```json cURL theme={null}
  {
    "backup_access_code": {
      "access_code_id": "1e72a758-fbf5-433a-8c20-b379dd6df2d3",
      "device_id": "6aae9d08-fed6-4ca5-8328-e36849ab48fe",
      "name": "Backup 1e72a758-fbf5-433a-8c20-b379dd6df2d3 (Seam)",
      "appearance": {
        "name": "Backup 1e72a758-fbf5-433a-8c20-b379dd6df2d3 (Seam)",
        "last_name": "1e72a758-fbf5-433a-8c20-b379dd6df2d3 (Seam)",
        "first_name": "Backup"
      },
      "code": "4207",
      "common_code_key": null,
      "type": "time_bound",
      "status": "set",
      "starts_at": "2023-10-19T08:33:10.702Z",
      "ends_at": "2025-01-22T12:00:00.000Z",
      "is_backup": true,
      "is_backup_access_code_available": false,
      "created_at": "2023-10-19T05:07:05.205Z",
      "errors": [],
      "warnings": [],
      "is_managed": true,
      "is_external_modification_allowed": false
    },
    "ok": true
  }
  ```

  ```json Python theme={null}
  AccessCode(access_code_id='6db16e34-48d4-467a-856c-32a56b9cf0da',
             device_id='6aae9d08-fed6-4ca5-8328-e36849ab48fe',
             type='time_bound',
             code='7768',
             created_at='2023-10-19T05:07:05.548Z',
             errors=[],
             warnings=[],
             starts_at='2023-10-19T05:22:37.082Z',
             ends_at='2025-01-22T12:00:00.000Z',
             name='Backup 6db16e34-48d4-467a-856c-32a56b9cf0da (Seam)',
             status='set',
             common_code_key=None,
             is_managed=True,
             is_waiting_for_code_assignment=None,
             is_scheduled_on_device=None,
             pulled_backup_access_code_id=None,
             is_backup_access_code_available=False,
             is_backup=True,
             appearance={'first_name': 'Backup',
                         'last_name': '6db16e34-48d4-467a-856c-32a56b9cf0da '
                                      '(Seam)',
                         'name': 'Backup 6db16e34-48d4-467a-856c-32a56b9cf0da '
                                 '(Seam)'},
             is_external_modification_allowed=False)
  ```

  ```json Ruby theme={null}
  <Seam::AccessCode:0x00438
    access_code_id="9b0b88f1-160c-470f-b649-c8a7c9839b22"
    device_id="6aae9d08-fed6-4ca5-8328-e36849ab48fe"
    name="Backup 9b0b88f1-160c-470f-b649-c8a7c9839b22 (Seam)"
    appearance={"name"=>"Backup 9b0b88f1-160c-470f-b649-c8a7c9839b22 (Seam)", "last_name"=>"9b0b88f1-160c-470f-b649-c8a7c9839b22 (Seam)", "first_name"=>"Backup"}
    code="9501"
    type="time_bound"
    status="set"
    starts_at=2023-10-25 04:30:25.371 UTC
    ends_at=2025-01-22 12:00:00 UTC
    is_backup=true
    is_backup_access_code_available=false
    created_at=2023-10-19 05:07:05.963 UTC
    errors=[]
    warnings=[]
    is_managed=true
    is_external_modification_allowed=false>
  ```

  ```json C# theme={null}
  CommonCodeKey:
  IsScheduledOnDevice:
  Type: TimeBound
  IsWaitingForCodeAssignment:
  AccessCodeId: eb140acf-c857-4a84-871b-52afa8c4f7b7
  DeviceId: 6aae9d08-fed6-4ca5-8328-e36849ab48fe
  Name: Backup eb140acf-c857-4a84-871b-52afa8c4f7b7 (Seam)
  Code: 6219
  CreatedAt: 2023-10-25T04:41:11.212Z
  Errors: []
  Warnings: []
  IsManaged: True
  StartsAt: 2023-10-28T03:40:08.035Z
  EndsAt: 2025-01-22T12:00:00.000Z
  Status: Set
  IsBackupAccessCodeAvailable: False
  IsBackup: True
  PulledBackupAccessCodeId:
  IsExternalModificationAllowed: False
  ```
</CodeGroup>

***

## Troubleshooting

When you have the backup access code pool feature enabled for a device, be on the lookout for the following warnings and errors on the device:

### Warning: `many_active_backup_codes`

Multiple back up codes have been pulled from the device. This usually indicates that Seam is having issues programming access codes onto the device. Check if the device is offline or if there are other issues.

### Warning: `partial_backup_access_code_pool`

Seam is having trouble refilling the back up access code pool. This could result from device connection issues or from the device running out of space for new codes.

### Error: `empty_backup_access_code_pool`

There are no more back up codes available in the pool. This can happen when you've just enabled the back up pool feature, or when all of the backup access codes have been used.

***

## Supported Brands

All door locks with the `access_code` capability are expected to support this feature, with the exception of Salto locks.


# Creating Access Codes
Source: https://docs.seam.co/low-level-apis/smart-locks/access-codes/creating-access-codes/index

Learn how to program an access code onto a smart lock with a keypad, and ensure the code is successfully set.

<Warning>
  This is a low-level API. For granting a person access, use [Access
  Grants](/use-cases/granting-access/index)—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](mailto:support@seam.co)).
</Warning>

## Overview

This guide explains how to create online access codes on an online smart lock. With the [Access Codes](/api/access_codes/object) 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:

1. **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](/api/access_codes/delete) endpoint.
2. **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.

<Info>
  For more information about creating offline access codes, see [Managing
  Offline Access
  Codes](../../../../low-level-apis/smart-locks/access-codes/offline-access-codes).
</Info>

***

## Before You Begin: Confirm Capabilities

Before you attempt to create an [online](/low-level-apis/smart-locks/access-codes/index#what-is-an-access-code) or [offline](/low-level-apis/smart-locks/access-codes/index#offline-access-codes) 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](/capability-guides/device-and-system-capabilities#capability-flags) for the device:

* `device.can_program_online_access_codes`
* `device.can_program_offline_access_codes`

Use [Get Device](/api/devices/get) 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](/api/devices/object) of the device, [errors or warnings](/api/devices/errors) for the device, and [events](/api/devices/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:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  await seam.devices.get({ device_id: '11111111-1111-1111-1111-444444444444' })
  ```

  ```bash cURL theme={null}
  # 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"
  }'
  ```

  ```python Python theme={null}
  seam.devices.get(device_id="11111111-1111-1111-1111-444444444444")
  ```

  ```ruby Ruby theme={null}
  client.devices.get(device_id: "11111111-1111-1111-1111-444444444444")
  ```

  ```php PHP theme={null}
  $seam->devices->get(device_id: "11111111-1111-1111-1111-444444444444");
  ```

  ```csharp C# theme={null}
  seam.Devices.Get(deviceId: "11111111-1111-1111-1111-444444444444");
  ```
</CodeGroup>

**Response:**

<CodeGroup>
  ```json JavaScript theme={null}
  {
    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.
    ...
  }
  ```

  ```json cURL theme={null}
  {
    "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
  }
  ```

  ```json Python theme={null}
  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.
    ...
  )
  ```

  ```json Ruby theme={null}
  <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.
    ...
  >
  ```

  ```json PHP theme={null}
  {
    "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.
    ...
  }
  ```

  ```json C# theme={null}
  {
    "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.
    ...
  }
  ```
</CodeGroup>

***

## 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.

<img
  alt="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](/api/access_codes/create). Assign an optional `name` to the access code for easier identification within the [Seam Console](https://console.seam.co) 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](../../../../low-level-apis/smart-locks/access-codes/access-code-requirements-for-door-locks) to understand any requirements specific to the door lock.

**Request:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  // 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',
    })
  }
  ```

  ```bash cURL theme={null}
  # 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
  ```

  ```python Python theme={null}
  # 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"
    )
  ```

  ```ruby Ruby theme={null}
  # 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
  ```

  ```php PHP theme={null}
  // 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"
    );
  }
  ```

  ```csharp C# theme={null}
  // 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"
    );
  }
  ```
</CodeGroup>

**Response:**

<CodeGroup>
  ```json JavaScript theme={null}
  {
    access_code_id: '11111111-1111-1111-1111-555555555555',
    device_id: '11111111-1111-1111-1111-444444444444',
    name: 'my ongoing code',
    code: '1234',
    type: 'ongoing',
    ...
  }
  ```

  ```json cURL theme={null}
  {
    "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
  }
  ```

  ```json Python theme={null}
  AccessCode(
    access_code_id='11111111-1111-1111-1111-555555555555',
    device_id='11111111-1111-1111-1111-444444444444',
    type='ongoing',
    code='1234',
    name='my ongoing code',
    ...
  )
  ```

  ```json Ruby theme={null}
  <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"
    ...
  >
  ```

  ```json PHP theme={null}
  {
    "access_code_id": "11111111-1111-1111-1111-555555555555",
    "device_id": "11111111-1111-1111-1111-444444444444",
    "name": "my ongoing code",
    "type": "ongoing",
    "code": "1234",
    ...
  }
  ```

  ```json C# theme={null}
  {
    "type": "ongoing",
    "access_code_id": "11111111-1111-1111-1111-555555555555",
    "device_id": "11111111-1111-1111-1111-444444444444",
    "name": "my ongoing code",
    "code": "1234",
    ...
  }
  ```
</CodeGroup>

### 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 `status` is updated
* **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](/api/access_codes/get) 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 [the guide on "Troubleshooting Access Code Issues"](../../../../low-level-apis/smart-locks/access-codes/troubleshooting-access-code-issues) for further guidance.

<img alt="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.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.

In the event of delay or failure, refer to [the "Troubleshooting access code issues" guide](../../../../low-level-apis/smart-locks/access-codes/troubleshooting-access-code-issues) for assistance and mitigation strategies.

<img alt="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.

<img
  alt="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](https://www.iso.org/iso-8601-date-and-time-format.html) timestamps to define the active time window for the code. For more details, see the [Create Access Code](/api/access_codes/create) 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](../../../../low-level-apis/smart-locks/access-codes/access-code-requirements-for-door-locks) to understand any requirements specific to the door lock brand.

**Request:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  // 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',
    })
  }
  ```

  ```sh cURL theme={null}
  # 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
  ```

  ```python Python theme={null}
  # 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"
    )
  ```

  ```ruby Ruby theme={null}
  # 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
  ```

  ```php PHP theme={null}
  // 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"
    );
  }
  ```

  ```csharp C# theme={null}
  // 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"
    );
  }
  ```
</CodeGroup>

**Response:**

<CodeGroup>
  ```json JavaScript theme={null}
  {
    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',
    ...
  }
  ```

  ```json cURL theme={null}
  {
    "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
  }
  ```

  ```json Python theme={null}
  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',
    ...
  )
  ```

  ```json Ruby theme={null}
  <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
    ...
  >
  ```

  ```json PHP theme={null}
  {
    "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"
  }
  ```

  ```json C# theme={null}
  {
    "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",
    ...
  }
  ```
</CodeGroup>

### 2. Verify Successful Time-Bound Code Programming

The [lifecycle of a time-bound access code](../../../../low-level-apis/smart-locks/access-codes/lifecycle-of-access-codes) is marked by distinct phases:

1. `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.
2. `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`.
3. `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.

<img alt="Life-cycle of a time-bound access code" />

On door locks that support [natively scheduled](/low-level-apis/smart-locks/access-codes/index#native-scheduling) 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, [please refer to this guide](../../../../low-level-apis/smart-locks/access-codes/lifecycle-of-access-codes).

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**

Use the `access_code` reference returned by the create function to call the [Get Access Code](/api/access_codes/get) 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 [the "Troubleshooting Access Code Issues" guide](../../../../low-level-apis/smart-locks/access-codes/troubleshooting-access-code-issues) for assistance.

<img alt="" />

### **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.

In the event of delay or failure, refer to [the "Troubleshooting access code issues" guide](../../../../low-level-apis/smart-locks/access-codes/troubleshooting-access-code-issues) for assistance and mitigation strategies.

<img alt="" />


# Understanding Code Constraints
Source: https://docs.seam.co/low-level-apis/smart-locks/access-codes/creating-access-codes/understanding-code-constraints

Learn about manufacturer- and device-specific constraints on codes.

When creating access codes, it is important to be aware of any constraints on the `code`. [Get a device](/api/devices/get) and review its `device.properties.code_constraints`. Seam represents each constraint as an object with a `constraint_type` property. Depending on the constraint type, there may also be additional properties. Note that some constraints are manufacturer- or device-specific.

The `constraint_type` property can be any of the following enum values:

<table>
  <thead>
    <tr>
      <th>Constraint Type</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        <code>no\_zeros</code>
      </td>

      <td>
        Cannot use <code>0</code>s as digits in the PIN code.
      </td>
    </tr>

    <tr>
      <td>
        <code>cannot\_start\_with\_12</code>
      </td>

      <td>
        PIN code cannot start with the sequence of digits <code>12</code>.
      </td>
    </tr>

    <tr>
      <td>
        <code>no\_triple\_consecutive\_ints</code>
      </td>

      <td>
        No more than three digits in a row can be consecutive or the same in the
        PIN code.
      </td>
    </tr>

    <tr>
      <td>
        <code>cannot\_specify\_pin\_code</code>
      </td>

      <td>
        Cannot specify a PIN code. You must leave the code empty, and the lock
        provider generates a PIN code.
      </td>
    </tr>

    <tr>
      <td>
        <code>pin\_code\_matches\_existing\_set</code>
      </td>

      <td>
        <p>
          If you specify a PIN code, it must match an existing set of PIN codes
          used in the account.
        </p>

        <p>
          For example, the PIN code could match the code assigned to a user in
          the system.
        </p>
      </td>
    </tr>

    <tr>
      <td>
        <code>start\_date\_in\_future</code>
      </td>

      <td>For time-bound codes, the start date must be in the future.</td>
    </tr>

    <tr>
      <td>
        <code>no\_ascending\_or\_descending\_sequence</code>
      </td>

      <td>PIN code cannot consist of a sequence of consecutive digits.</td>
    </tr>

    <tr>
      <td>
        <code>at\_least\_three\_unique\_digits</code>
      </td>

      <td>PIN code must contain at least three unique digits.</td>
    </tr>

    <tr>
      <td>
        <code>no\_all\_same\_digits</code>
      </td>

      <td>
        PIN code cannot consist entirely of the same repeated digit (for
        example, <code>1111</code> is invalid).
      </td>
    </tr>

    <tr>
      <td>
        <code>unique\_first\_four\_digits</code>
      </td>

      <td>The first four digits of the PIN code must all be distinct.</td>
    </tr>

    <tr>
      <td>
        <code>cannot\_contain\_089</code>
      </td>

      <td>
        <p>
          PIN code cannot contain the digits <code>0</code>, <code>8</code>, or
          <code>9</code>.
        </p>

        <p>
          For example, this restriction could apply to a cylinder lock that only
          includes the digits <code>1</code> to <code>7</code>.
        </p>
      </td>
    </tr>

    <tr>
      <td>
        <code>cannot\_contain\_0789</code>
      </td>

      <td>
        <p>
          PIN code cannot contain the digits <code>0</code>, <code>7</code>,
          <code>8</code>, or <code>9</code>.
        </p>

        <p>
          For example, this restriction could apply to a cylinder lock that only
          includes the digits <code>1</code> to <code>6</code>.
        </p>
      </td>
    </tr>

    <tr>
      <td>
        <code>name\_length</code>
      </td>

      <td>
        <p>Name of the code has some restrictions on length.</p>

        <p>
          When the <code>constraint\_type</code> is <code>name\_length</code>, the
          constraint object has one or two additional properties called
          <code>min\_length</code> and <code>max\_length</code> to specify the
          length constraints.
        </p>
      </td>
    </tr>

    <tr>
      <td>
        <code>name\_must\_be\_unique</code>
      </td>

      <td>Name of the code must be unique within the device.</td>
    </tr>
  </tbody>
</table>

***

## Provider-Specific Requirements

In addition to code constraints, some device providers have additional requirements for creating access codes.

### Timezone Configuration

Some device providers require you to configure the device's timezone before creating time-bound access codes. This is because these devices schedule access codes using device-local time, but their APIs do not report the device's timezone.

**Providers requiring timezone configuration:**

* **Ultraloq** — Must configure timezone using `/devices/report_provider_metadata` before creating time-bound access codes. See [Configuring Ultraloq Device Timezones](/device-and-system-integration-guides/ultraloq-locks/configuring-ultraloq-device-timezones).

<Info>
  Permanent access codes (codes without `starts_at` and `ends_at`) do not
  require timezone configuration, even on providers that require it for
  time-bound codes.
</Info>

**Detecting timezone requirement:**

Check for the provider-specific timezone warning in `device.warnings`:

<CodeGroup>
  ```javascript JavaScript theme={null}
  import { Seam } from 'seam'

  const seam = new Seam()

  const device = await seam.devices.get({
    device_id: 'your-device-id',
  })

  // Check for timezone warnings
  const timezoneWarnings = device.warnings.filter((w) =>
    w.warning_code.toLowerCase().includes('time_zone'),
  )

  if (timezoneWarnings.length > 0) {
    console.log('⚠️ Timezone configuration required for time-bound codes')
    console.log(`Warning: ${timezoneWarnings[0].message}`)
  }
  ```

  ```bash cURL theme={null}
  device=$(curl -X 'POST' \
    'https://connect.getseam.com/devices/get' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d "{
      \"device_id\": \"your-device-id\"
    }")

  # Check for timezone warnings
  echo $device | jq '.device.warnings[] | select(.warning_code | test("time_zone"; "i"))'
  ```

  ```python Python theme={null}
  from seam import Seam

  seam = Seam()

  device = seam.devices.get(device_id="your-device-id")

  # Check for timezone warnings
  timezone_warnings = [
    w for w in device.warnings
    if "time_zone" in w.warning_code.lower()
  ]

  if timezone_warnings:
    print("⚠️ Timezone configuration required for time-bound codes")
    print(f"Warning: {timezone_warnings[0].message}")
  ```

  ```ruby Ruby theme={null}
  require "seam"

  seam = Seam.new()

  device = seam.devices.get(device_id: "your-device-id")

  # Check for timezone warnings
  timezone_warnings = device.warnings.select do |w|
    w.warning_code.downcase.include?("time_zone")
  end

  if timezone_warnings.any?
    puts "⚠️ Timezone configuration required for time-bound codes"
    puts "Warning: #{timezone_warnings[0].message}"
  end
  ```

  ```php PHP theme={null}
  <?php
  require 'vendor/autoload.php';

  use Seam\SeamClient;

  $seam = new SeamClient();

  $device = $seam->devices->get(device_id: "your-device-id");

  // Check for timezone warnings
  $timezoneWarnings = array_filter($device->warnings, function($w) {
    return stripos($w->warning_code, "time_zone") !== false;
  });

  if (count($timezoneWarnings) > 0) {
    echo "⚠️ Timezone configuration required for time-bound codes\n";
    echo "Warning: " . array_values($timezoneWarnings)[0]->message . "\n";
  }
  ```

  ```csharp C# theme={null}
  using Seam.Client;
  using System.Linq;

  var seam = new SeamClient();

  var device = seam.Devices.Get(deviceId: "your-device-id");

  // Check for timezone warnings
  var timezoneWarnings = device.Warnings
    .Where(w => w.WarningCode.ToLower().Contains("time_zone"))
    .ToList();

  if (timezoneWarnings.Any())
  {
    Console.WriteLine("⚠️ Timezone configuration required for time-bound codes");
    Console.WriteLine($"Warning: {timezoneWarnings[0].Message}");
  }
  ```

  ```java Java theme={null}
  import com.seam.api.Seam;
  import com.seam.api.types.Device;
  import java.util.stream.Collectors;

  Seam seam = Seam.builder().build();

  Device device = seam.devices().get(
    DevicesGetRequest.builder()
      .deviceId("your-device-id")
      .build()
  );

  // Check for timezone warnings
  var timezoneWarnings = device.getWarnings().stream()
    .filter(w -> w.getWarningCode().toLowerCase().contains("time_zone"))
    .collect(Collectors.toList());

  if (!timezoneWarnings.isEmpty()) {
    System.out.println("⚠️ Timezone configuration required for time-bound codes");
    System.out.println("Warning: " + timezoneWarnings.get(0).getMessage());
  }
  ```
</CodeGroup>

For devices requiring timezone configuration, attempting to create a time-bound access code without first setting the timezone will result in a validation error.


# Understanding Time Frame Options
Source: https://docs.seam.co/low-level-apis/smart-locks/access-codes/creating-access-codes/understanding-time-frame-options

Learn about manufacturer- and device-specific limits on the time frame of an access code.

Some devices only accept access codes whose time frame—its duration and, sometimes, its time of day or calendar dates—falls within limits that the lock or its manufacturer enforces. When creating a time-bound access code, [get the device](/api/devices/get) and review two `device.properties` so that you can build a valid time frame **before** you call [`/access_codes/create`](/api/access_codes/create), rather than discovering the constraint from an error.

* `device.properties.offline_time_frame_options` applies to **offline** access codes.
* `device.properties.online_time_frame_options` applies to **online** access codes.

Each property is an **array of options**. An option is one self-contained way to make a code: a duration band plus any time-of-day and date rules that apply within it. To create a valid code, pick **one** option and satisfy **all** of its rules.

These properties are split by code type because you always know which kind of code you are creating, so you read the matching property directly. Splitting them also lets a provider express different limits per code type—for example, a device that allows a longer duration for online codes than for offline codes.

<Info>
  Read these options from the device at request time and build your time frame from the values you find—do not hardcode limits per manufacturer. Providers gain support and adjust their bounds over time, so a device's current `time_frame_options` are always the source of truth.
</Info>

<Info>
  When a property is `undefined`, any time frame works for that code type on that device—there are no time-frame limits to observe. A device may define one property and leave the other `undefined`. For example, a lock that only programs online codes exposes `online_time_frame_options` and leaves `offline_time_frame_options` unset. Standard online locks and thermostats leave both `undefined`.
</Info>

## The Time Frame Option Object

| Property                     | Type                       | Description                                                                                                                                                                                                                                               |
| ---------------------------- | -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `display_name`               | string                     | Human-readable label. Always present. For a single-option device, typically the product name (for example, `algoPIN` or `SmartPIN`); for a multi-option device, a label that distinguishes the options (for example, `Hourly` or `Fixed check-in times`). |
| `min_duration`               | string (ISO 8601 duration) | Shortest duration this option covers, for example `PT1H` or `P29D`. Omitted when there is no minimum.                                                                                                                                                     |
| `max_duration`               | string (ISO 8601 duration) | Longest duration this option covers, for example `PT672H` or `P367D`. Omitted when there is no maximum.                                                                                                                                                   |
| `matching_start_end_time`    | `true`                     | When present, the check-in and check-out must be at the **same time of day** (you choose which). Mutually exclusive with `time_pairs`.                                                                                                                    |
| `time_pairs`                 | array                      | Fixed check-in/check-out pairings to choose from. See [The time pair object](#the-time-pair-object). Mutually exclusive with `matching_start_end_time`.                                                                                                   |
| `start_date_recurrence_rule` | string (RRULE)             | iCalendar recurrence rule that the **check-in date** must fall on, for example `FREQ=MONTHLY;BYDAY=1MO,3MO` for the first and third Monday of each month. Constrains which calendar dates are selectable, independent of the time-of-day rules.           |
| `end_date_recurrence_rule`   | string (RRULE)             | iCalendar recurrence rule that the **check-out date** must fall on.                                                                                                                                                                                       |
| `time_zone`                  | string (IANA time zone)    | Time zone used to interpret `time_pairs` and the date recurrence rules. Present only when the option fixes times or dates.                                                                                                                                |

Every property except `display_name` is optional, and the **absence of a rule means unrestricted on that axis**. An option with only `min_duration` and `max_duration` constrains duration and nothing else—any time of day, any date. An option with only `max_duration` means "any time frame up to that length."

<Info>
  `start_date_recurrence_rule` and `end_date_recurrence_rule` are part of the schema for forward compatibility, but no provider populates them yet. Today, every option either leaves the date axis unrestricted or fixes times of day through `time_pairs`.
</Info>

### The Time Pair Object

| Property       | Type                      | Description                                                                                                                     |
| -------------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `display_name` | string                    | Label for the pairing, for example `Standard`, `Late arrival`, or `8 AM – 8 PM`.                                                |
| `start_time`   | string (`HH:MM`, 24-hour) | Start time of day (check-in), interpreted in the option's `time_zone`.                                                          |
| `end_time`     | string (`HH:MM`, 24-hour) | End time of day (check-out). An `end_time` earlier on the clock than `start_time` means that the end falls on a **later date**. |

A time pair is atomic: you pick one whole pairing, and you cannot mix a `start_time` from one pair with an `end_time` from another.

## Choosing an Option

1. **Filter by duration.** Compute your requested duration and keep the options whose `[min_duration, max_duration]` band contains it.
2. **Disambiguate.** How you land on a single option depends on whether the options' duration ranges overlap:
   * **Non-overlapping ranges (the common case):** The requested duration falls into exactly one option, so the duration alone selects it. You just enter dates.
   * **Overlapping ranges:** Duration cannot disambiguate, so the options are genuine alternatives that you choose between by `display_name`.
3. **Satisfy that option's rules.** Honor its time-of-day rule (`matching_start_end_time` or one `time_pairs` entry) and any `start_date_recurrence_rule` or `end_date_recurrence_rule`, interpreting times and dates in `time_zone`.

You do not need a flag to tell these cases apart—it falls out of the ranges. If two options can both accept the requested duration, present them as a choice; otherwise, route by duration.

<Warning>
  When `start_date_recurrence_rule` or `end_date_recurrence_rule` is present, `max_duration` caps the range, but the only valid dates are recurrence dates within that cap. Offer only recurrence dates within the duration bound, not every date up to the cap.
</Warning>

## Examples

### Duration-Only Option

For example, an igloohome `algoPIN` hourly code accepts any time of day, from one hour to 28 days:

```json theme={null}
{ "display_name": "Hourly", "min_duration": "PT1H", "max_duration": "PT672H" }
```

### Matching Start and End Time

For example, an igloohome `algoPIN` daily code covers 29 to 367 days, and the check-in and check-out must be at the same time of day:

```json theme={null}
{
  "display_name": "Daily",
  "min_duration": "P29D",
  "max_duration": "P367D",
  "matching_start_end_time": true
}
```

### Fixed Time Pairs

For example, a Dormakaba Oracode offline code offers the fixed check-in/check-out pairings defined for the door, up to 31 days, in the lock's local time zone:

```json theme={null}
{
  "display_name": "Fixed check-in times",
  "max_duration": "P31D",
  "time_zone": "America/Los_Angeles",
  "time_pairs": [
    { "display_name": "Standard", "start_time": "15:00", "end_time": "11:00" },
    { "display_name": "Late arrival", "start_time": "16:00", "end_time": "10:00" }
  ]
}
```

### Multiple Options on One Property

For example, an igloohome `algoPIN` device exposes two duration-matched offline options. The ranges don't overlap, so Seam selects the option by the requested duration—you never pick. Its online (bridge) codes are unconstrained, so `online_time_frame_options` is `undefined`.

```json theme={null}
"offline_time_frame_options": [
  { "display_name": "Hourly", "min_duration": "PT1H", "max_duration": "PT672H" },
  {
    "display_name": "Daily",
    "min_duration": "P29D",
    "max_duration": "P367D",
    "matching_start_end_time": true
  }
]
```

As another example, a KeyInCode `SmartPIN` device programs online codes only and exposes two duration-matched online options: short-term codes are unrestricted on time of day, while long-term codes are fixed to an 8 AM check-in and 8 PM check-out in the lock's location time zone. Its `offline_time_frame_options` is `undefined`.

```json theme={null}
"online_time_frame_options": [
  { "display_name": "Short-term", "max_duration": "P32D" },
  {
    "display_name": "Long-term",
    "min_duration": "P33D",
    "max_duration": "P365D",
    "time_zone": "America/Los_Angeles",
    "time_pairs": [
      { "display_name": "8 AM – 8 PM", "start_time": "08:00", "end_time": "20:00" }
    ]
  }
]
```

## Related Resources

* [Understanding Code Constraints](/low-level-apis/smart-locks/access-codes/creating-access-codes/understanding-code-constraints)
* [Creating Access Codes](/low-level-apis/smart-locks/access-codes/creating-access-codes/index)
* [API Reference: `device` Properties](/api/devices)


# Creating and Updating Multiple Linked Access Codes
Source: https://docs.seam.co/low-level-apis/smart-locks/access-codes/creating-and-updating-multiple-linked-access-codes

Learn how to create and update groups of access codes with the same code for properties with multiple door locks.

Users with more than one door lock in a property may want to create groups of linked access codes, all of which have the same code (PIN). For example, a short-term rental host may want to provide guests the same PIN for both a front door lock and a back door lock. In this case, use [`/access_codes/create_multiple`](/api/access_codes/create_multiple). Specify the `device_id` of each device for which you want to create linked access codes. You can also include additional optional properties, such as the following:

* A name to apply to all of the access codes.
* The `preferred_code_length`.
* Whether to throw an error or create a random code if any of the included devices cannot share a code.
* Starting and ending timestamps if you want to create time-bound access codes.

When you use `/access_codes/create_multiple`, Seam assigns a `common_code_key` to all of the created access codes and returns this key. The `common_code_key` identifies all the access codes within this linked group.

Then, you can change the starting or ending time for the group of access codes—for example, if a short-term rental guest requests an early check-in or late checkout. To update a group of linked access codes, use [`/access_codes/update_multiple`](/api/access_codes/update_multiple), specifying the `common_code_key` of the linked access code group, along with the replacement starting and ending timestamps.

***

## Specifying Custom Codes

When you use `/access_codes/create_multiple`, you can specify a custom `code`. Seam assigns this custom `code` to each of the resulting access codes. However, in this case, Seam does not link these access codes together with a `common_code_key`. That is, `common_code_key` remains null for these access codes.

If you want to change these access codes that are not linked by a `common_code_key`, you cannot use `/access_codes/update_multiple`. However, you can update each of these access codes individually, using [`/access_codes/update`](/api/access_codes/update).

***

## Create Linked Access Codes

The following example creates two linked access codes for two devices.

**Request:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  // Create the group of linked access codes.
  // Each returned access code includes a common_code_key.
  await seam.accessCodes.createMultiple({
    device_ids: [
      '8e94044d-a4d1-4691-9f7e-e97d3e8a0b73',
      'd87eea5d-71c6-4633-a966-396c5ac51177',
    ],
    name: "Jane's reservation",
    starts_at: '2024-11-15T15:00:00Z',
    ends_at: '2024-11-17T11:00:00Z',
    preferred_code_length: 4,
  })
  ```

  ```sh cURL theme={null}
  # Create the group of linked access codes.
  # Each returned access code includes a common_code_key.
  curl -X 'POST' \
    'https://connect.getseam.com/access_codes/create_multiple' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d '{
      "device_ids": [
        "8e94044d-a4d1-4691-9f7e-e97d3e8a0b73",
        "d87eea5d-71c6-4633-a966-396c5ac51177"
      ],
      "name": "Jane'\''s reservation",
      "starts_at": "2024-11-15T15:00:00Z",
      "ends_at": "2024-11-17T11:00:00Z",
      "preferred_code_length": 4
  }'
  ```

  ```python Python theme={null}
  # Create the group of linked access codes.
  # Each returned access code includes a common_code_key.
  seam.access_codes.create_multiple(
    device_ids = [
      "8e94044d-a4d1-4691-9f7e-e97d3e8a0b73",
      "d87eea5d-71c6-4633-a966-396c5ac51177"
    ],
    name = "Jane's reservation",
    starts_at = "2024-11-15T15:00:00Z",
    ends_at = "2024-11-17T11:00:00Z",
    preferred_code_length = 4
  )
  ```

  ```ruby Ruby theme={null}
  # Create the group of linked access codes.
  # Each returned access code includes a common_code_key.
  client.access_codes.create_multiple(
    device_ids: [
      "8e94044d-a4d1-4691-9f7e-e97d3e8a0b73",
      "d87eea5d-71c6-4633-a966-396c5ac51177"
    ],
    name: "Jane's reservation",
    starts_at: "2024-11-15T15:00:00Z",
    ends_at: "2024-11-17T11:00:00Z",
    preferred_code_length: 4
  )
  ```

  ```php PHP theme={null}
  // Create the group of linked access codes.
  // Each returned access code includes a common_code_key.
  $seam->access_codes->create_multiple(
    device_ids: [
      "8e94044d-a4d1-4691-9f7e-e97d3e8a0b73",
      "d87eea5d-71c6-4633-a966-396c5ac51177"
    ],
    name: "Jane's reservation",
    starts_at: "2024-11-15T15:00:00Z",
    ends_at: "2024-11-17T11:00:00Z",
    preferred_code_length: 4
  );
  ```

  ```csharp C# theme={null}
  // Create the group of linked access codes.
  // Each returned access code includes a common_code_key.
  seam.AccessCodes.CreateMultiple(
    deviceIds: new List<string>(new string[] {
      "8e94044d-a4d1-4691-9f7e-e97d3e8a0b73",
     "d87eea5d-71c6-4633-a966-396c5ac51177"
    }),
    name: "Jane's reservation",
    startsAt: "2024-11-15T15:00:00Z",
    endsAt: "2024-11-17T11:00:00Z",
    preferredCodeLength: 4
  );
  ```
</CodeGroup>

**Response:**

<CodeGroup>
  ```json JavaScript theme={null}
  [
    {
      access_code_id: 'a1c682b1-c909-473f-926a-442a4ffc54c2',
      name: "Jane's reservation",
      device_id: '8e94044d-a4d1-4691-9f7e-e97d3e8a0b73',
      code: '5974',
      common_code_key: 'auto_set_by_create_multiple_72f81ee3-997f-4fdc-81d0-289dabc28ae7',
      starts_at: '2024-12-15T15:00:00.000Z',
      ends_at: '2024-12-17T11:00:00.000Z',
      ...
    },
    {
      access_code_id: '49261a24-103c-4880-8e58-d1d98f301ba7',
      name: "Jane's reservation",
      device_id: 'd87eea5d-71c6-4633-a966-396c5ac51177',
      code: '5974',
      common_code_key: 'auto_set_by_create_multiple_72f81ee3-997f-4fdc-81d0-289dabc28ae7',
      starts_at: '2024-12-15T15:00:00.000Z',
      ends_at: '2024-12-17T11:00:00.000Z',
      ...
    }
  ]
  ```

  ```json cURL theme={null}
  {
    "access_codes": [
      {
        "access_code_id": "d7369c78-77a5-4c95-b6f0-d218e9eb82e0",
        "name": "Jane's reservation",
        "device_id": "8e94044d-a4d1-4691-9f7e-e97d3e8a0b73",
        "code": "2156",
        "common_code_key": "auto_set_by_create_multiple_ba3a361f-4acb-4122-9cce-12b164e70554",
        "starts_at": "2024-11-15T15:00:00.000Z",
        "ends_at": "2024-11-17T11:00:00.000Z",
        ...
      },
      {
        "access_code_id": "0f14fed0-00f0-49bf-bfee-262120844b5a",
        "name": "Jane's reservation",
        "device_id": "d87eea5d-71c6-4633-a966-396c5ac51177",
        "code": "2156",
        "common_code_key": "auto_set_by_create_multiple_ba3a361f-4acb-4122-9cce-12b164e70554",
        "starts_at": "2024-11-15T15:00:00.000Z",
        "ends_at": "2024-11-17T11:00:00.000Z",
        ...
      }
    ],
    "ok":true
  }
  ```

  ```json Python theme={null}
  [
    AccessCode(
      access_code_id='4ae69d7a-de72-4bb0-a32e-afc2ac025e2e',
      name="Jane's reservation",
      device_id='8e94044d-a4d1-4691-9f7e-e97d3e8a0b73',
      code='2709',
      common_code_key='auto_set_by_create_multiple_a11a027a-5070-47f5-aabf-279051117b0d',
      starts_at='2024-11-15T15:00:00.000Z',
      ends_at='2024-11-17T11:00:00.000Z',
      ...
    ),
    AccessCode(
      access_code_id='adcd39ff-a334-4890-9904-0c056d8f8f8c',
      name="Jane's reservation",
      device_id='d87eea5d-71c6-4633-a966-396c5ac51177',
      code='2709',
      common_code_key='auto_set_by_create_multiple_a11a027a-5070-47f5-aabf-279051117b0d',
      starts_at='2024-11-15T15:00:00.000Z',
      ends_at='2024-11-17T11:00:00.000Z',
      ...
    )
  ]
  ```

  ```json Ruby theme={null}
  <Seam::AccessCode:0x00438
    access_code_id="a1c682b1-c909-473f-926a-442a4ffc54c2"
    name="Jane's reservation"
    device_id="8e94044d-a4d1-4691-9f7e-e97d3e8a0b73"
    code="5974"
    common_code_key="auto_set_by_create_multiple_72f81ee3-997f-4fdc-81d0-289dabc28ae7"
    starts_at=2024-12-15 15:00:00 UTC
    ends_at=2024-12-17 11:00:00 UTC
    ...
  >,
  <Seam::AccessCode:0x00438
    access_code_id="49261a24-103c-4880-8e58-d1d98f301ba7"
    name="Jane's reservation"
    device_id="d87eea5d-71c6-4633-a966-396c5ac51177"
    code="5974"
    common_code_key="auto_set_by_create_multiple_72f81ee3-997f-4fdc-81d0-289dabc28ae7"
    starts_at=2024-12-15 15:00:00 UTC
    ends_at=2024-12-17 11:00:00 UTC
    ...
  >
  ```

  ```json PHP theme={null}
  [
    {
      "access_code_id": "a1c682b1-c909-473f-926a-442a4ffc54c2",
      "name": "Jane's reservation",
      "device_id": "8e94044d-a4d1-4691-9f7e-e97d3e8a0b73",
      "code": "5974",
      "common_code_key": "auto_set_by_create_multiple_72f81ee3-997f-4fdc-81d0-289dabc28ae7",
      "starts_at": "2024-12-15T15:00:00.000Z",
      "ends_at": "2024-12-17T11:00:00.000Z",
      ...
    },
    {
      "access_code_id": "49261a24-103c-4880-8e58-d1d98f301ba7",
      "name": "Jane's reservation",
      "device_id": "d87eea5d-71c6-4633-a966-396c5ac51177",
      "code": "5974",
      "common_code_key": "auto_set_by_create_multiple_72f81ee3-997f-4fdc-81d0-289dabc28ae7",
      "starts_at": "2024-12-15T15:00:00.000Z",
      "ends_at": "2024-12-17T11:00:00.000Z",
      ...
    }
  ]
  ```

  ```json C# theme={null}
  [
    {
      "access_code_id": "a1c682b1-c909-473f-926a-442a4ffc54c2",
      "name": "Jane's reservation",
      "device_id": "8e94044d-a4d1-4691-9f7e-e97d3e8a0b73",
      "code": "5974",
      "common_code_key": "auto_set_by_create_multiple_72f81ee3-997f-4fdc-81d0-289dabc28ae7",
      "starts_at": "2024-12-15T15:00:00.000Z",
      "ends_at": "2024-12-17T11:00:00.000Z",
      ...
    },
    {
      "access_code_id": "49261a24-103c-4880-8e58-d1d98f301ba7",
      "name": "Jane's reservation",
      "device_id": "d87eea5d-71c6-4633-a966-396c5ac51177",
      "code": "5974",
      "common_code_key": "auto_set_by_create_multiple_72f81ee3-997f-4fdc-81d0-289dabc28ae7",
      "starts_at": "2024-12-15T15:00:00.000Z",
      "ends_at": "2024-12-17T11:00:00.000Z",
      ...
    }
  ]
  ```
</CodeGroup>

***

## Update Linked Access Codes

The following example changes both the starting and ending times for a group of linked access codes:

**Request:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  // Update the starting and ending times
  // for all these linked access codes,
  // using the common_code_key to identify
  // the group of access codes to update.
  await seam.accessCodes.updateMultiple({
    common_code_key: commonCodeKey,
    starts_at: '2024-11-15T12:00:00Z',
    ends_at: '2024-11-17T15:00:00Z',
  })
  ```

  ```sh cURL theme={null}
  # Update the starting and ending times
  # for all these linked access codes,
  # using the common_code_key to identify
  # the group of access codes to update.
  curl -X 'POST' \
    'https://connect.getseam.com/access_codes/update_multiple' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d "{
      \"common_code_key\": \"${common_code_key}\",
      \"starts_at\": \"2024-11-15T12:00:00Z\",
      \"ends_at\": \"2024-11-17T15:00:00Z\"
  }"
  ```

  ```python Python theme={null}
  # Update the starting and ending times
  # for all these linked access codes,
  # using the common_code_key to identify
  # the group of access codes to update.
  seam.access_codes.update_multiple(
    common_code_key = common_code_key,
    starts_at = "2024-11-15T12:00:00Z",
    ends_at = "2024-11-17T15:00:00Z"
  )
  ```

  ```ruby Ruby theme={null}
  # Update the starting and ending times
  # for all these linked access codes,
  # using the common_code_key to identify
  # the group of access codes to update.
  client.access_codes.update_multiple(
    common_code_key: common_code_key,
    starts_at: "2024-11-15T12:00:00Z",
    ends_at: "2024-11-17T15:00:00Z"
  )
  ```

  ```php PHP theme={null}
  // Update the starting and ending times
  // for all these linked access codes,
  // using the common_code_key to identify
  // the group of access codes to update.
  $seam->access_codes->update_multiple(
    common_code_key: $common_code_key,
    starts_at: "2024-11-15T12:00:00Z",
    ends_at: "2024-11-17T15:00:00Z"
  );
  ```

  ```csharp C# theme={null}
  // Update the starting and ending times
  // for all these linked access codes,
  // using the common_code_key to identify
  // the group of access codes to update.
  seam.AccessCodes.UpdateMultiple(
    commonCodeKey: commonCodeKey,
    startsAt: "2024-11-15T12:00:00Z",
    endsAt: "2024-11-17T15:00:00Z"
  );
  ```
</CodeGroup>

**Response:**

<CodeGroup>
  ```json JavaScript theme={null}
  void
  ```

  ```json cURL theme={null}
  {
    "ok": true
  }
  ```

  ```json Python theme={null}
  None
  ```

  ```json Ruby theme={null}
  void
  ```

  ```json PHP theme={null}
  void
  ```

  ```json C# theme={null}
  void
  ```
</CodeGroup>


# Deleting Access Codes
Source: https://docs.seam.co/low-level-apis/smart-locks/access-codes/deleting-access-codes

Learn how to delete your access codes, and ensure that the code is successfully removed from the device.

## 1. Delete the access code using the API

To delete an access code, specify the desired `access_code_id` in the [Delete Access Code](/api/access_codes/delete) request.

**Code:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  await seam.accessCodes.delete({
    access_code_id: '11111111-1111-1111-1111-555555555555',
  })
  ```

  ```bash cURL theme={null}
  curl -X 'POST' \
    'https://connect.getseam.com/access_codes/delete' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d '{
    "access_code_id": "11111111-1111-1111-1111-555555555555"
  }'
  ```

  ```python Python theme={null}
  seam.access_codes.delete(
    access_code_id="11111111-1111-1111-1111-555555555555"
  )
  ```

  ```ruby Ruby theme={null}
  client.access_codes.delete(
    access_code_id: "11111111-1111-1111-1111-555555555555"
  )
  ```

  ```php PHP theme={null}
  $seam->access_codes->delete(
    access_code_id: "11111111-1111-1111-1111-555555555555"
  );
  ```

  ```csharp C# theme={null}
  seam.AccessCodes.Delete(
    accessCodeId: "11111111-1111-1111-1111-555555555555"
  );
  ```
</CodeGroup>

**Output:**

<CodeGroup>
  ```json JavaScript theme={null}
  void
  ```

  ```json cURL theme={null}
  {
    "ok": true
  }
  ```

  ```json Python theme={null}
  None
  ```

  ```json Ruby theme={null}
  void
  ```

  ```json PHP theme={null}
  void
  ```

  ```json C# theme={null}
  void
  ```
</CodeGroup>

***

## 2. Verify that the access code has been removed

Poll for or configure a [webhook](../../../developer-tools/webhooks) to listen for an `access_code.deleted` or `access_code.removed_from_device` event containing the `access_code_id` of the access code that you've deleted. Note that if you delete an access code that was never programmed onto a device, Seam does not emit an `access_code.removed_from_device` event for this access code.

If you receive `access_code.failed_to_remove_from_device` or `access_code.delay_in_removing_from_device` events, see [Troubleshooting Access Code Issues](/low-level-apis/smart-locks/access-codes/troubleshooting-access-code-issues).


# Creating and Managing Smart Lock Access Codes
Source: https://docs.seam.co/low-level-apis/smart-locks/access-codes/index

Access codes are codes for keypad devices. These are used when you want to provide access to a lock using a PIN code.

<Warning>
  This is a low-level API. For granting a person access, use [Access
  Grants](/use-cases/granting-access/index)—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](mailto:support@seam.co)).
</Warning>

<img alt="" />

## What Is an Access Code?

An access code is a code used for a keypad or pinpad device. Unlike physical keys, which can easily be lost or duplicated, PIN codes can be customized, tracked, and altered on the fly. Using the Seam [Access Code API](/api/access_codes/object), you can easily generate access codes on the hundreds of door lock models with which we integrate.

Seam supports programming two types of access codes: [ongoing](#ongoing-access-codes) and [time-bound](#time-bound-access-codes). To differentiate between the two, refer to the `type` property of the access code. Ongoing codes display as `ongoing`, whereas time-bound codes are labeled `time_bound`.

In addition, for certain devices, Seam also supports [offline access codes](#offline-access-codes).

### **Ongoing Access Codes**

Ongoing access code are ideal for residents or long-term users. Ongoing codes start right away and remain active on a device until they are removed.

<picture>
  <source />

  <img alt="Timeline of an ongoing access code. The code remains active until you ask Seam to remove it." />
</picture>

### **Time-Bound Access Codes**

Time-bound 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 this period.

<picture>
  <source />

  <img alt="Timeline of a time-bound access code. The code remains active until the ends_at timestamp that you provide to Seam." />
</picture>

### Offline Access Codes

Offline access (PIN) codes are designed for door locks that might not always maintain an internet connection. Currently, Seam supports offline access codes for [igloohome locks](/device-and-system-integration-guides/igloohome-locks), [dormakaba Oracode locks](/device-and-system-integration-guides/dormakaba-oracode-locks), and [Lockly locks](/device-and-system-integration-guides/lockly-locks). For this type of access code, the device manufacturer uses encryption keys (tokens) to create server-based registries of algorithmically-generated offline PIN codes. Because the tokens remain synchronized with the managed devices, the locks do not require an active internet connection—and you do not need to be near the locks—to create an offline access code. Then, owners or managers can share these offline codes with users through a variety of mechanisms, such as messaging applications. That is, lock users do not need to install a smartphone application to receive an offline access code.

<Info>
  You cannot modify a created offline access code. In addition, you cannot
  revoke a created offline access code before the configured expiration date for
  the code. To invalidate an offline access code before the expiration date, you
  must either perform a factory reset on the device or re-pair your smartphone
  with the device.
</Info>

Seam supports two types of offline access codes: [time-bound](#time-bound-offline-access-codes) and [one-time-use](#one-time-use-offline-access-codes). Note that this support varies based on the device manufacturer. Before creating an offline access code, it is imperative to understand any manufacturer- or device-specific constraints, such as the maximum number of access codes, any time slot or activation requirements, and so on. For details, see the corresponding device guide.

* [igloohome Locks device guide](/device-and-system-integration-guides/igloohome-locks)
* [dormakaba Oracode Locks device guide](/device-and-system-integration-guides/dormakaba-oracode-locks)
* [Lockly Locks device guide](/device-and-system-integration-guides/lockly-locks)

#### Time-Bound Offline Access Codes

For [igloohome locks](/device-and-system-integration-guides/igloohome-locks) and [dormakaba Oracode locks](/device-and-system-integration-guides/dormakaba-oracode-locks), you can create time-bound offline access codes with validity durations at either the hour level or the day level. For [Lockly locks](/device-and-system-integration-guides/lockly-locks), you can create generic time-bound offline access codes that do not differentiate between hourly-bound and daily-bound codes.

Hourly-bound offline access codes are intended for shorter durations, while daily-bound offline codes are intended for longer durations. Device manufacturers set the bounds for these short- and long-term access codes, and some device manufacturers enforce a maximum duration for hourly-bound offline access codes. See the corresponding device guide for more information.

To [create a time-bound offline access code](/low-level-apis/smart-locks/access-codes/offline-access-codes#creating-time-bound-offline-access-codes), specify the desired `starts_at` and `ends_at` date and time. To [create a daily-bound offline access code](/low-level-apis/smart-locks/access-codes/offline-access-codes#1-create-a-time-bound-offline-access-code), you must specify the same time in the `starts_at` and `ends_at` properties.

#### One-Time-Use Offline Access Codes

For [igloohome locks](/device-and-system-integration-guides/igloohome-locks) and [Lockly locks](/device-and-system-integration-guides/lockly-locks), you can create [one-time-use offline access codes](/low-level-apis/smart-locks/access-codes/offline-access-codes#creating-one-time-use-offline-access-codes). igloohome one-time-use offline access codes are valid for 24 hours from the `starts_at` timestamp that you configure. Lockly offline access codes are valid for the time period that you specify using the `starts_at` and `ends_at` timestamps. These codes expire after a single use.

***

## How Seam Programs Codes onto the Lock

Seam ensures access reliability by initiating the programming of access codes onto the lock ahead of its `starts_at` time. This approach minimizes the risks of delays or disruptions during the programming process.

### **Native Scheduling**

For locks that support setting codes with a schedule, Seam will preload access codes onto the device a full **72 hours** before the `starts_at` timestamp of a time-bound code. When the `starts_at` time arrives, the code automatically activates and will remain active until its `ends_at` time. We enable this "native scheduling" functionality by default for all providers that support it. See [Native Scheduling - Supported Providers](#native-scheduling-supported-providers) for a list of supported providers. You can choose to override this default behavior and have Seam perform "just-in-time scheduling" by setting `prefer_native_scheduling` to `false` when creating a code.

<img
  alt="72 hours before the starts_at timestamp, Seam inserts the
code into the device's internal memory. When the starts_at' '
time arrives, the device automatically activates the code. It is then
automatically deactivated at the ends_at timestamp."
/>

#### Native Scheduling Supported Providers

| ✅ Supported | ✖️ Not Supported  |
| ----------- | ----------------- |
| 2N          | Dormakaba Oracode |
| August      | Lockly            |
| Igloohome   | SmartThings       |
| Kwikset     |                   |
| Nuki        |                   |
| Salto       |                   |
| Schlage     |                   |
| Tedee       |                   |
| TTLock      |                   |
| Yale        |                   |
| Wyze        |                   |

### **Just-in-time Scheduling**

For those locks that lack native scheduling functionality, Seam will use its own scheduling infrastructure to program the code 60 minutes before the `starts_at` time, and remove it at the `ends_at` time.

<img
  alt="When the starts_at time arrives, Seam adds the code to the
device and activates it. It is then automatically deactivated at the' '
ends_at timestamp."
/>

***

## Access Code Names <a href="#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 appears 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 names down into components, such as `first_name` and `last_name`.

To provide a consistent experience, Seam identifies an access 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 to meet provider constraints.

To help your 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 a name down into components).

***

## Linking Unlock Events and Access Codes

When a user unlocks a door using an access code, Seam issues a [`lock.unlocked` event](/api/locks/events#lock-unlocked). Some device manufacturers include the ID of the access code in lock-related events. This information is useful for troubleshooting and logging. Further, if you name access codes in a way that identifies the associated users, you can use these `lock.unlocked` events to identify the users who unlocked the doors.

Currently, the following device manufacturers send the `access_code_id` in the `lock.unlocked` event:

* August
* Kwikset
* Salto KS
* Schlage
* Tedee
* TTLock
* Yale

***

## External Modification <a href="#external-modification" />

Seam attempts to keep an access code on a 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 are set to match the declared state of the access code on Seam. Any updates to the access code timings on Seam are reflected on the device. In general, if the access code is modified externally to Seam (through the lock provider's app, for example), Seam attempts 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 attempts 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 sends an `access_code.modified_external_to_seam` event and adds a `code_modified_external_to_seam` error on the access code.

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

***

## Advanced Feature: Backup Access Codes

Occasionally, Seam may encounter issues when programming codes onto locks. Such hiccups can arise from device connectivity issues, manual interventions from the lock or its accompanying app, or service disruptions from the lock providers. Given these issues, we strongly advise preprogramming a set of backup codes onto the door lock. Should you detect a failure in access code programming, these backup codes can be promptly shared.

Seam offers a Backup Access Code service. When activated, this service automatically maintain a pool of pre-programmed access codes on a device. These codes are programmed in addition to the regular access codes on Seam, acting as a safety net in case of any issues with the primary codes. Please read about [how to enable and request a back up code here](/low-level-apis/smart-locks/access-codes/backup-access-codes).

<CardGroup>
  <Card title="Backup Access Code PoolUse our backup code pool service to automatically maintain a set of back up codes on your device." href="/low-level-apis/smart-locks/access-codes/backup-access-codes" />
</CardGroup>


# Lifecycle of Access Codes
Source: https://docs.seam.co/low-level-apis/smart-locks/access-codes/lifecycle-of-access-codes

Learn how access codes transition between states, and the corresponding events that are emitted.

Programming access codes involves [asynchronous](https://en.wikipedia.org/wiki/Asynchronous_system) processes, which can be complex to manage. Such asynchronous flows depend on interactions with smart devices and third-party applications outside your main application. Our access code API streamlines this process by tracking the status of the access code using a state machine.

The access code flow begins when you use Seam to make a request to create an access code. The access code creation process starts with the code in the `unset` state. Then, the access code proceeds through the rest of the states.

<img alt="Lifecycle of an access code" />

## 1. `unset` - Awaiting programming

This is the initial state of an access code. At this stage, the code is created in the system but has not yet been sent to or recognized by the smart device. It's essentially in a queue, waiting for its turn to be programmed.

For [natively-scheduled](/low-level-apis/smart-locks/access-codes#native-scheduling) codes, Seam will preload the access code onto the device **72 hours ahead** of the `starts_at` time. Seam will also emit an `access_code.scheduled_on_device` event, which indicates a natively-scheduled code has been programmed on the device, and is awaiting its designated activation time. You'll observe that the access code remains in an `unset` state until the `starts_at` time, at which point it will activate and transition to the `set` status.

## 2. `setting` - Programming in progress

For Just-in-time codes, once the code starts being programmed onto the smart device, it transitions to the `setting` state. During this phase, Seam is actively trying to communicate with the smart device to program the code.

For natively-scheduled codes, if there's an issue programming the natively-scheduled code by its `starts_at` time, then the code's status will display as `setting`.

## 3. `set` - Active for use

Once an access code is successfully programmed onto a smart device, specific events are emitted to indicate its status. For standard access codes, the `access_code.set_on_device` event is triggered, signifying successful programming. Regardless of the type, the code is securely stored in the device's memory. However, its immediate usability may be contingent on properties like `starts_at`. For [natively scheduled](/low-level-apis/smart-locks/access-codes#native-scheduling) codes, you can expect the `access_code.set_on_device` event to be emitted when the `starts_at` activation time is reached.

## Modifying a `set` code

A code stays in the `set` state while you update its PIN, name, or time frame (see [Modifying Access Codes](/low-level-apis/smart-locks/access-codes/modifying-access-codes)). Seam reports a modification through two kinds of events:

* **`access_code.mutations_requested`** fires at request time, as soon as Seam accepts the change—before it is confirmed on the device. Its `requested_mutations` array describes what was asked for.
* When the change is confirmed on the device, Seam emits the event specific to what changed, each carrying `from` and `to` values:
  * **`access_code.code_changed`** — the PIN code changed.
  * **`access_code.name_changed`** — the name changed.
  * **`access_code.time_frame_changed`** — the [time frame](/low-level-apis/smart-locks/access-codes/creating-access-codes/understanding-time-frame-options) (`starts_at` / `ends_at`) changed.

See the [access code events reference](/api/access_codes/events) for full payloads.

## 4. `removing` - Being removed from device

When an access code is no longer required or its `ends_at` time has been reached, Seam initiates the process to remove the code from the device. The access code then transitions to the "removing" state. During this period, the system actively communicates with the smart device, working to erase the access code from its memory.

## 5. Access code unprogrammed and deleted from Seam

When an access code is removed from a device, it's not just deleted from the device's memory. Correspondingly, the access code object is also deleted from Seam's database. As a result, if you try to retrieve that specific access code through the 'get access code' endpoint afterwards, you will encounter a 404 error, indicating that the code no longer exists.

<Info>
  Seam is modifying the behavior of access codes so they won't return a 404
  error unless explicitly deleted by the API user. Currently, access codes yield
  a 404 error when removed from a device, such as when a time-bound access code
  expires.
</Info>

***

## `unknown` - Seam lost connection to account

Beyond the states previously detailed, an "unknown" state exists. This state suggests that the account has been disconnected, preventing Seam from interfacing with the third-party API to verify the access code.


# Migrating Existing Unmanaged Access Codes
Source: https://docs.seam.co/low-level-apis/smart-locks/access-codes/migrating-existing-access-codes

Learn how to migrate existing lock access codes into Seam

## Overview

Prior to using Seam to manage your devices, you may have used another lock management system to manage the access codes on your devices. Where possible, we will help you keep any existing access codes on devices, and transition those codes to ones managed by your Seam workspace.

If migrating existing codes into your Seam workspace is not possible, you can still get a list of these existing codes, and replace them with new access codes managed by your Seam workspace.

## Unmanaged Access Codes

Seam differentiates between managed access codes and unmanaged access codes. When you create an access code on a device in Seam, it is created as a managed code. Codes that exist on a device that were not created on Seam are considered unmanaged codes. We strictly limit the operations that can be performed on unmanaged codes to:

* Viewing a list of the unmanaged codes on a device
* Converting an unmanaged code into a managed code
* Deleting an unmanaged code

<Info>
  Strictly speaking, unmanaged codes are any codes on a device that were not
  created by the current workspace. For example, if you are within *Workspace 1*
  and created codes *Code 1* and *Code 2*, those two codes would be considered
  unmanaged if you were looking at the same device in *Workspace 2*. Therefore,
  unmanaged codes include both codes not managed by Seam at all, and codes that
  might be managed by a different workspace within Seam.
</Info>

## Viewing Unmanaged Codes on a Device

You can retrieve a list of all unmanaged access codes for a particular device using the [List Unmanaged Access Codes](/api/access_codes/unmanaged/list) request, passing in `device_id` as a query parameter. For example:

**Request:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  await seam.accessCodes.unmanaged.list({
    device_id: '11111111-1111-1111-1111-444444444444',
  })
  ```

  ```bash cURL theme={null}
  # Use GET or POST.
  curl -X 'GET' \
    'https://connect.getseam.com/access_codes/unmanaged/list' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d '{
    "device_id": "11111111-1111-1111-1111-444444444444"
  }'
  ```

  ```python Python theme={null}
  seam.access_codes.unmanaged.list(
    device_id="11111111-1111-1111-1111-444444444444"
  )
  ```

  ```ruby Ruby theme={null}
  client.unmanaged_access_codes.list(
    device_id: "11111111-1111-1111-1111-444444444444"
  )
  ```

  ```csharp C# theme={null}
  seam.UnmanagedAccessCodes.List(
    deviceId: "11111111-1111-1111-1111-444444444444"
  );
  ```
</CodeGroup>

**Response:**

<CodeGroup>
  ```json JavaScript theme={null}
  [
    {
      access_code_id: '11111111-1111-1111-1111-999999999999',
      device_id: '11111111-1111-1111-1111-444444444444',
      is_managed: false,
      ...
    },
    ...
  ]
  ```

  ```json cURL theme={null}
  {
    "access_codes": [
      {
        "access_code_id": "11111111-1111-1111-1111-999999999999",
        "device_id": "11111111-1111-1111-1111-444444444444",
        "is_managed": false,
        ...
      },
      ...
    ],
    "ok": true
  }
  ```

  ```json Python theme={null}
  [
    UnmanagedAccessCode(
      access_code_id='11111111-1111-1111-1111-999999999999',
      device_id='11111111-1111-1111-1111-444444444444',
      is_managed=False,
      ...
    ),
    ...
  ]
  ```

  ```json Ruby theme={null}
  [
    <Seam::AccessCode:0x00438
      access_code_id="11111111-1111-1111-1111-999999999999"
      device_id="11111111-1111-1111-1111-444444444444"
      is_managed=false
      ...
    >
    ...
  ]
  ```

  ```json C# theme={null}
  {
    "access_code_id": "11111111-1111-1111-1111-999999999999",
    "device_id": "11111111-1111-1111-1111-444444444444",
    "is_managed": false,
    ...
  }
  ...
  ```
</CodeGroup>

## Converting Unmanaged Codes into Managed Codes

You can convert unmanaged access codes into managed ones using the [Convert an Unmanaged Access Code](/api/access_codes/unmanaged/convert_to_managed) request, passing in `access_code_id` as a query parameter. For example:

**Request:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  await seam.accessCodes.unmanaged.convertToManaged({
    access_code_id: '11111111-1111-1111-1111-999999999999',
  })
  ```

  ```bash cURL theme={null}
  curl -X 'POST' \
    'https://connect.getseam.com/access_codes/unmanaged/convert_to_managed' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d '{
    "access_code_id": "11111111-1111-1111-1111-999999999999"
  }
  ```

  ```python Python theme={null}
  seam.access_codes.unmanaged.convert_to_managed(
    access_code_id = "11111111-1111-1111-1111-999999999999"
  )
  ```

  ```ruby Ruby theme={null}
  client.unmanaged_access_codes.convert_to_managed(
    access_code_id: "11111111-1111-1111-1111-999999999999"
  )
  ```

  ```csharp C# theme={null}
  seam.UnmanagedAccessCodes.ConvertToManaged(
    accessCodeId: "11111111-1111-1111-1111-999999999999"
  );
  ```
</CodeGroup>

**Response:**

<CodeGroup>
  ```json JavaScript theme={null}
  {
    "actionAttempt": {
      "status": "success",
      "action_attempt_id": "721b51b7-6ab9-41cf-b09d-a5e97d355208",
      "action_type": "CONVERT_ACCESS_CODE_TO_MANAGED",
      "result": {},
      "error": null
    }
  }
  ```

  ```json cURL theme={null}
  {
    "action_attempt": {
      "status": "pending",
      "action_type": "CONVERT_ACCESS_CODE_TO_MANAGED",
      "action_attempt_id": "721b51b7-6ab9-41cf-b09d-a5e97d355208",
      "result": null,
      "error": null
    },
    "ok": true
  }
  ```

  ```json Python theme={null}
  ActionAttempt(action_attempt_id='721b51b7-6ab9-41cf-b09d-a5e97d355208',
                action_type='CONVERT_ACCESS_CODE_TO_MANAGED',
                status='success',
                result={},
                error=None)
  ```

  ```json Ruby theme={null}
  <Seam::ActionAttempt:0x00438
    status="success"
    action_type="CONVERT_ACCESS_CODE_TO_MANAGED"
    action_attempt_id="721b51b7-6ab9-41cf-b09d-a5e97d355208"
    result=nil>
  ```

  ```json C# theme={null}
  Status: success
  ActionType: CONVERT_ACCESS_CODE_TO_MANAGED
  ActionAttemptId: 721b51b7-6ab9-41cf-b09d-a5e97d355208
  Result:
  Error:
  ```
</CodeGroup>

The request returns immediately, but the conversion is an asynchronous process that completes in the background. You can listen to the `access_code.unmanaged.converted_to_managed` and `access_code.unmanaged.failed_to_convert_to_managed` to be notified when conversion succeeds or fails.

Once an unmanaged code is successfully converted to a managed code, all of the normal managed access code operations and behavior are available.

## Unsupported Conversion

Some third-party device providers strictly limit the information available about existing access codes on a device. Thus, for devices connected using these providers, we cannot convert unmanaged codes to managed ones. The following providers currently do not support conversion:

* [igloohome](/device-and-system-integration-guides/igloohome-locks)
* [Kwikset](/device-and-system-integration-guides/kwikset-locks)
* [SmartThings](/device-and-system-integration-guides/smartthings-hubs-+-devices/get-started-with-smartthings-hubs-+-smart-locks)

For SmartThings devices, you can still see a list of all unmanaged codes on the devices using the `GET /access_codes/unmanaged/list` endpoint, but you cannot see the actual PIN code for the access codes (the `code` property is not present).

## Deleting Unmanaged Codes

After you have converted unmanaged codes to managed codes, or replaced them with new ones, you can allow users to delete any remaining unmanaged codes on their device. You can do this by using the [Delete an Unmanaged Access Code](/api/access_codes/unmanaged/delete) request and passing in passing in `access_code_id` as a query parameter. For example:

**Request:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  await seam.accessCodes.unmanaged.delete({
    access_code_id: '11111111-1111-1111-1111-999999999999',
  })
  ```

  ```bash cURL theme={null}
  curl -X 'POST' \
    'https://connect.getseam.com/access_codes/unmanaged/delete' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d '{
    "access_code_id": "11111111-1111-1111-1111-999999999999"
  }'
  ```

  ```python Python theme={null}
  seam.access_codes.unmanaged.delete(
    access_code_id = "11111111-1111-1111-1111-999999999999"
  )
  ```

  ```ruby Ruby theme={null}
  client.unmanaged_access_codes.delete(
    access_code_id: "11111111-1111-1111-1111-999999999999"
  )
  ```

  ```csharp C# theme={null}
  seam.UnmanagedAccessCodes.Delete(
    accessCodeId: "11111111-1111-1111-1111-999999999999"
  );
  ```
</CodeGroup>

**Response:**

<CodeGroup>
  ```json JavaScript theme={null}
  {
    "actionAttempt": {
      "status": "success",
      "action_attempt_id": "364e747f-9631-4eb1-bc9e-24cd1f11cf3b",
      "action_type": "DELETE_UNMANAGED_ACCESS_CODE",
      "result": {},
      "error": null
    }
  }
  ```

  ```json cURL theme={null}
  {
    "action_attempt": {
      "status": "pending",
      "action_type": "DELETE_UNMANAGED_ACCESS_CODE",
      "action_attempt_id": "364e747f-9631-4eb1-bc9e-24cd1f11cf3b",
      "result": null,
      "error": null
    },
    "ok": true
  }
  ```

  ```json Python theme={null}
  ActionAttempt(action_attempt_id='364e747f-9631-4eb1-bc9e-24cd1f11cf3b',
                action_type='DELETE_UNMANAGED_ACCESS_CODE',
                status='success',
                result={},
                error=None)
  ```

  ```json Ruby theme={null}
  <Seam::ActionAttempt:0x00438
    status="success"
    action_type="DELETE_UNMANAGED_ACCESS_CODE"
    action_attempt_id="364e747f-9631-4eb1-bc9e-24cd1f11cf3b"
    result={}>
  ```

  ```json C# theme={null}
  Status: success
  ActionType: DELETE_UNMANAGED_ACCESS_CODE
  ActionAttemptId: 364e747f-9631-4eb1-bc9e-24cd1f11cf3b
  Result:
  Error:
  ```
</CodeGroup>

The request returns an action attempt, similar to the managed code deletion endpoint. See [Delete an access code](/api/access_codes/delete) for more details.


# Modifying Access Codes
Source: https://docs.seam.co/low-level-apis/smart-locks/access-codes/modifying-access-codes

Learn how to update your access codes, and ensure that the changes are successfully set on the device.

## 1. Update the access code using the API

You can update any active or upcoming access codes using the [Update Access Code](/api/access_codes/update) request.

When modifying an access code, adjust the properties of the access code, such as the `code`, `name`, `starts_at`, and `ends_at` to the new desired values.

**Code:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  await seam.accessCodes.update({
    access_code_id: '11111111-1111-1111-1111-555555555555',
    name: 'my updated code name',
    starts_at: '2025-02-01T16:00:00Z',
    ends_at: '2025-02-22T12:00:00Z',
    code: '5432',
  })
  ```

  ```bash cURL theme={null}
  curl -X 'POST' \
    'https://connect.getseam.com/access_codes/update' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d '{
    "access_code_id": "11111111-1111-1111-1111-555555555555",
    "name": "my updated code name",
    "code": "5432",
    "starts_at": "2025-02-01T16:00:00Z",
    "ends_at": "2025-02-22T12:00:00Z"
  }'
  ```

  ```python Python theme={null}
  seam.access_codes.update(
    access_code = "11111111-1111-1111-1111-555555555555",
    name = "my updated code name",
    code = "5432",
    starts_at = "2025-02-01T16:00:00Z",
    ends_at = "2025-02-22T12:00:00Z"
  )
  ```

  ```ruby Ruby theme={null}
  client.access_codes.update(
    access_code_id: "11111111-1111-1111-1111-555555555555",
    name: "my updated code name",
    starts_at: "2025-02-01T16:00:00Z",
    ends_at: "2025-02-22T12:00:00Z",
    code: "5432"
  )
  ```

  ```php PHP theme={null}
  $seam->access_codes->update(
    access_code_id: "11111111-1111-1111-1111-555555555555",
    name: "my updated code name",
    starts_at: "2025-02-01T16:00:00Z",
    ends_at: "2025-02-22T12:00:00Z",
    code: "5432"
  );
  ```

  ```csharp C# theme={null}
  seam.AccessCodes.Update(
    accessCodeId: "11111111-1111-1111-1111-555555555555",
    name: "my updated code name",
    startsAt: "2025-02-01T16:00:00Z",
    endsAt: "2025-02-22T12:00:00Z",
    code: "5432"
  );
  ```
</CodeGroup>

**Output:**

<CodeGroup>
  ```json JavaScript theme={null}
  void
  ```

  ```json cURL theme={null}
  {
    "ok": true
  }
  ```

  ```json Python theme={null}
  None
  ```

  ```json Ruby theme={null}
  nil
  ```

  ```json PHP theme={null}
  void
  ```

  ```json C# theme={null}
  void
  ```
</CodeGroup>

## 2. Verify that the access code has been updated

When you modify an existing code, Seam emits update-specific events in addition to the status signals below. `access_code.mutations_requested` fires at request time, as soon as Seam accepts the change (before it is confirmed on the device). Once the change is confirmed on the device, Seam emits the event for what changed—`access_code.code_changed`, `access_code.name_changed`, or `access_code.time_frame_changed`—each carrying `from` and `to` values, so you can confirm precisely which attribute updated. See the [access code events reference](/api/access_codes/events) for full payloads.

### For a permanent access code

There are two methods to verify that a permanent access code has been set on the device:

**Polling Method**

Utilize the `access_code_id` returned in the response from the create endpoint to invoke the [Get Access Code](/api/access_codes/get) endpoint. 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 [our guide on "Troubleshooting Access Code Issues"](/low-level-apis/smart-locks/access-codes/troubleshooting-access-code-issues) for further guidance.

**Webhook Events Method**

Monitor the incoming events on your webhook. Be on the lookout for the `access_code.set_on_device` event, which indicates the successful setting of the access code on the device.

However, if you receive `access_code.failed_to_set_on_device` or `access_code.delay_in_setting_on_device` events, it's crucial to refer to [the "Troubleshooting access code issues" guide](/low-level-apis/smart-locks/access-codes/troubleshooting-access-code-issues) for assistance.

### For a time-bound access code

There are two methods to verify that a time-bound access code has been set on the device:

**Polling Method**

Use the `access_code_id` provided in the response from the create endpoint to call the [Get Access Code](/api/access_codes/get) endpoint. 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 [our "Troubleshooting Access Code Issues" guide](/low-level-apis/smart-locks/access-codes/troubleshooting-access-code-issues) for assistance.

**Webhook Events Method**

Monitor the incoming events on your webhook. Be on the lookout for the `access_code.set_on_device` event, which indicates the successful setting of the access code on the device.

However, if you receive `access_code.failed_to_set_on_device` or `access_code.delay_in_setting_on_device` events, it's crucial to refer to [the "Troubleshooting access code issues" guide](/low-level-apis/smart-locks/access-codes/troubleshooting-access-code-issues) for assistance.

***

## Special Case #1: Changing an ongoing access code to time-bound access

To convert a permanent access code to time-bound access, you must set the `starts_at` and `ends_at` properties to the timeframe that you want for the access code.

<Tabs>
  <Tab title="JavaScript">
    **1. Confirm that the access code starts as an ongoing code.**

    **Code:**

    ```javascript theme={null}
    await seam.accessCodes.get({
      access_code_id: '11111111-1111-1111-1111-555555555555',
    })
    ```

    **Output:**

    ```json theme={null}
    {
      access_code_id: '11111111-1111-1111-1111-555555555555',
      type: 'ongoing',
      ...
    }
    ```

    **2. Update the code to set `starts_at` and `ends_at` timestamps.**

    **Code:**

    ```javascript theme={null}
    await seam.accessCodes.update({
      access_code_id: '11111111-1111-1111-1111-555555555555',
      starts_at: '2025-02-01T16:00:00Z',
      ends_at: '2025-02-22T12:00:00Z',
    })
    ```

    **Output:**

    ```json theme={null}
    void
    ```

    **3. Confirm that the `type` has changed to `time_bound`.**

    **Code:**

    ```javascript theme={null}
    await seam.accessCodes.get({
      access_code_id: '11111111-1111-1111-1111-555555555555',
    })
    ```

    **Output:**

    ```json theme={null}
    {
      access_code_id: '11111111-1111-1111-1111-555555555555',
      type: 'time_bound',
      starts_at: '2025-02-01T16:00:00.000Z',
      ends_at: '2025-02-22T12:00:00.000Z',
      ...
    }
    ```
  </Tab>

  <Tab title="cURL">
    **1. Confirm that the access code starts as an ongoing code.**

    **Request:**

    ```bash theme={null}
    # Use GET or POST.
    curl -X 'GET' \
      'https://connect.getseam.com/access_codes/get' \
      -H 'accept: application/json' \
      -H "Authorization: Bearer ${SEAM_API_KEY}" \
      -H 'Content-Type: application/json' \
      -d '{
      "access_code_id": "11111111-1111-1111-1111-555555555555"
    }'
    ```

    **Response:**

    ```json theme={null}
    {
      "access_code": {
        "access_code_id": "11111111-1111-1111-1111-555555555555",
        "type": "ongoing",
        ...
      },
      "ok": true
    }
    ```

    **2. Update the code to set `starts_at` and `ends_at` timestamps.**

    **Request:**

    ```bash theme={null}
    curl -X 'POST' \
      'https://connect.getseam.com/access_codes/update' \
      -H 'accept: application/json' \
      -H "Authorization: Bearer ${SEAM_API_KEY}" \
      -H 'Content-Type: application/json' \
      -d '{
      "access_code_id": "11111111-1111-1111-1111-555555555555",
      "starts_at": "2025-01-01T16:00:00Z",
      "ends_at": "2025-01-22T12:00:00Z"
    }'
    ```

    **Response:**

    ```json theme={null}
    {
      "ok": true
    }
    ```

    **3. Confirm that the `type` has changed to `time_bound`.**

    **Request:**

    ```bash theme={null}
    # Use GET or POST.
    curl -X 'GET' \
      'https://connect.getseam.com/access_codes/get' \
      -H 'accept: application/json' \
      -H "Authorization: Bearer ${SEAM_API_KEY}" \
      -H 'Content-Type: application/json' \
      -d '{
      "access_code_id": "11111111-1111-1111-1111-555555555555"
    }'
    ```

    **Response:**

    ```json theme={null}
    {
      "access_code": {
        "access_code_id": "11111111-1111-1111-1111-555555555555",
        "type": "time_bound",
        "starts_at": "2025-01-01T16:00:00.000Z",
        "ends_at": "2025-01-22T12:00:00.000Z",
        ...
      },
      "ok": true
    }
    ```
  </Tab>

  <Tab title="Python">
    **1. Confirm that the access code starts as an ongoing code.**

    **Code:**

    ```python theme={null}
    access_code = seam.access_codes.get(
      access_code_id = "11111111-1111-1111-1111-555555555555"
    )
    ```

    **Output:**

    ```
    AccessCode(
      access_code_id='11111111-1111-1111-1111-555555555555',
      type='ongoing',
      ...
    )
    ```

    **2. Update the code to set `starts_at` and `ends_at` timestamps.**

    **Code:**

    ```python theme={null}
    seam.access_codes.update(
      access_code = "11111111-1111-1111-1111-555555555555",
      starts_at = "2025-01-01T16:00:00Z",
      ends_at = "2025-01-22T12:00:00Z"
    )
    ```

    **Output:**

    ```
    None
    ```

    **3. Confirm that the `type` has changed to `time_bound`.**

    **Code:**

    ```python theme={null}
    seam.access_codes.get(
      access_code_id = "11111111-1111-1111-1111-555555555555"
    )
    ```

    **Output:**

    ```
    AccessCode(
      access_code_id='11111111-1111-1111-1111-555555555555',
      type='time_bound',
      starts_at='2025-01-01T16:00:00.000Z',
      ends_at='2025-01-22T12:00:00.000Z',
      ...
    )
    ```
  </Tab>

  <Tab title="Ruby">
    **1. Confirm that the access code starts as an ongoing code.**

    **Code:**

    ```ruby theme={null}
    client.access_codes.get(
      access_code_id: "11111111-1111-1111-1111-555555555555"
    )
    ```

    **Output:**

    ```
    <Seam::AccessCode:0x00438
      access_code_id="11111111-1111-1111-1111-555555555555"
      type="ongoing"
      ...
    >
    ```

    **2. Update the code to set `starts_at` and `ends_at` timestamps.**

    **Code:**

    ```ruby theme={null}
    client.access_codes.update(
      access_code_id: "11111111-1111-1111-1111-555555555555",
      starts_at: "2025-02-01T16:00:00Z",
      ends_at: "2025-02-22T12:00:00Z"
    )
    ```

    **Output:**

    ```
    nil
    ```

    **3. Confirm that the `type` has changed to `time_bound`.**

    **Code:**

    ```ruby theme={null}
    client.access_codes.get(
      access_code_id: "11111111-1111-1111-1111-555555555555"
    )
    ```

    **Output:**

    ```
    <Seam::AccessCode:0x00438
      access_code_id="11111111-1111-1111-1111-555555555555"
      type="time_bound"
      starts_at=2025-02-01 16:00:00 UTC
      ends_at=2025-02-22 12:00:00 UTC
      ...
    >
    ```
  </Tab>

  <Tab title="PHP">
    **1. Confirm that the access code starts as an ongoing code.**

    **Code:**

    ```php theme={null}
    $seam->access_codes->get(
      access_code_id: "11111111-1111-1111-1111-555555555555"
    );
    ```

    **Output:**

    ```json theme={null}
    {
      "access_code_id": "11111111-1111-1111-1111-555555555555",
      "type": "ongoing",
      ...
    }
    ```

    **2. Update the code to set `starts_at` and `ends_at` timestamps.**

    **Code:**

    ```php theme={null}
    $seam->access_codes->update(
      access_code_id: "11111111-1111-1111-1111-555555555555",
      starts_at: "2025-02-01T16:00:00Z",
      ends_at: "2025-02-22T12:00:00Z"
    );
    ```

    **Output:**

    ```
    void
    ```

    **3. Confirm that the `type` has changed to `time_bound`.**

    **Code:**

    ```php theme={null}
    $seam->access_codes->get(
      access_code_id: "11111111-1111-1111-1111-555555555555"
    );
    ```

    **Output:**

    ```json theme={null}
    {
      "access_code_id": "11111111-1111-1111-1111-555555555555",
      "type": "time_bound",
      "starts_at": "2025-02-01T16:00:00.000Z",
      "ends_at": "2025-02-22T12:00:00.000Z",
      ...
    }
    ```
  </Tab>

  <Tab title="C#">
    **1. Confirm that the access code starts as an ongoing code.**

    **Code:**

    ```csharp theme={null}
    seam.AccessCodes.Get(
      accessCodeId: "11111111-1111-1111-1111-555555555555"
    );
    ```

    **Output:**

    ```json theme={null}
    {
      "access_code_id": "11111111-1111-1111-1111-555555555555",
      "type": "ongoing",
      ...
    }
    ```

    **2. Update the code to set `starts_at` and `ends_at` timestamps.**

    **Code:**

    ```csharp theme={null}
    seam.AccessCodes.Update(
      accessCodeId: "11111111-1111-1111-1111-555555555555",
      startsAt: "2025-02-01T16:00:00Z",
      endsAt: "2025-02-22T12:00:00Z"
    );
    ```

    **Output:**

    ```
    void
    ```

    **3. Confirm that the `type` has changed to `time_bound`.**

    **Code:**

    ```csharp theme={null}
    seam.AccessCodes.Get(
      accessCodeId: "11111111-1111-1111-1111-555555555555"
    );
    ```

    **Output:**

    ```json theme={null}
    {
      "access_code_id": "11111111-1111-1111-1111-555555555555",
      "type": "time_bound",
      "starts_at": "2025-02-01T16:00:00.000Z",
      "ends_at": "2025-02-22T12:00:00.000Z",
      ...
    }
    ```
  </Tab>
</Tabs>

***

## Special Case #2: Changing a time-bound access code to permanent access

When converting a time-bound code to a permanent one, you'll also need to set the `type` property of the access code to `ongoing`.

<Tabs>
  <Tab title="JavaScript">
    **1. Confirm that the access code starts as a time-bound code.**

    **Code:**

    ```javascript theme={null}
    await seam.accessCodes.get({
      access_code_id: '11111111-1111-1111-1111-555555555555',
    })
    ```

    **Output:**

    ```json theme={null}
    {
      access_code_id: '11111111-1111-1111-1111-555555555555',
      type: 'time_bound',
      starts_at: '2025-02-01T16:00:00.000Z',
      ends_at: '2025-02-22T12:00:00.000Z',
      ...
    }
    ```

    **2. Update the code to set the `type` to `ongoing`.**

    **Code:**

    ```javascript theme={null}
    await seam.accessCodes.update({
      access_code_id: '11111111-1111-1111-1111-555555555555',
      type: 'ongoing',
    })
    ```

    **Output:**

    ```json theme={null}
    void
    ```

    **3. Confirm that the `type` has changed to `ongoing` and the `starts_at` and `ends_at` are `None`.**

    **Code:**

    ```javascript theme={null}
    await seam.accessCodes.get({
      access_code_id: '11111111-1111-1111-1111-555555555555',
    })
    ```

    **Output:**

    ```json theme={null}
    {
      access_code_id: '11111111-1111-1111-1111-555555555555',
      type: 'ongoing',
      ...
    }
    ```
  </Tab>

  <Tab title="cURL">
    **1. Confirm that the access code starts as a time-bound code.**

    **Request:**

    ```bash theme={null}
    # Use GET or POST.
    curl -X 'GET' \
      'https://connect.getseam.com/access_codes/get' \
      -H 'accept: application/json' \
      -H "Authorization: Bearer ${SEAM_API_KEY}" \
      -H 'Content-Type: application/json' \
      -d '{
      "access_code_id": "11111111-1111-1111-1111-555555555555"
    }'
    ```

    **Response:**

    ```json theme={null}
    {
      "access_code": {
        "access_code_id": "11111111-1111-1111-1111-555555555555",
        "type": "time_bound",
        "starts_at": "2025-01-01T16:00:00.000Z",
        "ends_at": "2025-01-22T12:00:00.000Z",
        ...
      },
      "ok": true
    }
    ```

    **2. Update the code to set the `type` to `ongoing`.**

    **Request:**

    ```bash theme={null}
    curl -X 'POST' \
      'https://connect.getseam.com/access_codes/update' \
      -H 'accept: application/json' \
      -H "Authorization: Bearer ${SEAM_API_KEY}" \
      -H 'Content-Type: application/json' \
      -d '{
      "access_code_id": "11111111-1111-1111-1111-555555555555",
      "type": "ongoing"
    }'
    ```

    **Response:**

    ```json theme={null}
    {
      "ok": true
    }
    ```

    **3. Confirm that the `type` has changed to `ongoing` and the `starts_at` and `ends_at` are `None`.**

    **Request:**

    ```bash theme={null}
    # Use GET or POST.
    curl -X 'GET' \
      'https://connect.getseam.com/access_codes/get' \
      -H 'accept: application/json' \
      -H "Authorization: Bearer ${SEAM_API_KEY}" \
      -H 'Content-Type: application/json' \
      -d '{
      "access_code_id": "11111111-1111-1111-1111-555555555555"
    }'
    ```

    **Response:**

    ```json theme={null}
    {
      "access_code": {
        "access_code_id": "11111111-1111-1111-1111-555555555555",
        "type": "ongoing",
        ...
      },
      "ok": true
    }
    ```
  </Tab>

  <Tab title="Python">
    **1. Confirm that the access code starts as a time-bound code.**

    **Code:**

    ```python theme={null}
    seam.access_codes.get(
      access_code_id = "11111111-1111-1111-1111-555555555555"
    )
    ```

    **Output:**

    ```
    AccessCode(
      access_code_id='11111111-1111-1111-1111-555555555555',
      type='time_bound',
      starts_at='2025-01-01T16:00:00.000Z',
      ends_at='2025-01-22T12:00:00.000Z',
      ...
    )
    ```

    **2. Update the code to set the `type` to `ongoing`.**

    **Code:**

    ```python theme={null}
    seam.access_codes.update(
      access_code_id = "11111111-1111-1111-1111-555555555555",
      type = "ongoing"
    )
    ```

    **Output:**

    ```
    None
    ```

    **3. Confirm that the `type` has changed to `ongoing` and the `starts_at` and `ends_at` are `None`.**

    **Code:**

    ```python theme={null}
    seam.access_codes.get(
      access_code_id = "11111111-1111-1111-1111-555555555555"
    )
    ```

    **Output:**

    ```
    AccessCode(
      access_code_id='11111111-1111-1111-1111-555555555555',
      type='ongoing',
      ...
    )
    ```
  </Tab>

  <Tab title="Ruby">
    **1. Confirm that the access code starts as a time-bound code.**

    **Code:**

    ```ruby theme={null}
    client.access_codes.get(
      access_code_id: "11111111-1111-1111-1111-555555555555"
    )
    ```

    **Output:**

    ```
    <Seam::AccessCode:0x00438
      access_code_id="11111111-1111-1111-1111-555555555555"
      type="time_bound"
      starts_at=2025-02-01 16:00:00 UTC
      ends_at=2025-02-22 12:00:00 UTC
      ...
    >
    ```

    **2. Update the code to set the `type` to `ongoing`.**

    **Code:**

    ```ruby theme={null}
    client.access_codes.update(
      access_code_id: "11111111-1111-1111-1111-555555555555",
      type: "ongoing"
    )
    ```

    **Output:**

    ```
    nil
    ```

    **3. Confirm that the `type` has changed to `ongoing` and the `starts_at` and `ends_at` are `None`.**

    **Code:**

    ```ruby theme={null}
    client.access_codes.get(
      access_code_id: "11111111-1111-1111-1111-555555555555"
    )
    ```

    **Output:**

    ```
    <Seam::AccessCode:0x00438
      access_code_id="11111111-1111-1111-1111-555555555555"
      type="ongoing"
      ...
    >
    ```
  </Tab>

  <Tab title="PHP">
    **1. Confirm that the access code starts as a time-bound code.**

    **Code:**

    ```php theme={null}
    $seam->access_codes->get(
      access_code_id: "11111111-1111-1111-1111-555555555555"
    );
    ```

    **Output:**

    ```json theme={null}
    {
      "access_code_id": "11111111-1111-1111-1111-555555555555",
      "type": "time_bound",
      "starts_at": "2025-02-01T16:00:00.000Z",
      "ends_at": "2025-02-22T12:00:00.000Z",
      ...
    }
    ```

    **2. Update the code to set the `type` to `ongoing`.**

    **Code:**

    ```php theme={null}
    $seam->access_codes->update(
      access_code_id: "11111111-1111-1111-1111-555555555555",
      type: "ongoing"
    );
    ```

    **Output:**

    ```
    void
    ```

    **3. Confirm that the `type` has changed to `ongoing` and the `starts_at` and `ends_at` are `None`.**

    **Code:**

    ```php theme={null}
    $seam->access_codes->get(
      access_code_id: "11111111-1111-1111-1111-555555555555"
    );
    ```

    **Output:**

    ```json theme={null}
    {
      "access_code_id": "11111111-1111-1111-1111-555555555555",
      "type": "ongoing",
      ...
    }
    ```
  </Tab>

  <Tab title="C#">
    **1. Confirm that the access code starts as a time-bound code.**

    **Code:**

    ```csharp theme={null}
    seam.AccessCodes.Get(
      accessCodeId: "11111111-1111-1111-1111-555555555555"
    );
    ```

    **Output:**

    ```json theme={null}
    {
      "access_code_id": "11111111-1111-1111-1111-555555555555",
      "type": "time_bound",
      "starts_at": "2025-02-01T16:00:00.000Z",
      "ends_at": "2025-02-22T12:00:00.000Z",
      ...
    }
    ```

    **2. Update the code to set the `type` to `ongoing`.**

    **Code:**

    ```csharp theme={null}
    seam.AccessCodes.Update(
      accessCodeId: "11111111-1111-1111-1111-555555555555",
      type: Seam.Api.AccessCodes.UpdateRequest.TypeEnum.Ongoing
    );
    ```

    **Output:**

    ```
    void
    ```

    **3. Confirm that the `type` has changed to `ongoing` and the `starts_at` and `ends_at` are `None`.**

    **Code:**

    ```csharp theme={null}
    seam.AccessCodes.Get(
      accessCodeId: "11111111-1111-1111-1111-555555555555"
    );
    ```

    **Output:**

    ```json theme={null}
    {
      "access_code_id": "11111111-1111-1111-1111-555555555555",
      "type": "ongoing",
      ...
    }
    ```
  </Tab>
</Tabs>


# Managing Offline Access Codes
Source: https://docs.seam.co/low-level-apis/smart-locks/access-codes/offline-access-codes

Learn how to create offline access codes for applicable smart locks with keypads.

## Overview

This guide explains how to create [offline access (PIN) codes](#offline-access-code-restrictions) for smart locks that support these types of codes. Use the [Access Codes](/api/access_codes/object) API to generate a [time-bound](#creating-time-bound-offline-access-codes) or [one-time-use](#creating-one-time-use-offline-access-codes) offline access code. Note that Seam support for offline access code functions varies depending on the device manufacturer. For details, see the corresponding device guide.

* [igloohome Locks device guide](/device-and-system-integration-guides/igloohome-locks/creating-igloohome-offline-access-codes)
* [dormakaba Oracode Locks device guide](/device-and-system-integration-guides/dormakaba-oracode-locks/creating-dormakaba-oracode-offline-access-codes)
* [Lockly Locks device guide](/device-and-system-integration-guides/lockly-locks/creating-lockly-offline-access-codes)

<Info>
  For information about online access codes, see [Managing Access Codes](./).
</Info>

***

## Offline Access Code Restrictions

Note the following restrictions on offline access codes:

* You cannot set custom codes for offline access codes.

  For devices that support offline access codes, these PIN codes are retrieved from the door lock itself. That is, these PIN codes are not programmed using Wi-Fi. Rather, they are generated by an algorithm.

* Once you create an offline access code, you cannot use the Seam API to update or delete it.

### Brand-Specific Offline Access Code Restrictions

It is imperative to understand all manufacturer- and device-specific behaviors and constraints. For example, igloohome categorizes time-bound offline access codes as hourly-bound or daily-bound and enforces maximum numbers of each type. Also, you must configure dormakaba Oracode offline access codes to fit into specific predefined time slots called "user levels." Further, some manufacturers support one-time-use offline access codes, while others do not.

For details, see the corresponding device guide. Also, [get the lock](/api/devices/get) and view any manufacturer-specific properties.

* [igloohome Locks device guide](/device-and-system-integration-guides/igloohome-locks/creating-igloohome-offline-access-codes)
* [dormakaba Oracode Locks device guide](/device-and-system-integration-guides/dormakaba-oracode-locks/creating-dormakaba-oracode-offline-access-codes)
* [Lockly Locks device guide](/device-and-system-integration-guides/lockly-locks/creating-lockly-offline-access-codes)

***

## Before You Begin: Confirm Capabilities

Before you attempt to create an offline access code, be sure to confirm that your device has the capability to perform this operation. You can check the following [capability flag](../../../capability-guides/device-and-system-capabilities#capability-flags) for the device:

* `device.can_program_offline_access_codes`

Use [Get Device](/api/devices/get) for a specific device to return this capability flag. Then, use an `if` statement or similar check to confirm that this flag is both present and `true` before attempting to create an offline access code.

**Request:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  await seam.locks.get('11111111-1111-1111-1111-444444444444')
  ```

  ```bash cURL theme={null}
  # 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"
  }'
  ```

  ```python Python theme={null}
  seam.locks.get(device="11111111-1111-1111-1111-444444444444")
  ```

  ```ruby Ruby theme={null}
  client.locks.get(device_id: "11111111-1111-1111-1111-444444444444")
  ```

  ```php PHP theme={null}
  $seam->devices->get("11111111-1111-1111-1111-444444444444");
  ```

  ```csharp C# theme={null}
  seam.Devices.Get(deviceId: "11111111-1111-1111-1111-444444444444");
  ```
</CodeGroup>

**Response:**

<CodeGroup>
  ```json JavaScript theme={null}
  {
    device_id: '11111111-1111-1111-1111-444444444444',
    can_program_offline_access_codes: true, // You can create offline access codes for this device.
    ...
  }
  ```

  ```json cURL theme={null}
  {
    "lock": {
      "device_id": "11111111-1111-1111-1111-444444444444",
      "can_program_offline_access_codes": true, // You can create offline access codes for this device.
      ...
    },
    "ok": true
  }
  ```

  ```json Python theme={null}
  Device(
    device_id='11111111-1111-1111-1111-444444444444',
    can_program_offline_access_codes=True, // You can create offline access codes for this device.
    ...
  )
  ```

  ```json Ruby theme={null}
  <Seam::Device:0x00438
    device_id="11111111-1111-1111-1111-444444444444"
    can_program_offline_access_codes=true // You can create offline access codes for this device.
    ...
  >
  ```

  ```json PHP theme={null}
  {
    "device_id": "11111111-1111-1111-1111-444444444444",
    "can_program_offline_access_codes": true, // You can create offline access codes for this device.
    ...
  }
  ```

  ```json C# theme={null}
  {
    "device_id": "11111111-1111-1111-1111-444444444444",
    "can_program_offline_access_codes": true, // You can create offline access codes for this device.
    ...
  }
  ```
</CodeGroup>

***

## Creating Time-Bound Offline Access Codes

For [Lockly locks](/device-and-system-integration-guides/lockly-locks/creating-lockly-offline-access-codes), you can create time-bound offline access codes that define a validity period using `starts_at` and `ends_at` timestamps. For [igloohome locks](/device-and-system-integration-guides/igloohome-locks/creating-igloohome-offline-access-codes) and [dormakaba Oracode locks](/device-and-system-integration-guides/dormakaba-oracode-locks/creating-dormakaba-oracode-offline-access-codes), you can create time-bound offline access codes with validity durations at either the hour level or the day level.

<Info>
  Make sure to learn any manufacturer-specific behavior and restrictions
  regarding time-bound offline access codes. For details, see the corresponding
  [device
  guide](/device-and-system-integration-guides#smart-locks).
</Info>

To create a time-bound offline access code, first issue a creation request. Then, poll or use a webhook to confirm that the code was registered successfully in the device manufacturer's offline access code server.

### 1. Create a Time-Bound Offline Access Code

To create a time-bound offline access code, provide the `device_id` of the lock for which you want to create the code and set `is_offline_access_code` to `true`. Specify the `starts_at` and `ends_at` [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) timestamps to define the active time window for the offline code. You can also assign an optional `name` to the offline access code. For more details, see the [Create Access Code endpoint](/api/access_codes/create).

**Request:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  // Get the device.
  const device = await seam.locks.get({
    device_id: '11111111-1111-1111-1111-444444444444',
  })

  // Confirm that the device supports offline access codes.
  if (device.can_program_offline_access_codes) {
    // Create the time-bound offline access code.
    await seam.accessCodes.create({
      device_id: device.device_id,
      name: 'my time-bound offline code',
      starts_at: '2023-11-10T00:00:00-00:00',
      ends_at: '2023-11-15T18:00:00-00:00',
      // To create a daily-bound code for devices
      // that support this feature, include
      // max_time_rounding: "1d",
      is_offline_access_code: true,
    })
  }
  ```

  ```sh cURL theme={null}
  # 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 offline access codes.
  if  $(jq -r '.device.can_program_offline_access_codes' <<< ${device}); then \
    # Create the time-bound offline access code.
    # To create a daily-bound code for devices
    # that support this feature, include
    # \"max_time_rounding\": \"1d\",
    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 offline code\",
        \"starts_at\": \"2023-11-10T00:00:00-00:00\",
        \"ends_at\": \"2023-11-15T18:00:00-00:00\",
        \"is_offline_access_code\": true
    }";
  fi
  ```

  ```python Python theme={null}
  # Get the device.
  device = seam.locks.get(
    device_id="11111111-1111-1111-1111-444444444444"
  )

  # Confirm that the device supports offline access codes.
  if device.can_program_offline_access_codes:
    # Create the time-bound offline access code.
    seam.access_codes.create(
      device_id = device.device_id,
      name = "my time-bound offline code",
      starts_at = "2023-11-10T00:00:00-00:00",
      ends_at = "2023-11-15T18:00:00-00:00",
      # To create a daily-bound code for devices
      # that support this feature, include
      # max_time_rounding = "1d",
      is_offline_access_code = True
    )
  ```

  ```ruby Ruby theme={null}
  # Get the device.
  device = client.locks.get(device_id: "11111111-1111-1111-1111-444444444444")

  # Confirm that the device supports offline access codes.
  if (device.can_program_offline_access_codes)
    # Create the time-bound offline access code.
    client.access_codes.create(
      device_id: device.device_id,
      name: "my time-bound offline code",
      starts_at: "2023-11-10T00:00:00-00:00",
      ends_at: "2023-11-15T18:00:00-00:00",
      # To create a daily-bound code for devices
      # that support this feature, include
      # max_time_rounding: "1d",
      is_offline_access_code: true
    )
  end
  ```

  ```php PHP theme={null}
  // Get the device.
  $device = $seam->locks->get(device_id: "11111111-1111-1111-1111-444444444444");

  // Confirm that the device supports offline access codes.
  if ($device->can_program_offline_access_codes) {
    // Create the time-bound offline access code.
    $seam->access_codes->create(
      device_id: $device->device_id,
      name: "my time-bound offline code",
      starts_at: "2023-11-10T00:00:00Z",
      ends_at: "2023-11-15T18:00:00Z",
      // To create a daily-bound code for devices
      // that support this feature, include
      // max_time_rounding: "1d",
      is_offline_access_code: true
    );
  }
  ```

  ```csharp C# theme={null}
  // Get the device.
  Device device = seam.Locks.Get(deviceId: "11111111-1111-1111-1111-444444444444");

  // Confirm that the device supports offline access codes.
  if (device.CanProgramOfflineAccessCodes == true) {
    // Create the time-bound offline access code.
    seam.AccessCodes.Create(
      deviceId: device.DeviceId,
      name: "my time-bound offline code",
      startsAt: "2023-11-10T00:00:00Z",
      endsAt: "2023-11-15T18:00:00Z",
      // To create a daily-bound code for devices
      // that support this feature, include
      // maxTimeRounding: "1d",
      isOfflineAccessCode: true
    );
  }
  ```
</CodeGroup>

**Response:**

<CodeGroup>
  ```json JavaScript theme={null}
  {
    access_code_id: '11111111-1111-1111-1111-777777777777',
    device_id: '11111111-1111-1111-1111-444444444444',
    name: 'my time-bound offline code',
    type: 'time_bound',
    starts_at: '2023-11-10T00:00:00.000Z',
    ends_at: '2023-11-15T18:00:00.000Z',
    is_offline_access_code: true,
    ...
  }
  ```

  ```json cURL theme={null}
  {
    "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-777777777777",
      "device_id": "11111111-1111-1111-1111-444444444444",
      "name": "my time-bound offline code",
      "type": "time_bound",
      "starts_at": "2023-11-10T00:00:00.000Z",
      "ends_at": "2023-11-15T18:00:00.000Z",
      "is_offline_access_code": true,
      ...
    },
    "ok": true
  }
  ```

  ```json Python theme={null}
  AccessCode(
    access_code_id='11111111-1111-1111-1111-777777777777',
    device_id='11111111-1111-1111-1111-444444444444',
    type='time_bound',
    starts_at='2023-11-10T00:00:00.000Z',
    ends_at='2023-11-15T18:00:00.000Z',
    name='my time-bound offline code',
    is_offline_access_code=True,
    ...
  )
  ```

  ```json Ruby theme={null}
  <Seam::AccessCode:0x00438
    access_code_id="11111111-1111-1111-1111-777777777777"
    device_id="11111111-1111-1111-1111-444444444444"
    name="my time-bound offline code"
    type="time_bound"
    starts_at=2023-11-10 00:00:00 UTC
    ends_at=2023-11-15 18:00:00 UTC
    is_offline_access_code: true
    ...
  >
  ```

  ```json PHP theme={null}
  {
    "access_code_id": "11111111-1111-1111-1111-777777777777",
    "device_id": "11111111-1111-1111-1111-444444444444",
    "name": "my time-bound offline code",
    "type": "time_bound",
    "starts_at": "2023-11-10T00:00:00.000Z",
    "ends_at": "2023-11-15T18:00:00.000Z",
    "is_offline_access_code": true,
    ...
  }
  ```

  ```json C# theme={null}
  {
    "type": "time_bound",
    "access_code_id": "11111111-1111-1111-1111-777777777777",
    "device_id": "11111111-1111-1111-1111-444444444444",
    "name": "my time-bound offline code",
    "starts_at": "2023-11-10T00:00:00Z",
    "ends_at": "2023-11-15T18:00:00Z",
    "is_offline_access_code": true,
    ...
  }
  ```
</CodeGroup>

### 2. Verify Successful Time-Bound Code Registration

The [lifecycle of a time-bound access code](/low-level-apis/smart-locks/access-codes/lifecycle-of-access-codes) is marked by distinct phases:

1. `Unset`: When initially created on Seam, the offline access code remains in an `unset` state, indicating that it is not yet available for use on the lock due to a configured future activation time.
2. `Setting`: As the scheduled `starts_at` time approaches, Seam initiates the process of readying the code for use on the lock, transitioning the `status` of the offline code to `setting`.
3. `Set`: Upon successful programming, the status updates to `set`, signaling that the code is ready to grant the designated user the ability to unlock the door.

There are two methods to verify that an time-bound offline access code has been registered in the offline access code server that the device manufacturer maintains:

* **Polling**: Continuously query the access code until the `status` is updated. For instructions, see [Polling Method](/low-level-apis/smart-locks/access-codes/creating-access-codes/index#polling-method).
* **Webhook**: Wait for updates to arrive using webhook requests from the Seam API. For instructions, see [Webhook Events Method](/low-level-apis/smart-locks/access-codes/creating-access-codes/index#webhook-events-method).

***

## Creating One-Time-Use Offline Access Codes

For [igloohome locks](/device-and-system-integration-guides/igloohome-locks/creating-igloohome-offline-access-codes) and [Lockly locks](/device-and-system-integration-guides/lockly-locks/creating-lockly-offline-access-codes), you can create one-time-use offline access codes. These codes expire after a single use. To confirm whether your device supports one-time-use offline access codes and to learn any manufacturer- and device-specific restrictions, see the corresponding [device guide](/device-and-system-integration-guides#smart-locks).

To create a one-time-use offline access code, first issue a creation request. In this request, set `is_offline_access_code` and `is_one_time_use` to `true`, and specify the desired `starts_at` and `ends_at` timestamps, as applicable for your device. Then, poll or use a webhook to confirm that the code was registered successfully in the offline access code server that the device manufacturer maintains.

### 1. Create a One-Time-Use Offline Access Code

To create a one-time-use offline access code, provide the `device_id` of the lock for which you want to create the code. Set `is_offline_access_code` and `is_one_time_use` to `true`. Specify the `starts_at` [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) timestamp to define the beginning of the active time window for the offline code. If applicable for your device, specify the `ends_at` [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) timestamp to define the end of the active time window for the offline code.

You can also assign an optional `name` to the offline access code. For more details, see the [Create Access Code endpoint](/api/access_codes/create).

**Request:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  // Get the device.
  const device = await seam.locks.get({
    device_id: '11111111-1111-1111-1111-444444444444',
  })

  // Confirm that the device supports offline access codes.
  if (device.can_program_offline_access_codes) {
    // Create the one-time-use offline access code.
    await seam.accessCodes.create({
      device_id: device.device_id,
      name: 'my one-time-use offline code',
      starts_at: '2023-11-12T00:00:00-00:00',
      // Specify ends_at if your device supports it.
      ends_at: '2023-11-14T00:00:00-00:00',
      is_offline_access_code: true,
      is_one_time_use: true,
    })
  }
  ```

  ```sh cURL theme={null}
  # 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 offline access codes.
  if  $(jq -r '.device.can_program_offline_access_codes' <<< ${device}); then \
    # Create the one-time-use offline access code.
    # Specify ends_at if your device supports it.
    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 one-time-use offline code\",
        \"starts_at\": \"2023-11-12T00:00:00-00:00\",
        \"ends_at\": \"2023-11-14T00:00:00-00:00\",
        \"is_offline_access_code\": true,
        \"is_one_time_use\": true
    }";
  fi
  ```

  ```python Python theme={null}
  # Get the device.
  device = seam.locks.get(
    device_id="11111111-1111-1111-1111-444444444444"
  )

  # Confirm that the device supports offline access codes.
  if device.can_program_offline_access_codes:
    # Create the one-time-use offline access code.
    seam.access_codes.create(
      device_id = device.device_id,
      name = "my one-time-use offline code",
      starts_at = "2023-11-12T00:00:00-00:00",
      # Specify ends_at if your device supports it.
      ends_at = "2023-11-14T00:00:00-00:00",
      is_offline_access_code = True,
      is_one_time_use = True
    )
  ```

  ```ruby Ruby theme={null}
  # Get the device.
  device = client.locks.get(device_id: "11111111-1111-1111-1111-444444444444")

  # Confirm that the device supports offline access codes.
  if (device.can_program_offline_access_codes)
    # Create the one-time-use offline access code.
    client.access_codes.create(
      device_id: device.device_id,
      name: "my one-time-use offline code",
      starts_at: "2023-11-12T00:00:00-00:00",
      # Specify ends_at if your device supports it.
      ends_at: "2023-11-14T00:00:00-00:00",
      is_offline_access_code: true,
      is_one_time_use: true
    )
  end
  ```

  ```php PHP theme={null}
  // Get the device.
  $device = $seam->locks->get(device_id: "11111111-1111-1111-1111-444444444444");

  // Confirm that the device supports offline access codes.
  if ($device->can_program_offline_access_codes) {
    // Create the one-time-use offline access code.
    $seam->access_codes->create(
      device_id: $device->device_id,
      name: "my one-time-use offline code",
      starts_at: "2023-11-12T00:00:00Z",
      // Specify ends_at if your device supports it.
      ends_at: "2023-11-14T00:00:00Z",
      is_offline_access_code: true,
      is_one_time_use: true
    );
  }
  ```

  ```csharp C# theme={null}
  // Get the device.
  Device device = seam.Locks.Get(deviceId: "11111111-1111-1111-1111-444444444444");

  // Confirm that the device supports offline access codes.
  if (device.CanProgramOfflineAccessCodes == true) {
    // Create the one-time-use offline access code.
    seam.AccessCodes.Create(
      deviceId: device.DeviceId,
      name: "my one-time-use offline code",
      startsAt: "2023-11-12T00:00:00Z",
      // Specify ends_at if your device supports it.
      endsAt: "2023-11-14T00:00:00Z",
      isOfflineAccessCode: true,
      isOneTimeUse: true
    );
  }
  ```
</CodeGroup>

**Response:**

<CodeGroup>
  ```json JavaScript theme={null}
  {
    access_code_id: '11111111-1111-1111-1111-777777888888',
    device_id: '11111111-1111-1111-1111-444444444444',
    name: 'my one-time-use offline code',
    type: 'time_bound',
    starts_at: '2023-11-12T00:00:00.000Z',
    ends_at: '2023-11-14T00:00:00.000Z',
    is_offline_access_code: true,
    is_one_time_use: true,
    ...
  }
  ```

  ```json cURL theme={null}
  {
    "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-777777888888",
      "device_id": "11111111-1111-1111-1111-444444444444",
      "name": "my one-time-use offline code",
      "type": "time_bound",
      "starts_at": "2023-11-12T00:00:00.000Z",
      "ends_at": "2023-11-14T00:00:00.000Z",
      "is_offline_access_code": true,
      "is_one_time_use": true,
      ...
    },
    "ok": true
  }
  ```

  ```json Python theme={null}
  AccessCode(
    access_code_id='11111111-1111-1111-1111-777777888888',
    device_id='11111111-1111-1111-1111-444444444444',
    type='time_bound',
    starts_at='2023-11-12T00:00:00.000Z',
    ends_at='2023-11-14T00:00:00.000Z',
    name='my one-time-use offline code',
    is_offline_access_code=True,
    is_one_time_use=True,
    ...
  )
  ```

  ```json Ruby theme={null}
  <Seam::AccessCode:0x00438
    access_code_id="11111111-1111-1111-1111-777777888888"
    device_id="11111111-1111-1111-1111-444444444444"
    name="my one-time-use offline code"
    type="time_bound"
    starts_at=2023-11-12 00:00:00 UTC
    ends_at=2023-11-14 00:00:00 UTC
    is_offline_access_code: true
    is_one_time_use: true
    ...
  >
  ```

  ```json PHP theme={null}
  {
    "access_code_id": "11111111-1111-1111-1111-777777888888",
    "device_id": "11111111-1111-1111-1111-444444444444",
    "name": "my one-time-use offline code",
    "type": "time_bound",
    "starts_at": "2023-11-12T00:00:00.000Z",
    "ends_at": "2023-11-14T00:00:00.000Z",
    "is_offline_access_code": true,
    "is_one_time_use": true,
    ...
  }
  ```

  ```json C# theme={null}
  {
    "type": "time_bound",
    "access_code_id": "11111111-1111-1111-1111-777777888888",
    "device_id": "11111111-1111-1111-1111-444444444444",
    "name": "my one-time-use offline code",
    "starts_at": "2023-11-12T00:00:00Z",
    "ends_at": "2023-11-14T00:00:00Z",
    "is_offline_access_code": true,
    "is_one_time_use": true,
    ...
  }
  ```
</CodeGroup>

### 2. Verify Successful One-Time-Use Code Registration

The [lifecycle of a one-time-use access code](/low-level-apis/smart-locks/access-codes/lifecycle-of-access-codes) is marked by distinct phases:

1. `Unset`: When initially created on Seam, the offline access code remains in an `unset` state, indicating that it is not yet available for use on the lock due to a configured future activation time.
2. `Setting`: As the scheduled `starts_at` time approaches, Seam initiates the process of readying the code for use on the lock, transitioning the `status` of the offline code to `setting`.
3. `Set`: Upon successful programming, the status updates to `set`, signaling that the code is ready to grant the designated user the ability to unlock the door.

There are two methods to verify that a one-time-use offline access code has been registered in the offline access code server that the device manufacturer maintains:

* **Polling**: Continuously query the access code until the `status` is updated. For instructions, see [Polling Method](/low-level-apis/smart-locks/access-codes/creating-access-codes/index#polling-method).
* **Webhook**: Wait for updates to arrive using webhook requests from the Seam API. For instructions, see [Webhook Events Method](/low-level-apis/smart-locks/access-codes/creating-access-codes/index#webhook-events-method).


# Retrieving Access Codes
Source: https://docs.seam.co/low-level-apis/smart-locks/access-codes/retrieving-access-codes

Learn how to retrieve access codes using various filters or by referencing their specific IDs

## Retrieving All Access Codes for a Device

To retrieve all access codes for a device, include the `device_id` in the [List Access Codes](/api/access_codes/list) request.

**Request:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  console.log(
    await seam.accessCodes.list({
      device_id: '6aae9d08-fed6-4ca5-8328-e36849ab48fe',
    }),
  )
  ```

  ```bash cURL theme={null}
  # Use GET or POST.
  curl -X 'GET' \
    'https://connect.getseam.com/access_codes/list' \
    -H 'accept: application/json' \
    -H 'Authorization: Bearer ${API_KEY}' \
    -H 'Content-Type: application/json' \
    -d '{
    "device_id": "6aae9d08-fed6-4ca5-8328-e36849ab48fe"
  }'
  ```

  ```python Python theme={null}
  device_id = "6aae9d08-fed6-4ca5-8328-e36849ab48fe"
  access_codes = seam.access_codes.list(device=device_id)

  pprint(access_codes)
  ```

  ```ruby Ruby theme={null}
  device_id = "6aae9d08-fed6-4ca5-8328-e36849ab48fe"

  puts client.access_codes.list(device_id: device_id).inspect
  ```

  ```php PHP theme={null}
  use Seam\SeamClient;

  $seam = new SeamClient("YOUR_API_KEY");

  $device_id = "0e2e6262-7f91-4970-a58d-47ef30b41e2e";

  $access_codes = $seam->access_codes->list(
    device_id: $device_id
  );

  # Inspect the access codes
  echo json_encode($access_codes, JSON_PRETTY_PRINT);

  // [
  //     {
  //         "access_code_id": "e3d6cf81-6dd4-490c-b81f-8478054c2003",
  //         "device_id": "0e2e6262-7f91-4970-a58d-47ef30b41e2e",
  //         "name": "my timebound code",
  //         "type": "time_bound",
  //         "status": "unset",
  //         "starts_at": "2025-01-01T16:00:00.000Z",
  //         "ends_at": "2025-01-22T12:00:00.000Z",
  //         "code": "834435",
  //         "created_at": "2023-09-04T05:32:32.085Z",
  //         "errors": [],
  //         "warnings": [],
  //         "is_managed": true,
  //         "common_code_key": null,
  //         "is_waiting_for_code_assignment": null
  //     },
  //     {
  //         "access_code_id": "bd7e8681-4df6-437c-a12a-e965ecca9caf",
  //         "device_id": "0e2e6262-7f91-4970-a58d-47ef30b41e2e",
  //         "name": "my ongoing code",
  //         "type": "ongoing",
  //         "status": "set",
  //         "starts_at": null,
  //         "ends_at": null,
  //         "code": "453419",
  //         "created_at": "2023-09-04T05:29:08.084Z",
  //         "errors": [],
  //         "warnings": [],
  //         "is_managed": true,
  //         "common_code_key": null,
  //         "is_waiting_for_code_assignment": null
  //     }
  // ]

  ```

  ```csharp C# theme={null}
  var deviceId = "6aae9d08-fed6-4ca5-8328-e36849ab48fe";
  var accessCodes = seam.AccessCodes.List(deviceId: deviceId);

  foreach (var accessCode in accessCodes)
  {
    Console.WriteLine("Access code ID: " + accessCode.AccessCodeId);
    Console.WriteLine("Type: " + accessCode.Type);
    Console.WriteLine("Code: " + accessCode.Code);
    Console.WriteLine();
  }
  ```
</CodeGroup>

**Response:**

<CodeGroup>
  ```json JavaScript theme={null}
  [
    {
      "access_code_id": "80aa1afa-f0e5-43c2-96ea-6ab141112f9c",
      "device_id": "6aae9d08-fed6-4ca5-8328-e36849ab48fe",
      "name": "my time-bound code",
      "appearance": null,
      "code": "2345",
      "common_code_key": null,
      "type": "time_bound",
      "status": "unset",
      "is_scheduled_on_device": false,
      "starts_at": "2025-01-01T16:00:00.000Z",
      "ends_at": "2025-01-22T12:00:00.000Z",
      "pulled_backup_access_code_id": null,
      "is_backup_access_code_available": true,
      "created_at": "2023-10-19T09:36:51.663Z",
      "errors": [],
      "warnings": [],
      "is_managed": true,
      "is_external_modification_allowed": false
    },
    {
      "access_code_id": "f4780806-076e-4cec-8081-df0ea2139d5a",
      "device_id": "6aae9d08-fed6-4ca5-8328-e36849ab48fe",
      "name": "my ongoing code",
      "appearance": {
        "name": "my ongoing code",
        "last_name": "ongoing code",
        "first_name": "my"
      },
      "code": "1234",
      "common_code_key": null,
      "type": "ongoing",
      "status": "set",
      "pulled_backup_access_code_id": null,
      "is_backup_access_code_available": true,
      "created_at": "2023-10-19T09:30:58.399Z",
      "errors": [],
      "warnings": [],
      "is_managed": true,
      "is_external_modification_allowed": false
    }
  ]
  ```

  ```json cURL theme={null}
  {
    "access_codes": [
      {
        "access_code_id": "27afb24f-c0ae-4ea9-81af-f06fd08de09f",
        "device_id": "6aae9d08-fed6-4ca5-8328-e36849ab48fe",
        "name": "my time-bound code",
        "appearance": null,
        "code": "2345",
        "common_code_key": null,
        "type": "time_bound",
        "status": "unset",
        "is_scheduled_on_device": false,
        "starts_at": "2025-01-01T16:00:00.000Z",
        "ends_at": "2025-01-22T12:00:00.000Z",
        "pulled_backup_access_code_id": null,
        "is_backup_access_code_available": true,
        "created_at": "2023-10-19T06:58:42.853Z",
        "errors": [],
        "warnings": [],
        "is_managed": true,
        "is_external_modification_allowed": false
      },
      {
        "access_code_id": "d2047ba8-8849-467f-a07a-efab6c3673bc",
        "device_id": "6aae9d08-fed6-4ca5-8328-e36849ab48fe",
        "name": "my ongoing code",
        "appearance": {
          "name": "my ongoing code",
          "last_name": "ongoing code",
          "first_name": "my"
        },
        "code": "1234",
        "common_code_key": null,
        "type": "ongoing",
        "status": "set",
        "pulled_backup_access_code_id": null,
        "is_backup_access_code_available": true,
        "created_at": "2023-10-19T06:55:28.278Z",
        "errors": [],
        "warnings": [],
        "is_managed": true,
        "is_external_modification_allowed": false
      }
    ],
    "ok": true
  }
  ```

  ```json Python theme={null}
  [AccessCode(access_code_id='1bbd1eba-e4a2-4f96-b1b9-8498a5405b2b',
              device_id='6aae9d08-fed6-4ca5-8328-e36849ab48fe',
              type='time_bound',
              code='2345',
              created_at='2023-10-19T02:21:58.738Z',
              errors=[],
              warnings=[],
              starts_at='2025-01-01T16:00:00.000Z',
              ends_at='2025-01-22T12:00:00.000Z',
              name='my time-bound code',
              status='unset',
              common_code_key=None,
              is_managed=True,
              is_waiting_for_code_assignment=None,
              is_scheduled_on_device=False,
              pulled_backup_access_code_id=None,
              is_backup_access_code_available=False,
              is_backup=None,
              appearance=None,
              is_external_modification_allowed=False),
   AccessCode(access_code_id='daf89de3-ad3a-49aa-93bd-25f27d58f699',
              device_id='6aae9d08-fed6-4ca5-8328-e36849ab48fe',
              type='ongoing',
              code='1234',
              created_at='2023-10-19T02:15:04.911Z',
              errors=[],
              warnings=[],
              starts_at=None,
              ends_at=None,
              name='my ongoing code',
              status='set',
              common_code_key=None,
              is_managed=True,
              is_waiting_for_code_assignment=None,
              is_scheduled_on_device=None,
              pulled_backup_access_code_id=None,
              is_backup_access_code_available=False,
              is_backup=None,
              appearance={'first_name': 'my',
                          'last_name': 'ongoing code',
                          'name': 'my ongoing code'},
              is_external_modification_allowed=False)]
  ```

  ```json Ruby theme={null}
  [<Seam::AccessCode:0x00438
    access_code_id="0d2c8b21-c71f-4301-82ea-22830f749d9b"
    device_id="6aae9d08-fed6-4ca5-8328-e36849ab48fe"
    name="my time-bound code"
    appearance=nil
    code="2345"
    type="time_bound"
    status="unset"
    is_scheduled_on_device=false
    starts_at=2025-01-01 16:00:00 UTC
    ends_at=2025-01-22 12:00:00 UTC
    pulled_backup_access_code_id=nil
    is_backup_access_code_available=true
    created_at=2023-10-23 20:56:49.213 UTC
    errors=[]
    warnings=[]
    is_managed=true
    is_external_modification_allowed=false>, <Seam::AccessCode:0x00460
    access_code_id="6fe348a8-5938-4b73-8a36-86f7ffdfc431"
    device_id="6aae9d08-fed6-4ca5-8328-e36849ab48fe"
    name="my ongoing code"
    appearance={"name"=>"my ongoing code", "last_name"=>"ongoing code", "first_name"=>"my"}
    code="1234"
    type="ongoing"
    status="set"
    pulled_backup_access_code_id=nil
    is_backup_access_code_available=true
    created_at=2023-10-23 20:49:42.932 UTC
    errors=[]
    warnings=[]
    is_managed=true
    is_external_modification_allowed=false>]
  ```

  ```json C# theme={null}
  Access code ID: 2928083e-4377-4467-ab33-c600ec48cdec
  Type: TimeBound
  Code: 2345

  Access code ID: fe372cb9-1fa5-492f-9494-ea01c5558333
  Type: Ongoing
  Code: 1234
  ```
</CodeGroup>

***

## Retrieving Access Codes Using Access Code IDs

To retrieve access codes by IDs, include the desired `access_code_ids` in the [List Access Codes](/api/access_codes/list) request.

**Request:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  const accessCodeIds = [
    '80aa1afa-f0e5-43c2-96ea-6ab141112f9c',
    'f4780806-076e-4cec-8081-df0ea2139d5a',
  ]
  console.log(
    await seam.accessCodes.list({
      access_code_ids: accessCodeIds,
    }),
  )
  ```

  ```bash cURL theme={null}
  # Use GET or POST.
  curl -X 'GET' \
    'https://connect.getseam.com/access_codes/list' \
    -H 'accept: application/json' \
    -H 'Authorization: Bearer ${API_KEY}' \
    -H 'Content-Type: application/json' \
    -d '{
    "access_code_ids": [
      "27afb24f-c0ae-4ea9-81af-f06fd08de09f",
      "d2047ba8-8849-467f-a07a-efab6c3673bc"
    ]
  }'
  ```

  ```python Python theme={null}
  access_code_ids = [
      "1bbd1eba-e4a2-4f96-b1b9-8498a5405b2b",
      "daf89de3-ad3a-49aa-93bd-25f27d58f699"
  ]
  access_codes = seam.access_codes.list(access_codes=access_code_ids)

  pprint(access_codes)
  ```

  ```ruby Ruby theme={null}
  access_code_ids = ["0d2c8b21-c71f-4301-82ea-22830f749d9b", "6fe348a8-5938-4b73-8a36-86f7ffdfc431"]
  access_codes = client.access_codes.list(access_code_ids: access_code_ids)

  puts access_codes.inspect
  ```

  ```php PHP theme={null}
  /** not implemented; contact us if you need immediate support **/
  ```

  ```csharp C# theme={null}
  List<string> accessCodeIds = new() {
    "2928083e-4377-4467-ab33-c600ec48cdec",
    "fe372cb9-1fa5-492f-9494-ea01c5558333"
  };
  var accessCodes = seam.AccessCodes.List(accessCodeIds: accessCodeIds);

  foreach (var accessCode in accessCodes)
  {
    Console.WriteLine("Access code ID: " + accessCode.AccessCodeId);
    Console.WriteLine("Type: " + accessCode.Type);
    Console.WriteLine("Code: " + accessCode.Code);
    Console.WriteLine();
  }
  ```
</CodeGroup>

**Response:**

<CodeGroup>
  ```json JavaScript theme={null}
  [
    {
      "access_code_id": "80aa1afa-f0e5-43c2-96ea-6ab141112f9c",
      "device_id": "6aae9d08-fed6-4ca5-8328-e36849ab48fe",
      "name": "my time-bound code",
      "appearance": null,
      "code": "2345",
      "common_code_key": null,
      "type": "time_bound",
      "status": "unset",
      "is_scheduled_on_device": false,
      "starts_at": "2025-01-01T16:00:00.000Z",
      "ends_at": "2025-01-22T12:00:00.000Z",
      "pulled_backup_access_code_id": null,
      "is_backup_access_code_available": true,
      "created_at": "2023-10-19T09:36:51.663Z",
      "errors": [],
      "warnings": [],
      "is_managed": true,
      "is_external_modification_allowed": false
    },
    {
      "access_code_id": "f4780806-076e-4cec-8081-df0ea2139d5a",
      "device_id": "6aae9d08-fed6-4ca5-8328-e36849ab48fe",
      "name": "my ongoing code",
      "appearance": {
        "name": "my ongoing code",
        "last_name": "ongoing code",
        "first_name": "my"
      },
      "code": "1234",
      "common_code_key": null,
      "type": "ongoing",
      "status": "set",
      "pulled_backup_access_code_id": null,
      "is_backup_access_code_available": true,
      "created_at": "2023-10-19T09:30:58.399Z",
      "errors": [],
      "warnings": [],
      "is_managed": true,
      "is_external_modification_allowed": false
    }
  ]
  ```

  ```json cURL theme={null}
  {
    "access_codes": [
      {
        "access_code_id": "27afb24f-c0ae-4ea9-81af-f06fd08de09f",
        "device_id": "6aae9d08-fed6-4ca5-8328-e36849ab48fe",
        "name": "my time-bound code",
        "appearance": null,
        "code": "2345",
        "common_code_key": null,
        "type": "time_bound",
        "status": "unset",
        "is_scheduled_on_device": false,
        "starts_at": "2025-01-01T16:00:00.000Z",
        "ends_at": "2025-01-22T12:00:00.000Z",
        "pulled_backup_access_code_id": null,
        "is_backup_access_code_available": true,
        "created_at": "2023-10-19T06:58:42.853Z",
        "errors": [],
        "warnings": [],
        "is_managed": true,
        "is_external_modification_allowed": false
      },
      {
        "access_code_id": "d2047ba8-8849-467f-a07a-efab6c3673bc",
        "device_id": "6aae9d08-fed6-4ca5-8328-e36849ab48fe",
        "name": "my ongoing code",
        "appearance": {
          "name": "my ongoing code",
          "last_name": "ongoing code",
          "first_name": "my"
        },
        "code": "1234",
        "common_code_key": null,
        "type": "ongoing",
        "status": "set",
        "pulled_backup_access_code_id": null,
        "is_backup_access_code_available": true,
        "created_at": "2023-10-19T06:55:28.278Z",
        "errors": [],
        "warnings": [],
        "is_managed": true,
        "is_external_modification_allowed": false
      }
    ],
    "ok": true
  }
  ```

  ```json Python theme={null}
  [AccessCode(access_code_id='1bbd1eba-e4a2-4f96-b1b9-8498a5405b2b',
              device_id='6aae9d08-fed6-4ca5-8328-e36849ab48fe',
              type='time_bound',
              code='2345',
              created_at='2023-10-19T02:21:58.738Z',
              errors=[],
              warnings=[],
              starts_at='2025-01-01T16:00:00.000Z',
              ends_at='2025-01-22T12:00:00.000Z',
              name='my time-bound code',
              status='unset',
              common_code_key=None,
              is_managed=True,
              is_waiting_for_code_assignment=None,
              is_scheduled_on_device=False,
              pulled_backup_access_code_id=None,
              is_backup_access_code_available=False,
              is_backup=None,
              appearance=None,
              is_external_modification_allowed=False),
   AccessCode(access_code_id='daf89de3-ad3a-49aa-93bd-25f27d58f699',
              device_id='6aae9d08-fed6-4ca5-8328-e36849ab48fe',
              type='ongoing',
              code='1234',
              created_at='2023-10-19T02:15:04.911Z',
              errors=[],
              warnings=[],
              starts_at=None,
              ends_at=None,
              name='my ongoing code',
              status='set',
              common_code_key=None,
              is_managed=True,
              is_waiting_for_code_assignment=None,
              is_scheduled_on_device=None,
              pulled_backup_access_code_id=None,
              is_backup_access_code_available=False,
              is_backup=None,
              appearance={'first_name': 'my',
                          'last_name': 'ongoing code',
                          'name': 'my ongoing code'},
              is_external_modification_allowed=False)]
  ```

  ```json Ruby theme={null}
  [<Seam::AccessCode:0x00438
    access_code_id="0d2c8b21-c71f-4301-82ea-22830f749d9b"
    device_id="6aae9d08-fed6-4ca5-8328-e36849ab48fe"
    name="my time-bound code"
    appearance=nil
    code="2345"
    type="time_bound"
    status="unset"
    is_scheduled_on_device=false
    starts_at=2025-01-01 16:00:00 UTC
    ends_at=2025-01-22 12:00:00 UTC
    pulled_backup_access_code_id=nil
    is_backup_access_code_available=true
    created_at=2023-10-23 20:56:49.213 UTC
    errors=[]
    warnings=[]
    is_managed=true
    is_external_modification_allowed=false>, <Seam::AccessCode:0x00460
    access_code_id="6fe348a8-5938-4b73-8a36-86f7ffdfc431"
    device_id="6aae9d08-fed6-4ca5-8328-e36849ab48fe"
    name="my ongoing code"
    appearance={"name"=>"my ongoing code", "last_name"=>"ongoing code", "first_name"=>"my"}
    code="1234"
    type="ongoing"
    status="set"
    pulled_backup_access_code_id=nil
    is_backup_access_code_available=true
    created_at=2023-10-23 20:49:42.932 UTC
    errors=[]
    warnings=[]
    is_managed=true
    is_external_modification_allowed=false>]
  ```

  ```json C# theme={null}
  Access code ID: 2928083e-4377-4467-ab33-c600ec48cdec
  Type: TimeBound
  Code: 2345

  Access code ID: fe372cb9-1fa5-492f-9494-ea01c5558333
  Type: Ongoing
  Code: 1234
  ```
</CodeGroup>

***

## Retrieving Individual Access Codes

To retrieve a specific access code, include the desired `access_code_id` in the [Get Access Code](/api/access_codes/get) request.

**Request:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  console.log(
    await seam.accessCodes.get({
      access_code_id: 'f4780806-076e-4cec-8081-df0ea2139d5a',
    }),
  )
  ```

  ```bash cURL theme={null}
  # Use GET or POST.
  curl -X 'GET' \
    'https://connect.getseam.com/access_codes/get' \
    -H 'accept: application/json' \
    -H 'Authorization: Bearer ${API_KEY}' \
    -H 'Content-Type: application/json' \
    -d '{
    "access_code_id": "d2047ba8-8849-467f-a07a-efab6c3673bc"
  }'
  ```

  ```python Python theme={null}
  access_code_id = "daf89de3-ad3a-49aa-93bd-25f27d58f699"
  access_code = seam.access_codes.get(access_code_id)

  pprint(access_code)
  ```

  ```ruby Ruby theme={null}
  puts client.access_codes.get(access_code_id: "6fe348a8-5938-4b73-8a36-86f7ffdfc431").inspect
  ```

  ```php PHP theme={null}
  use Seam\SeamClient;

  $seam = new SeamClient("YOUR_API_KEY");

  $access_code_id = "e3d6cf81-6dd4-490c-b81f-8478054c2003";

  $access_code = $seam->access_codes->get(
    access_code_id: $access_code_id
  );

  # Inspect access codes
  echo json_encode($access_code, JSON_PRETTY_PRINT);

  // {
  //     "access_code_id": "e3d6cf81-6dd4-490c-b81f-8478054c2003",
  //     "device_id": "0e2e6262-7f91-4970-a58d-47ef30b41e2e",
  //     "name": "my timebound code",
  //     "type": "time_bound",
  //     "status": "unset",
  //     "starts_at": "2025-01-01T16:00:00.000Z",
  //     "ends_at": "2025-01-22T12:00:00.000Z",
  //     "code": "834435",
  //     "created_at": "2023-09-04T05:32:32.085Z",
  //     "errors": [],
  //     "warnings": [],
  //     "is_managed": true,
  //     "common_code_key": null,
  //     "is_waiting_for_code_assignment": null
  // }
  ```

  ```csharp C# theme={null}
  var accessCode = seam.AccessCodes.Get(accessCodeId: "fe372cb9-1fa5-492f-9494-ea01c5558333");

  Console.WriteLine("Access code ID: " + accessCode.AccessCodeId);
  Console.WriteLine("Type: " + accessCode.Type);
  Console.WriteLine("Code: " + accessCode.Code);
  Console.WriteLine();
  ```
</CodeGroup>

**Response:**

<CodeGroup>
  ```json JavaScript theme={null}
  {
    "access_code_id": "f4780806-076e-4cec-8081-df0ea2139d5a",
    "device_id": "6aae9d08-fed6-4ca5-8328-e36849ab48fe",
    "name": "my ongoing code",
    "appearance": {
      "name": "my ongoing code",
      "last_name": "ongoing code",
      "first_name": "my"
    },
    "code": "1234",
    "common_code_key": null,
    "type": "ongoing",
    "status": "set",
    "pulled_backup_access_code_id": null,
    "is_backup_access_code_available": true,
    "created_at": "2023-10-19T09:30:58.399Z",
    "errors": [],
    "warnings": [],
    "is_managed": true,
    "is_external_modification_allowed": false
  }
  ```

  ```json cURL theme={null}
  {
    "access_code": {
      "access_code_id": "d2047ba8-8849-467f-a07a-efab6c3673bc",
      "device_id": "6aae9d08-fed6-4ca5-8328-e36849ab48fe",
      "name": "my ongoing code",
      "appearance": {
        "name": "my ongoing code",
        "last_name": "ongoing code",
        "first_name": "my"
      },
      "code": "1234",
      "common_code_key": null,
      "type": "ongoing",
      "status": "set",
      "pulled_backup_access_code_id": null,
      "is_backup_access_code_available": true,
      "created_at": "2023-10-19T06:55:28.278Z",
      "errors": [],
      "warnings": [],
      "is_managed": true,
      "is_external_modification_allowed": false
    },
    "ok": true
  }
  ```

  ```json Python theme={null}
  AccessCode(access_code_id='daf89de3-ad3a-49aa-93bd-25f27d58f699',
             device_id='6aae9d08-fed6-4ca5-8328-e36849ab48fe',
             type='ongoing',
             code='1234',
             created_at='2023-10-19T02:15:04.911Z',
             errors=[],
             warnings=[],
             starts_at=None,
             ends_at=None,
             name='my ongoing code',
             status='set',
             common_code_key=None,
             is_managed=True,
             is_waiting_for_code_assignment=None,
             is_scheduled_on_device=None,
             pulled_backup_access_code_id=None,
             is_backup_access_code_available=False,
             is_backup=None,
             appearance={'first_name': 'my',
                         'last_name': 'ongoing code',
                         'name': 'my ongoing code'},
             is_external_modification_allowed=False)
  ```

  ```json Ruby theme={null}
  <Seam::AccessCode:0x00438
    access_code_id="6fe348a8-5938-4b73-8a36-86f7ffdfc431"
    device_id="6aae9d08-fed6-4ca5-8328-e36849ab48fe"
    name="my ongoing code"
    appearance={"name"=>"my ongoing code", "last_name"=>"ongoing code", "first_name"=>"my"}
    code="1234"
    type="ongoing"
    status="set"
    pulled_backup_access_code_id=nil
    is_backup_access_code_available=true
    created_at=2023-10-23 20:49:42.932 UTC
    errors=[]
    warnings=[]
    is_managed=true
    is_external_modification_allowed=false>
  ```

  ```json C# theme={null}
  Access code ID: fe372cb9-1fa5-492f-9494-ea01c5558333
  Type: Ongoing
  Code: 1234
  ```
</CodeGroup>


# Troubleshooting Access Codes
Source: https://docs.seam.co/low-level-apis/smart-locks/access-codes/troubleshooting-access-code-issues

Learn about how to diagnose and fix access code issues.

Seam might encounter issues when programming an access code on a lock. This troubleshooting guide helps you to determine the cause of access code programming issues and learn how to fix these issues.

When scheduling an access code on a device that supports [native scheduling](/low-level-apis/smart-locks/access-codes#native-scheduling), Seam begins to load it onto the device three days in advance, unless it's a [just-in-time code](/low-level-apis/smart-locks/access-codes#native-scheduling). Seam records any errors or warnings on the access code when it attempts to set it on the device. This approach ensures that you have ample time to address any issues, using the mitigation steps in this guide. Note that not all device brands support the ability to program codes in advance. See [Native Scheduling—Supported Providers](/low-level-apis/smart-locks/access-codes#native-scheduling-supported-providers) for details.

## Access Code Error Handling

Seam provides both generic and more specific access code errors. We recommend that you add error handling logic to your app for each of the following generic errors:

| Error Type                             | Description                                                                                                                                                                                                                                                                                                               |
| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `failed_to_set_on_device`              | An error occurred when we tried to set the access code on the device. We will continue to try and set the code on the device in case the error was temporary.                                                                                                                                                             |
| `failed_to_remove_from_device`         | An error occurred when we tried to remove the access code from the device. We will continue to try and remove the code from the device in case the error was temporary.                                                                                                                                                   |
| `code_modified_external_to_seam`       | We detected that the code was modified or removed externally after Seam successfully set it on the device. We will attempt to set the code on the device again. Please advise the user that Seam will re-set codes they modify or remove manually, and to review other lock integrations that may be modifying the codes. |
| `conflicting_unmanaged_access_code_id` | An access code called "Foo bar" with the same pin already exists on the device.                                                                                                                                                                                                                                           |

Your app should also include a fallback case if it encounters an unknown generic error code.

When Seam is able to provide more specific information beyond one of the generic errors, your app can display additional context or suggest provider-specific resolutions.

<Info>
  If the device or connected account associated with an access code has an
  error, it is attached to the access code alongside any other access code
  errors. Treat these errors as specific errors.
</Info>

## Determining the Issue

The first step in troubleshooting an access code issue is to figure out what the issue is from Seam's point of view. Make a [Get Access Code](/api/access_codes/get) or [List Access Codes](/api/access_codes/list) request and look at the `errors` and `warnings` payloads on the access code object. Look at the error and warning codes. Then, see the matching remedy in [Suggested Access Code Remedies](#suggested-access-code-remedies) for next steps.

**Request:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  const accessCode = await seam.accessCodes.get({
    access_code_id: '38a569bb-40b9-4e42-97bd-bb78f8d96777',
  })

  console.log('Errors:')
  console.log(accessCode.errors)
  console.log('Warnings:')
  console.log(accessCode.warnings)
  ```

  ```bash cURL theme={null}
  # Use GET or POST.
  curl -X 'GET' \
    'https://connect.getseam.com/access_codes/get' \
    -H 'accept: application/json' \
    -H 'Authorization: Bearer ${API_KEY}' \
    -H 'Content-Type: application/json' \
    -d '{
    "access_code_id": "a7b85c1f-9963-4fa8-b106-7ce580a41256"
  }'
  ```

  ```python Python theme={null}
  access_code = seam.access_codes.get("1d9fe873-3393-4b29-b93e-87fe7f923462")

  pprint("Errors:")
  pprint(access_code.errors)
  pprint("Warnings:")
  pprint(access_code.warnings)
  ```

  ```ruby Ruby theme={null}
  access_code = client.access_codes.get(access_code_id: "8f1f576f-ee52-4f12-97f6-7a1593965dec")
  puts "Errors:"
  puts access_code.errors
  puts "Warnings:"
  puts access_code.warnings
  ```

  ```php PHP theme={null}
  $access_code = $seam->access_codes->get('ed4a1f62-9070-4379-8c46-ea30a99e4d74');

  if (property_exists($access_code, 'errors')) {
      echo json_encode($access_code->errors);
  }

  if (property_exists($access_code, 'warnings')) {
      echo json_encode($access_code->warnings);
  }
  ```

  ```csharp C# theme={null}
  var accessCode = seam.AccessCodes.Get(accessCodeId: "65f4a1d3-5f3a-45a4-a6b7-372c7f16c007");

  Console.WriteLine("Access code ID: " + accessCode.AccessCodeId);
  Console.WriteLine("Errors:");
  Console.WriteLine(accessCode.Errors);
  Console.WriteLine("Warnings:");
  Console.WriteLine(accessCode.Warnings);
  ```
</CodeGroup>

**Response:**

<CodeGroup>
  ```json JavaScript theme={null}
  Errors:
  [...]
  Warnings:
  [...]
  ```

  ```json cURL theme={null}
  {
    "access_code": {
      "access_code_id": "a7b85c1f-9963-4fa8-b106-7ce580a41256",
      "device_id": "6aae9d08-fed6-4ca5-8328-e36849ab48fe",
      "name": "my ongoing code",
      "appearance": {
        "name": "my ongoing code",
        "last_name": "ongoing code",
        "first_name": "my"
      },
      "code": "5048",
      "common_code_key": null,
      "type": "ongoing",
      "status": "set",
      "pulled_backup_access_code_id": null,
      "is_backup_access_code_available": true,
      "created_at": "2023-10-19T08:10:24.248Z",
      "errors": [...],
      "warnings": [...],
      "is_managed": true,
      "is_external_modification_allowed": true
    },
    "ok": true
  }
  ```

  ```json Python theme={null}
  'Errors:'
  [...]
  'Warnings:'
  [...]
  ```

  ```json Ruby theme={null}
  Errors:
  Warnings:
  ```

  ```json C# theme={null}
  Errors:
  []
  Warnings:
  []
  ```
</CodeGroup>

***

## Suggested Access Code Remedies

We recommend the following mitigations for various error codes:

| Error Code                                         | Recommended remedies                                                                                                                                                                                                                                                                                                                                                                                         |
| -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `failed_to_set_on_device`                          | Check the error message for more specific mitigation steps or use a [backup access code](/low-level-apis/smart-locks/access-codes/backup-access-codes)                                                                                                                                                                                                                                                       |
| `failed_to_remove_from_device`                     | Check the error message for more specific mitigation steps. Confirm using the provider's app if the access code is still on the device, as it may have been deleted through another source.                                                                                                                                                                                                                  |
| `code_modified_external_to_seam`                   | To resolve a conflict due to a Seam access code being modified or created by an external source, you can delete and re-create the code through Seam or convert the code from an unmanaged to managed access code (if it was created by an external source). By default, Seam will attempt to reset the code.                                                                                                 |
| `august_device_programming_delay`                  | Verify that the device has a stable internet connection (e.g. by attempting to lock and unlock the device through Seam) and troubleshoot any connectivity issues that may be causing intermittent or unreliable access to the device.                                                                                                                                                                        |
| `august_device_slots_full`                         | Delete existing access codes on the device to free up slots for new access codes. This should be done through Seam if possible.                                                                                                                                                                                                                                                                              |
| `august_lock_bad_access_code_format`               | Review the pin code and name requirements specific to your August device and update the access code on Seam to match these requirements.                                                                                                                                                                                                                                                                     |
| `august_lock_temporarily_offline`                  | Verify that the device has a stable internet connection (e.g. by attempting to lock and unlock the device through Seam) and troubleshoot any connectivity issues that may be causing intermittent or unreliable access to the device.                                                                                                                                                                        |
| `duplicate_code_on_device`                         | Check for [unmanaged access codes](/low-level-apis/smart-locks/access-codes/migrating-existing-access-codes) through the provider's app or Seam with the same pin code or name. If a duplicate is found, either delete the duplicate code or convert it to a managed code.                                                                                                                                   |
| `salto_site_user_not_subscribed`                   | Check the Salto user's subscription and your Salto site's subscription limit.                                                                                                                                                                                                                                                                                                                                |
| `smartthings_failed_to_set_after_multiple_retries` | Check for duplicate codes caused by third-party software managing the device. RBoy Apps in particular can cause this, so disable these for devices that are managed using Seam if possible.                                                                                                                                                                                                                  |
| `smartthings_no_free_slots_available`              | Delete existing access codes on the device to free up slots for new access codes. Note that in addition to the codes managed by Seam, there are 3 other codes on the device.                                                                                                                                                                                                                                 |
| `kwikset_unable_to_confirm_code`                   | This error is usually caused by a duplicate pin code on the device that was set outside of Seam. Try to update this access code's 'code' value through Seam Console or by using our [Update Access Code](/api/access_codes/update) endpoint                                                                                                                                                                  |
| `kwikset_unable_to_confirm_deletion`               | You can see a master list of access codes from the Kwikset mobile app (must be from a mobile device connected to the lock through Bluetooth). If the code is not in the list, it may have already been deleted by a source other than Seam. In this case, contact us, and we will remove our record of the access code. Otherwise, we will continue to attempt and confirm deletion of the code on the lock. |


# Get started with Smart Locks
Source: https://docs.seam.co/low-level-apis/smart-locks/get-started-with-smartlocks-api

Learn how to connect and control smartlocks with the Seam API.

## Overview

Seam is a simple API to connect and control almost any smartlocks. Seam already integrates popular smartlock brands such as [August](https://seam.co/manufacturers/august), [Yale](https://seam.co/manufacturers/yale), [Schlage](https://seam.co/manufacturers/schlage), [Igloo](https://www.seam.co/manufacturers/igloohome), and [Kwikset](https://www.seam.co/manufacturers/kwikset), as well as lesser known ones like [Nuki](https://www.seam.co/manufacturers/nuki), [Wyze](https://www.seam.co/manufacturers/wyze), or [TTLock](https://www.seam.co/manufacturers/ttlock).

The main benefit of Seam is that you can connect devices from these brands and control them with an easy to use API without having to worry about the underlying specific of each devices. Seam abstracts functions in [capabilities](/capability-guides/device-and-system-capabilities) such as `access_codes` or `locks` which you can use to integrate devices from multiple brands while expecting them to all behave more or less in the same way.

This guide is intended to show you how to connect and control smartlocks. To learn more about all devices supported by Seam such as thermostats and sensors, head over to our [integration page](https://www.seam.co/supported-devices-and-systems).

Let's get started.

## 1 — Install Seam SDK

Seam provides client libraries for many languages, such as JavaScript, Python, Ruby, PHP, and others, as well as a Postman collection and [OpenAPI](https://connect.getseam.com/openapi.json) spec.

* JavaScript / TypeScript ([npm](https://www.npmjs.com/package/seam), [GitHub](https://github.com/seamapi/javascript))
* Python ([pip](https://pypi.org/project/seam/), [GitHub](https://github.com/seamapi/python))
* Ruby Gem ([rubygem](https://rubygems.org/gems/seam), [GitHub](https://github.com/seamapi/ruby))
* PHP ([packagist](https://packagist.org/packages/seamapi/seam), [GitHub](https://github.com/seamapi/php))
* C# ([nuget](https://www.nuget.org/packages/Seam), [GitHub](https://github.com/seamapi/csharp))

<Tabs>
  <Tab title="JavaScript">
    ```bash theme={null}
    npm i seam
    ```
  </Tab>

  <Tab title="Python">
    ```bash theme={null}
    pip install seam
    # For some development environments, use pip3 in this command instead of pip.
    ```
  </Tab>

  <Tab title="Ruby">
    ```bash theme={null}
    bundle add seam
    ```
  </Tab>

  <Tab title="PHP">
    ```bash theme={null}
    composer require seamapi/seam
    ```
  </Tab>

  <Tab title="C#">
    Install using [nuget](https://www.nuget.org/packages/Seam).
  </Tab>
</Tabs>

Once installed, [sign-up for Seam](https://console.seam.co/) to get your API key, and export it as an environment variable:

```
$ export SEAM_API_KEY=seam_test2ZTo_0mEYQW2TvNDCxG5Atpj85Ffw
```

<Info>
  This guide uses a Sandbox Workspace. Only virtual devices can be connected. If
  you need to connect a real device, use a non-sandbox workspace and API key.
</Info>

## 2 — Link Your Smartlock Account with Seam

To control a smartlock via the Seam API, we need to first connect to your smartlock account and authorize your Seam workspace to control its device(s). To make this easy, Seam provides [Connect Webviews](/core-concepts/connect-webviews) authorization flows that walk you (or a device owner) through authorizing your workspace to control your device.

#### Request a Connect Webview

To start, we will create a Connect Webview and pass "stable" as the `provider_category`. This will ensure that only stable integrations are being presented.

<CodeGroup>
  ```javascript JavaScript theme={null}
  import { Seam } from 'seam'

  const seam = new Seam()

  const connectWebview = await seam.connectWebviews.create({
  provider_category: 'stable',
  })

  console.log(connectWebview.login_successful) // false

  // Send the webview URL to your user
  console.log(connectWebview.url)

  ```

  ```python Python theme={null}
  from seam import Seam

  seam = Seam()

  webview = seam.connect_webviews.create(provider_category="stable")

  assert webview.login_successful is False

  # Send the webview URL to your user
  print(webview.url)
  ```

  ```ruby Ruby theme={null}
  require "seam"

  seam = Seam.new(api_key: "MY_API_KEY")

  webview = seam.connect_webviews.create(
  provider_category: "stable"
  )

  puts webview.login_successful # false

  # Send the webview URL to your user

  puts webview.url

  ```

  ```php PHP theme={null}
  use Seam\SeamClient;

  $seam = new SeamClient("YOUR_API_KEY");

  $webview = $seam->connect_webviews->create(
    provider_category: "stable"
  );

  echo json_encode($webview)
  ```
</CodeGroup>

#### Authorize Your Workspace

Using a browser, navigate to the URL returned by the Connect Webview object. If you are in a sandbox workspace, you can select Yale as the provider and use the test login below to complete the process. If you have a non-sandbox workspace and a real device, simply use your account credentials.

Yale Test credentials:

* **email:** [jane@example.com](mailto:jane@example.com)
* **password:** 1234

Confirm the Connect Webview was successful by querying its status:

<CodeGroup>
  ```javascript JavaScript theme={null}
  const updatedWebview = await seam.connectWebviews.get(
    connectWebview.connect_webview_id,
  )

  console.log(updatedWebview.login_successful) // true

  ```

  ```python Python theme={null}
  updated_webview = seam.connect_webviews.get(connect_webview_id: webview.connect_webview_id)

  assert updated_webview.login_successful # true
  ```

  ```ruby Ruby theme={null}
  updated_webview = seam.connect_webviews.get(connect_webview_id: webview.connect_webview_id)

  puts updated_webview.login_successful # true

  ```

  ```php PHP theme={null}
  $webview = $seam->connect_webviews->get($webview->id);
  echo json_encode($webview);
  ```
</CodeGroup>

## 3 — Retrieve Smartlock Devices

After an account is linked with Seam, you can retrieve devices for this linked account. The Seam API exposes most of the device's properties such as battery level or door lock status.

<CodeGroup>
  ```javascript JavaScript theme={null}
  const allLocks = await seam.locks.list()

  const someLock = allLocks[0]

  console.log(someLock.properties.online) // true
  console.log(someLock.properties.locked) // true

  ```

  ```python Python theme={null}
  all_locks = seam.locks.list()

  some_lock = all_locks[0]

  assert some_lock.properties["online"] is True
  assert some_lock.properties["locked"] is True
  ```

  ```ruby Ruby theme={null}
  some_lock = seam.locks.list.first

  puts some_lock.properties.online # true
  puts some_lock.properties.locked # true

  ```

  ```php PHP theme={null}
  use Seam\SeamClient;

  $seam = new SeamClient('YOUR_API_KEY');

  $locks = $seam->locks->list();

  echo json_encode($locks);
  ```
</CodeGroup>

### 4 — Locking & Unlocking a Door

Next, you can perform the basic action of locking and unlocking the door as most devices will support the `locks` capability.

<mark>`POST`</mark> `undefined/locks/lock_door`

## Unlock a door

<mark>`POST`</mark>
`https://connect.getseam.com/locks/unlock_door`

#### Request Body

| Name       | Type   | Description |
| ---------- | ------ | ----------- |
| device\_id | String |             |

<CodeGroup>
  ```javascript JavaScript theme={null}
  // lock the door
  await seam.locks.lockDoor(someLock.device_id)
  const updatedLock = await seam.locks.get(someLock.device_id)
  console.log(updatedLock.properties.locked) // true

  // unlock the door
  await seam.locks.unlockDoor(someLock.device_id)
  updatedLock = await seam.locks.get(someLock.device_id)
  console.log(updatedLock.properties.locked) // false

  ```

  ```python Python theme={null}
  # lock the door
  seam.locks.lock_door(device_id: some_lock.device_id)
  updated_lock = seam.locks.get(device_id: some_lock.device_id)
  assert updated_lock.properties["locked"] is True

  # Now unlock the door
  seam.locks.unlock_door(device_id: some_lock.device_id)
  updated_lock = seam.locks.get(device_id: some_lock.device_id)
  assert updated_lock.properties["locked"] is False
  ```

  ```ruby Ruby theme={null}
  # lock the door
  seam.locks.lock_door(device_id: some_lock.device_id)
  updated_lock = seam.locks.get(device_id: some_lock.device_id)
  puts updated_lock.properties.locked # true

  # unlock the door

  seam.locks.unlock_door(device_id: some_lock.device_id)
  updated_lock = seam.locks.get(device_id: some_lock.device_id)
  puts updated_lock.properties.locked # false

  ```

  ```php PHP theme={null}
  use Seam\SeamClient;

  $seam = new SeamClient('YOUR_API_KEY');

  $some_lock = $seam->locks->list()[0];

  # unlock the door
  $seam->locks->unlock_door($lock->device_id);
  # lock the door
  $seam->locks->lock_door($lock->device_id);
  ```
</CodeGroup>

###

### 5 — Setting Access Code

Many smartlocks have a built-in keypad or an external one that can be paired over bluetooth. This lets you program access codes that a user can then enter at a later time to unlock a door.

The Seam API makes it easy to program both `ongoing` codes and `timebound` codes on a smartlock. An `ongoing` code is a code that will be permanently programmed onto the device until you tell the Seam API you wish to remove it. A `timebound` code is, as the time implies, time bound by a set of ISO8601 timestamp that you provide the Seam API. You can find out more about access code in our [core concept section on access codes.](/low-level-apis/smart-locks/access-codes)

<CodeGroup>
  ```javascript JavaScript theme={null}
  // create an ongoing code
  await seam.accessCodes.create({
    device_id: someLock.device_id,
    code: '123456',
    name: 'My Access Code',
  })

  // create a timebound code
  await seam.accessCodes.create({
  device_id: someLock.device_id,
  code: '888888',
  name: 'Scheduled Code',
  starts_at: '2028-11-12T19:23:42+0000',
  ends_at: '2028-11-13T19:23:42+0000',
  })

  // use a device_id as the "device_id" parameter
  await seam.accessCodes.list({
  device_id: someLock.device_id,
  })

  /_
  [
  {
  code: '1988',
  type: 'ongoing',
  status: 'setting',
  created_at: '2022-08-26T12:50:17.858Z',
  access_code_id: '26d6138c-6524-4f3c-ac96-43cc3bea0a8d'
  },
  {
  type: 'timebound',
  code: '888888',
  starts_at: '2028-08-12T19:24:00.000Z',
  ends_at: '2028-08-13T19:24:00.000Z',
  access_code_id: '8c2db4da-b137-4c08-a2c3-d611e6ff91b3',
  }
  ]
  _/

  ```

  ```python Python theme={null}
  # create an ongoing code
  seam.access_codes.create(
      device=some_lock, code="123456", name="My Access Code"
  )

  # create a timebound code
  seam.access_codes.create(
      device=some_lock,
      code="888888",
      name="Scheduled Code",
      starts_at="2028-08-12T19:23:42+0000",
      ends_at="2028-08-13T19:23:42+0000"
  )

  # you can use a device or a device_id as the "device" parameter
  seam.access_codes.list(device=some_lock)
  # [
  #   AccessCode(
  #     access_code_id='af5272b1-2a49-4eb5-9388-2447fc7b5bd1',
  #     type='ongoing',
  #     code='123459'
  #   ),
  #   AccessCode(
  #     access_code_id='8c2db4da-b137-4c08-a2c3-d611e6ff91b3',
  #     type='timebound',
  #     code='888888',
  #     starts_at='2028-08-12T19:24:00.000Z',
  #     ends_at='2028-08-13T19:24:00.000Z',
  #   )
  # ]

  ```

  ```ruby Ruby theme={null}
  # create an ongoing code
  seam.access_codes.create(
    device_id: some_lock.device_id, code: '123456', name: 'My Access Code'
  )

  # create a timebound code

  seam.access_codes.create(
  device_id: some_lock.device_id,
  code: '888888',
  name: 'Scheduled Code',
  starts_at: '2028-08-12T19:23:42+0000',
  ends_at: '2028-08-13T19:23:42+0000'
  )

  seam.access_codes.list(device_id: some_lock.device_id)

  # [<Seam::AccessCode:0x00730

  # code="888888"

  # name="Scheduled Code"

  # type="time_bound"

  # errors=[]

  # warnings=[]

  # access_code_id="ce2c298c-364f-4b13-aa12-712f3976288e"

  # ends_at=2028-08-13 19:24:00 UTC

  # starts_at=2028-08-12 19:24:00 UTC>, <Seam::AccessCode:0x00758

  # code="123456"

  # name="My Access Code"

  # type="ongoing"

  # errors=[]

  # warnings=[]

  # access_code_id="75f49550-fc9b-481a-a158-5bc53ac9bb34">, <Seam::AccessCode:0x00780

  # code="086355"

  # name="some-code2"

  # type="ongoing"

  # errors=[]

  # warnings=[]

  # access_code_id="5243e5f3-528a-4378-ba3c-21447bf844a8">, <Seam::AccessCode:0x007a8

  # code="376525"

  # name="some-code"

  # type="ongoing"

  # errors=[]

  # warnings=[]

  # access_code_id="91a08a3d-a0bb-4ff0-bfb4-ced164353988">]

  ```

  ```php PHP theme={null}
  use Seam\SeamClient;

  $seam = new SeamClient("YOUR_API_KEY");

  $some_lock = $seam->locks->list()[0];
  $seam->access_codes->create(
    device_id: $some_lock->device_id, code: '123456', name: 'My Access Code'
  );

  $seam->access_codes->create(
    device_id: $some_lock->device_id,
    name: 'Scheduled Code',
    code: '888888',
    starts_at: '2028-08-12T19:23:42+0000',
    ends_at: '2028-08-13T19:23:42+0000'
  );

  ```
</CodeGroup>

## Next Steps

Now that you've completed this guide, you can try to build a real application to connect and control a device. Don't hesitate to reach out to our team if we can help with anything, or explore other aspects of Seam, here is a list of helpful resources:

* [Yale Getting Started Guide](/device-and-system-integration-guides/yale-locks/get-started-with-yale-locks)
* [August Getting Started Guide](/device-and-system-integration-guides/august-locks/get-started-with-august-locks)
* [Schlage Getting Started Guide](/device-and-system-integration-guides/schlage-locks/get-started-with-schlage-locks)
* [SmartThings Getting Started Guide](/device-and-system-integration-guides/smartthings-hubs-+-devices/get-started-with-smartthings-hubs-+-smart-locks)
* [Receiving webhook](/developer-tools/webhooks) for [device events](/api/events/list)
* [Core Concepts](/core-concepts/overview)


# Smart Locks
Source: https://docs.seam.co/low-level-apis/smart-locks/index

Learn about managing smart locks and access codes that enable you to lock and unlock doors and other entry points.

<Warning>
  This is a low-level API. For granting access to smart locks, use [Access
  Grants](/use-cases/granting-access/index)—the default and recommended way to grant
  access to any physical space. We don't recommend building on the Smart Locks
  API directly unless you've discussed your use case with the Seam team at
  [support@seam.co](mailto:support@seam.co).
</Warning>

<iframe title="YouTube video" />

The Seam API enables you to control connected smart locks from a wide variety of manufacturers, including locks that provide online and offline access code programming. For example, you can use the Seam API to implement the following common scenarios:

* **Shareable Web Pass:** Create a web pass to distribute to guests or visitors. When this pass is used, it can lock or unlock the smart lock.
* **Scheduled Access:** Grant time-bound access by providing temporary codes to guests, babysitters, or service personnel. For example, a cleaner with a schedule from 10 am to 12 pm on Tuesdays could be given a code valid only within that time frame.
* **Security Monitoring:** Get real-time status updates on when the door is locked or unlocked.

## What Is a Smart Lock?

Smart locks utilize technology to provide a new way to unlock or lock your door. With smart locks, you can access your premises without a physical key.

These locks can be integrated into various entry points, such as standard doors, gates, garage doors, elevators, and lockers. Some associated devices, such as intercoms and access control systems, come equipped with built-in video cameras and microphones. This way, you can see and communicate with whomever is at your door, even when you're away from the location.

The Seam API provides the capability to lock and unlock doors remotely. You can use capability flags to check whether your lock has the `device.can_remotely_lock` or `device.can_remotely_unlock` capability. For more information, see [Capability Flags](../../capability-guides/device-and-system-capabilities#capability-flags).

For locks equipped with keypads, our API also permits the creation and programming of access codes. Additional capability flags enable you to check whether your lock has the `device.can_program_online_access_codes` or `device.can_program_offline_access_codes` capability. For more information, see [Capability Flags](../../capability-guides/device-and-system-capabilities#capability-flags).

## What Is an Access Code?

An access code is a numeric or alphanumeric code that a user enters to gain access through the lock. Here's how it works:

* The smart lock owner sets a specific code for the lock.
* When the correct code is entered on the keypad, the lock releases and allows access.
* Access codes can be permanent (for homeowners or primary users) or temporary (for guests or service providers).

You can use capability flags to check whether your lock has the `device.can_program_online_access_codes` or `device.can_program_offline_access_codes` capability. For more information, see [Capability Flags](../../capability-guides/device-and-system-capabilities#capability-flags).

## **Next Steps**

To learn how to manage locks and access codes, see the following guides:

* [Locking and Unlocking](/low-level-apis/smart-locks/lock-and-unlock)
* [Managing Access Codes](/low-level-apis/smart-locks/access-codes/index)

For the corresponding Seam API references, see [Locks](/api/locks/object) and [Access Codes](/api/access_codes/object).


# Locking and Unlocking Smart Locks
Source: https://docs.seam.co/low-level-apis/smart-locks/lock-and-unlock

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](../../core-concepts/action-attempts), 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](/api/action_attempts/get). Once Seam has successfully confirmed the action, the action attempt's `status` will indicate `success`.

Some providers and device models cannot confirm whether the physical lock or unlock happened in a reasonable time or at all. In those cases, a successful action attempt can still include `action_attempt.result.was_confirmed_by_device = false`.

***

## 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](../../capability-guides/device-and-system-capabilities#capability-flags) for the device:

* `device.can_remotely_lock`
* `device.can_remotely_unlock`

Use [Get Device](/api/devices/get) 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](/api/devices/object) of the device, [errors or warnings](/api/devices/errors) for the device, and [events](/api/devices/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.

**Request:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  await seam.devices.get('11111111-1111-1111-1111-444444444444')
  ```

  ```bash cURL theme={null}
  # Use GET or POST.
  curl -X 'GET' \
    'https://connect.getseam.com/devices/get' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d '{
    "device_id": "11111111-1111-1111-1111-444444444444"
  }'
  ```

  ```python Python theme={null}
  seam.devices.get(device_id="11111111-1111-1111-1111-444444444444")
  ```

  ```ruby Ruby theme={null}
  client.devices.get(device_id: "11111111-1111-1111-1111-444444444444")
  ```

  ```php PHP theme={null}
  $seam->devices->get("11111111-1111-1111-1111-444444444444");
  ```

  ```csharp C# theme={null}
  seam.Devices.Get(deviceId: "11111111-1111-1111-1111-444444444444");
  ```
</CodeGroup>

**Response:**

<CodeGroup>
  ```json JavaScript theme={null}
  {
    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.
    ...
  }
  ```

  ```json cURL theme={null}
  {
    "device": {
      "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
  }
  ```

  ```json Python theme={null}
  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.
    ...
  )
  ```

  ```json Ruby theme={null}
  <
    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.
      ...
  >
  ```

  ```json PHP theme={null}
  {
    "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.
    ...
  }
  ```

  ```json C# theme={null}
  {
    "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.
    ...
  }
  ```
</CodeGroup>

***

## Locking a Door

You can lock a door using the [`lock_door`](/api/locks/lock_door) endpoint. To confirm the success of the action, see [Verifying the success of a lock or unlock action](#verifying-the-success-of-a-lock-or-unlock-action).

**Request:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  // Get the device.
  const device = await seam.devices.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,
    })
  }
  ```

  ```bash cURL theme={null}
  # Get the device.
  device=$(
    # Use GET or POST.
    curl -X 'GET' \
      'https://connect.getseam.com/devices/get' \
      -H 'accept: application/json' \
      -H "Authorization: Bearer ${SEAM_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 ${SEAM_API_KEY}" \
      -H 'Content-Type: application/json' \
      -d "{
        \"device_id\": \"$(jq -r '.device.device_id' <<< ${device})\"
    }";
  fi
  ```

  ```python Python theme={null}
  # Get the device.
  device = seam.devices.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)
  ```

  ```ruby Ruby theme={null}
  # Get the device.
  device = client.devices.get(device_id: "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_id: device.device_id)
  end
  ```

  ```php PHP theme={null}
  // Get the device.
  $device = $seam->devices->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);
  }
  ```

  ```csharp C# theme={null}
  // Get the device.
  Device device = seam.Devices.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);
  }
  ```
</CodeGroup>

**Response:**

<CodeGroup>
  ```json JavaScript theme={null}
  {
    "actionAttempt": {
      "status": "success",
      "action_attempt_id": "11111111-2222-3333-4444-555555555555",
      "action_type": "LOCK_DOOR",
      "result": {},
      "error": null
    }
  }
  ```

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

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

  ```json Ruby theme={null}
  <Seam::ActionAttempt:0x00438
    status="pending"
    action_type="LOCK_DOOR"
    action_attempt_id="11111111-2222-3333-4444-555555555555"
    result=nil>
  ```

  ```json PHP theme={null}
  {
    "action_attempt_id": "11111111-2222-3333-4444-555555555555",
    "action_type": "LOCK_DOOR",
    "error": null,
    "result": {},
    "status": "success"
  }
  ```

  ```json C# theme={null}
  {
    "status": "pending",
    "action_type": "LOCK_DOOR",
    "action_attempt_id": "11111111-2222-3333-4444-555555555555"
  }
  ```
</CodeGroup>

***

## Unlocking a Door

You can unlock a door using the [unlock\_door](/api/locks/unlock_door) endpoint. To confirm the success of the action, see [Verifying the success of a lock or unlock action](#verifying-the-success-of-a-lock-or-unlock-action).

**Request:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  // Get the device.
  const device = await seam.devices.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,
    })
  }
  ```

  ```bash cURL theme={null}
  # Get the device.
  device=$(
    # Use GET or POST.
    curl -X 'GET' \
      'https://connect.getseam.com/devices/get' \
      -H 'accept: application/json' \
      -H "Authorization: Bearer ${SEAM_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_unlock' <<< ${device}); then \
    # Perform the unlock operation.
    curl -X 'POST' \
      'https://connect.getseam.com/locks/unlock_door' \
      -H 'accept: application/json' \
      -H "Authorization: Bearer ${SEAM_API_KEY}" \
      -H 'Content-Type: application/json' \
      -d "{
        \"device_id\": \"$(jq -r '.device.device_id' <<< ${device})\"
    }";
  fi
  ```

  ```python Python theme={null}
  # Get the device.
  device = seam.devices.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)
  ```

  ```ruby Ruby theme={null}
  # Get the device.
  device = client.devices.get(device_id: "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_id: device.device_id)
  end
  ```

  ```php PHP theme={null}
  // Get the device.
  $device = $seam->devices->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);
  }
  ```

  ```csharp C# theme={null}
  // Get the device.
  Device device = seam.Devices.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);
  }
  ```
</CodeGroup>

**Response:**

<CodeGroup>
  ```json JavaScript theme={null}
  {
    "actionAttempt": {
      "status": "success",
      "action_attempt_id": "11111111-2222-3333-4444-555555555555",
      "action_type": "UNLOCK_DOOR",
      "result": {
        "was_confirmed_by_device": false
      },
      "error": null
    }
  }
  ```

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

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

  ```json Ruby theme={null}
  <Seam::ActionAttempt:0x00438
    status="pending"
    action_type="UNLOCK_DOOR"
    action_attempt_id="11111111-2222-3333-4444-555555555555"
    result=nil>
  ```

  ```json PHP theme={null}
  {
    "action_attempt_id": "11111111-2222-3333-4444-555555555555",
    "action_type": "UNLOCK_DOOR",
    "error": null,
    "result": {
      "was_confirmed_by_device": false
    },
    "status": "success"
  }
  ```

  ```json C# theme={null}
  {
    "status": "pending",
    "action_type": "UNLOCK_DOOR",
    "action_attempt_id": "11111111-2222-3333-4444-555555555555"
  }
  ```
</CodeGroup>

***

## 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.

**Request:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  await seam.locks.lockDoor({
    device_id: '11111111-1111-1111-1111-444444444444',
  })
  ```

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

  ```python Python theme={null}
  seam.locks.lock_door(device_id="11111111-1111-1111-1111-444444444444")
  ```

  ```ruby Ruby theme={null}
  client.locks.lock_door(device_id: "11111111-1111-1111-1111-444444444444")
  ```

  ```php PHP theme={null}
  $seam->locks->lock_door(device_id: "11111111-1111-1111-1111-444444444444");
  ```

  ```csharp C# theme={null}
  seam.Locks.LockDoor(deviceId: "11111111-1111-1111-1111-444444444444");
  ```
</CodeGroup>

**Response:**

<CodeGroup>
  ```json JavaScript theme={null}
  {
    "actionAttempt": {
      "status": "success",
      "action_attempt_id": "11111111-2222-3333-4444-555555555555",
      "action_type": "LOCK_DOOR",
      "result": {},
      "error": null
    }
  }
  ```

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

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

  ```json Ruby theme={null}
  <Seam::ActionAttempt:0x00438
    status="pending"
    action_type="LOCK_DOOR"
    action_attempt_id="11111111-2222-3333-4444-555555555555"
    result=nil>
  ```

  ```json PHP theme={null}
  {
    "action_attempt_id": "11111111-2222-3333-4444-555555555555",
    "action_type": "LOCK_DOOR",
    "error": null,
    "result": {},
    "status": "success"
  }
  ```

  ```json C# theme={null}
  {
    "status": "pending",
    "action_type": "LOCK_DOOR",
    "action_attempt_id": "11111111-2222-3333-4444-555555555555"
  }
  ```
</CodeGroup>

### 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](/api/action_attempts/get). When the action attempt's `status` changes to `success`, it indicates the action has been successful.

<Info>
  Some providers and device models do not confirm whether a lock or unlock
  completed on the physical device. In those cases, the action attempt can still
  succeed while `action_attempt.result.was_confirmed_by_device` is `false`. Use
  this property to set the right expectation in your UI, especially for unlock
  flows.
</Info>

**Request:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  await seam.actionAttempts.get({
    action_attempt_id: '11111111-2222-3333-4444-555555555555',
  })
  ```

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

  ```python Python theme={null}
  seam.action_attempts.get(action_attempt_id="11111111-2222-3333-4444-555555555555")
  ```

  ```ruby Ruby theme={null}
  client.action_attempts.get(action_attempt_id: "11111111-2222-3333-4444-555555555555")
  ```

  ```php PHP theme={null}
  $seam->action_attempts->get(action_attempt_id: "11111111-2222-3333-4444-555555555555");
  ```

  ```csharp C# theme={null}
  seam.ActionAttempts.Get("11111111-2222-3333-4444-555555555555");
  ```
</CodeGroup>

**Response:**

<CodeGroup>
  ```json JavaScript theme={null}
  {
    "status": "success",
    "action_attempt_id": "11111111-2222-3333-4444-555555555555",
    "action_type": "LOCK_DOOR",
    "result": {
      "was_confirmed_by_device": true
    },
    "error": null
  }
  ```

  ```json cURL theme={null}
  {
    "action_attempt": {
      "status": "success",
      "action_attempt_id": "11111111-2222-3333-4444-555555555555",
      "action_type": "LOCK_DOOR",
      "result": {
        "was_confirmed_by_device": true
      },
      "error": null
    },
    "ok": true
  }
  ```

  ```json Python theme={null}
  ActionAttempt(action_attempt_id='11111111-2222-3333-4444-555555555555',
                action_type='LOCK_DOOR',
                status='success',
                result={'was_confirmed_by_device': True},
                error=None)
  ```

  ```json Ruby theme={null}
  <Seam::ActionAttempt:0x00438
    status="success"
    action_attempt_id="11111111-2222-3333-4444-555555555555"
    action_type="LOCK_DOOR"
    result={"was_confirmed_by_device"=>true}>
  ```

  ```json PHP theme={null}
  {
    "action_attempt_id": "11111111-2222-3333-4444-555555555555",
    "action_type": "LOCK_DOOR",
    "error": null,
    "result": {
      "was_confirmed_by_device": true
    },
    "status": "success"
  }
  ```

  ```json C# theme={null}
  {
    "status": "success",
    "action_type": "LOCK_DOOR",
    "action_attempt_id": "11111111-2222-3333-4444-555555555555",
    "result": {
      "was_confirmed_by_device": true
    },
    "error": null
  }
  ```
</CodeGroup>

***

## Checking the Locked Status of a Lock

To retrieve the locked status of a specific door lock, use the [Get Device](/api/devices/get) endpoint by providing the `device_id` of the desired lock. This operation returns detailed information, including the current locked status. Note that if the lock is offline, Seam does not return the `device.locked` property.

**Request:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  await seam.devices.get('11111111-1111-1111-1111-444444444444')
  ```

  ```bash cURL theme={null}
  # Use GET or POST.
  curl -X 'GET' \
    'https://connect.getseam.com/devices/get' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d '{
    "device_id": "11111111-1111-1111-1111-444444444444"
  }'
  ```

  ```python Python theme={null}
  seam.devices.get(device_id="11111111-1111-1111-1111-444444444444")
  ```

  ```ruby Ruby theme={null}
  client.devices.get(device_id: "11111111-1111-1111-1111-444444444444")
  ```

  ```php PHP theme={null}
  $seam->devices->get("11111111-1111-1111-1111-444444444444");
  ```

  ```csharp C# theme={null}
  seam.Devices.Get("11111111-1111-1111-1111-444444444444");
  ```
</CodeGroup>

**Response:**

<CodeGroup>
  ```json JavaScript theme={null}
  {
    device_id: '11111111-1111-1111-1111-444444444444',
    properties: {
      locked: true,
      ...
    },
    ...
  }
  ```

  ```json cURL theme={null}
  {
    "lock": {
      "device_id": "11111111-1111-1111-1111-444444444444",
      "properties": {
        "locked": true,
        ...
      },
      ...
    },
    "ok": true
  }
  ```

  ```json Python theme={null}
  Device(
    device_id='11111111-1111-1111-1111-444444444444',
    properties={
      'locked': True,
      ...
    },
    ...
  )
  ```

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

  ```json PHP theme={null}
  {
    "device_id": "11111111-1111-1111-1111-444444444444",
    "properties": {
      "locked": true,
      ...
    },
    ...
  }
  ```

  ```json C# theme={null}
  {
    "device_id": "11111111-1111-1111-1111-444444444444",
    "properties": {
      "locked": true,
      ...
    },
    ...
  }
  ```
</CodeGroup>

***

## Lock and Unlock Events

Whenever a lock is locked or unlocked, Seam emits a `lock.locked` or `lock.unlocked` event. You can retrieve these events by making a [List Events request](/api/events/list) or receive them in real time by setting up a webhook. For more information on how to set up webhooks, see the [Webhooks guide](../../developer-tools/webhooks). For the complete list of properties on each event, see the [Lock Events reference](/api/locks/events).

A `lock.unlocked` event looks like the following:

```json theme={null}
{
  "event_id": "22222222-3333-4444-5555-666666666666",
  "event_type": "lock.unlocked",
  "device_id": "11111111-1111-1111-1111-444444444444",
  "method": "keycode",
  "access_code_id": "99999999-9999-9999-9999-999999999999",
  "access_code_is_managed": true,
  "occurred_at": "2025-01-01T00:00:00.000Z",
  "created_at": "2025-01-01T00:00:00.000Z",
  "workspace_id": "00000000-0000-0000-0000-000000000000"
}
```

### Determining How a Lock Was Operated

Use the `method` property to determine how the lock was locked or unlocked. Both `lock.locked` and `lock.unlocked` events include this property.

| `method`    | Meaning                                                                                               | Related properties                                    |
| ----------- | ----------------------------------------------------------------------------------------------------- | ----------------------------------------------------- |
| `keycode`   | An access code was entered on the keypad.                                                             | `access_code_id`, `access_code_is_managed`            |
| `manual`    | A direct physical action at the lock, such as turning the thumbturn or pressing a button.             | —                                                     |
| `remote`    | A remote action initiated from an app, over Bluetooth, or through the Seam API.                       | `action_attempt_id`, `is_via_bluetooth`, `is_via_nfc` |
| `automatic` | Triggered automatically, without user interaction—for example, by an auto-relock timer or a schedule. | —                                                     |
| `unknown`   | Seam could not determine the method from the provider's event.                                        | —                                                     |

For `remote` events, the following properties tell you which remote channel was used:

* **`action_attempt_id`**: Present only when the action was initiated through Seam, using a `LOCK_DOOR` or `UNLOCK_DOOR` [action attempt](../../core-concepts/action-attempts). Use it to tie the event back to the specific API call your application made. When this property is absent, the remote action originated outside of Seam—for example, from the provider's own mobile app.
* **`is_via_bluetooth`**: `true` when the action was performed over Bluetooth by a remote client, such as the provider's [mobile app](/low-level-apis/smart-locks/access-codes/accommodating-manufacturer-mobile-apps), rather than through Seam or a physical interaction.
* **`is_via_nfc`**: `true` when the action was performed by tapping an NFC credential, such as an Apple Home Key or an NFC key fob, at the lock.

### Identifying the Access Code Used

When `method` is `keycode`, the event identifies the [access code](/low-level-apis/smart-locks/access-codes) that was used:

* **`access_code_id`**: ID of the access code that was entered.
* **`access_code_is_managed`**: `true` if the code is managed by Seam—that is, one that you created through the Seam API—or `false` if it is an unmanaged code that was programmed directly on the device. This property is present only when `access_code_id` is set.

### Common Scenarios

The following examples show the properties that distinguish common ways a lock is operated. Each event also includes the standard `event_id`, `device_id`, `occurred_at`, and other envelope properties, omitted here for brevity.

<CodeGroup>
  ```json A guest enters a Seam-managed code theme={null}
  {
    "event_type": "lock.unlocked",
    "method": "keycode",
    "access_code_id": "99999999-9999-9999-9999-999999999999",
    "access_code_is_managed": true
  }
  ```

  ```json Your app unlocks via the Seam API theme={null}
  {
    "event_type": "lock.unlocked",
    "method": "remote",
    "action_attempt_id": "11111111-2222-3333-4444-555555555555"
  }
  ```

  ```json A resident unlocks with the provider's app over Bluetooth theme={null}
  {
    "event_type": "lock.unlocked",
    "method": "remote",
    "is_via_bluetooth": true
  }
  ```

  ```json Someone taps an Apple Home Key theme={null}
  {
    "event_type": "lock.unlocked",
    "method": "remote",
    "is_via_nfc": true
  }
  ```

  ```json The door auto-relocks on a timer theme={null}
  {
    "event_type": "lock.locked",
    "method": "automatic"
  }
  ```
</CodeGroup>


# Architecture
Source: https://docs.seam.co/mobile-sdks/android/architecture

A high-level view of how the Seam Android SDK integrates with your app, Seam Cloud services, and lock hardware — including StateFlows, coroutines, offline caching, and the SDK lifecycle.

## System Components

The Seam Android SDK connects four main components:

* **Mobile App** — Your Android application, written in Kotlin, that calls the Seam SDK.
* **SeamSDK** — A native library responsible for credential management, unlock flows, and reactive state emission.
* **Seam Cloud API** — The cloud service that provisions credentials, handles revocation, and synchronizes state.
* **Lock Hardware** — Physical locks that communicate over Bluetooth Low Energy (BLE) and/or NFC.

```
Mobile App  ──SDK Calls──▶  Seam SDK  ──HTTPS──▶  Seam Cloud API
                               │                        │
                            BLE/NFC              Push / Sync Events
                               │                        │
                               ▼                        ▼
                          Lock Hardware          SeamSDK (state update)
```

***

## Reactive State with StateFlow

The SDK exposes its state through three `StateFlow` properties. Because `StateFlow` is a hot stream, your UI always has access to the latest value via `.value`, and you can collect emissions reactively using Kotlin coroutines.

| Property       | Type                              | Description                                                                                           |
| -------------- | --------------------------------- | ----------------------------------------------------------------------------------------------------- |
| `credentials`  | `StateFlow<List<SeamCredential>>` | Current list of access credentials. Emits on every change, including credential sync from the server. |
| `isActivated`  | `StateFlow<Boolean>`              | `true` after a successful `activate()` call; `false` after `deactivate()`.                            |
| `unlockStatus` | `StateFlow<UnlockEvent>`          | Emits progress events during an unlock operation. The latest event is always accessible via `.value`. |

### Collecting StateFlows

All three StateFlows are thread-safe and can be collected from any coroutine context. When collecting in an Activity or Fragment, use `repeatOnLifecycle` to automatically cancel collection when the view is not in the foreground:

```kotlin theme={null}
lifecycleScope.launch {
    repeatOnLifecycle(Lifecycle.State.STARTED) {
        SeamSDK.getInstance().credentials.collect { credentials ->
            updateCredentialListUI(credentials)
        }
    }
}
```

StateFlows survive configuration changes (for example, screen rotation) when collected through a `ViewModel`, making them a natural fit for Android's architecture components.

***

## Coroutines and Suspend Functions

The SDK's mutating operations are Kotlin `suspend` functions — they are non-blocking and safe to call from any coroutine context without additional threading configuration:

| Function                                                 | Suspend? | Notes                                                                                       |
| -------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------- |
| `SeamSDK.initialize(context, clientSessionToken)`        | Yes      | Call once, typically in `Application.onCreate()`. Thread-safe and idempotent.               |
| `seamSDK.activate()`                                     | Yes      | Requires internet on first call. Safe to call multiple times.                               |
| `seamSDK.deactivate(deintegrate)`                        | Yes      | Stops background operations; does not clear cached credentials unless `deintegrate = true`. |
| `seamSDK.refresh()`                                      | Yes      | Manually syncs credentials; `credentials` StateFlow updates before the call returns.        |
| `seamSDK.unlock(credentialId, unlockProximity, timeout)` | No       | Returns a `Job`. Subscribe to `unlockStatus` before calling.                                |
| `SeamSDK.getInstance()`                                  | No       | Returns the initialized instance. Throws if `initialize` was not called.                    |

<Note>
  `unlock()` is not a suspend function — it launches a background `Job` and emits progress via `unlockStatus`. Start collecting `unlockStatus` **before** calling `unlock()` to ensure you receive all events from the start of the operation.
</Note>

***

## Offline Caching

The SDK caches credentials locally so that unlock operations remain available even without an active network connection.

| Operation               | Requires Internet | Notes                                                                             |
| ----------------------- | ----------------- | --------------------------------------------------------------------------------- |
| `activate()`            | Yes (first call)  | Subsequent calls may succeed from cache if already activated.                     |
| `refresh()`             | Yes               | Always fetches from the server.                                                   |
| `unlock()`              | No (if cached)    | Uses locally cached credentials. BLE/NFC communication goes directly to the lock. |
| `credentials` StateFlow | No                | Always emits the last-known list, including while offline.                        |

When the app comes back online, the SDK automatically re-syncs credentials in the background. Your UI observing `credentials` will receive updated values without any manual intervention.

***

## SDK Lifecycle

The SDK's lifecycle maps naturally onto the Android application lifecycle:

<Steps>
  <Step title="Initialize (once per installation / sign-in)">
    Call `SeamSDK.initialize(context, clientSessionToken)` in `Application.onCreate()` or immediately after the user signs in. Initialization is idempotent — calling it again with the same token is a no-op. To re-initialize with a new token (for example, after a sign-out and sign-in), call `deactivate(deintegrate = true)` first.

    ```kotlin theme={null}
    class MyApplication : Application() {
        override fun onCreate() {
            super.onCreate()
            // Launch a coroutine from an application-scoped scope
            applicationScope.launch {
                try {
                    SeamSDK.initialize(this@MyApplication, userClientSessionToken)
                } catch (e: SeamError.AlreadyInitialized) {
                    // Safe to ignore if already initialized for this session
                }
            }
        }
    }
    ```
  </Step>

  <Step title="Activate (when the user opens the credential / lock screen)">
    Call `activate()` to start syncing credentials and background services. This is typically done when the user navigates to the part of your app that manages access credentials. The SDK is safe to activate multiple times.

    ```kotlin theme={null}
    viewModelScope.launch {
        SeamSDK.getInstance().activate()
    }
    ```
  </Step>

  <Step title="Use credentials and unlock">
    Observe the `credentials` StateFlow to display the user's keys and call `unlock()` when the user taps an unlock button. See the [Quickstart](/mobile-sdks/android/quickstart) for a complete example.
  </Step>

  <Step title="Deactivate (optional, on sign-out)">
    Call `deactivate()` to stop background operations while preserving the credential cache. Pass `deintegrate = true` to also remove the device association and clear all cached state — use this path when the user signs out.

    ```kotlin theme={null}
    viewModelScope.launch {
        // Sign-out path: full teardown
        SeamSDK.getInstance().deactivate(deintegrate = true)
    }
    ```
  </Step>
</Steps>

***

## Key Data Types

| Type                           | Description                                                                                                                                                               |
| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Client Session Token (CST)** | A short-lived token used to authenticate SDK API calls. Obtained from your server via the Seam API after the user signs in.                                               |
| **`SeamCredential`**           | An immutable snapshot of a single access credential, with `id`, `name`, `location`, `expiry`, and an `errors` list. Observe the `credentials` StateFlow for live updates. |
| **`SeamUnlockEvent`**          | A sealed class describing each stage of an unlock operation (`ScanningStarted`, `AccessGranted`, `Timeout`, and `ReaderError`).                                           |
| **`SeamError`**                | A sealed class for SDK setup and API-level failures. See [Error Handling](/mobile-sdks/android/error-handling).                                                           |
| **`SeamCredentialError`**      | Returned in `SeamCredential.errors` when a specific credential has an issue (for example, expired, loading, or user interaction required).                                |

***

## Security and Storage

* **Secure Transport** — All Seam Cloud API calls use HTTPS. Lock communication is secured by the lock vendor's protocol over BLE/NFC.
* **Encrypted Storage** — Tokens and credentials are stored using Android's secure storage mechanisms. Do not cache CSTs in plaintext in your own code.
* **Credential Isolation** — Credentials are scoped to the initialized client session token. Calling `deactivate(deintegrate = true)` wipes all locally cached state.

***

## See Also

* [Quickstart](/mobile-sdks/android/quickstart) — Initialize the SDK and perform your first unlock.
* [Error Handling](/mobile-sdks/android/error-handling) — How to handle `SeamError` and credential errors.
* [API Reference](/mobile-sdks/android/reference/index) — Full API reference for all public types.


# Error Handling
Source: https://docs.seam.co/mobile-sdks/android/error-handling

Interpret and handle errors thrown by the Seam Android SDK, including SDK-level errors (SeamError), credential-specific errors (SeamCredentialError), and required user interactions.

## Overview

Errors in the Seam Android SDK fall into two categories:

* **`SeamError`** — Thrown by SDK operations such as `initialize()`, `activate()`, `deactivate()`, `refresh()`, and `unlock()`. These represent SDK setup, configuration, or API-level failures.
* **`SeamCredentialError`** — Stored in `SeamCredential.errors`. These represent issues with a specific credential that must be resolved before it can be used for an unlock.

Handling both types ensures your app can present clear, actionable guidance to users.

***

## SeamError

`SeamError` is a sealed class. Each subtype maps to a specific failure mode:

| Subtype                                | Thrown by                                              | Description                                                                                                                                                                        |
| -------------------------------------- | ------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `SeamError.AlreadyInitialized`         | `initialize()`                                         | The SDK is already initialized. Call `deactivate(deintegrate = true)` before re-initializing with a new token.                                                                     |
| `SeamError.InitializationRequired`     | `getInstance()`, `activate()`, `refresh()`, `unlock()` | The SDK has not been initialized; call `SeamSDK.initialize()` first.                                                                                                               |
| `SeamError.InvalidClientSessionToken`  | `initialize()`, `activate()`                           | The client session token is malformed or has expired. Obtain a fresh token from your server.                                                                                       |
| `SeamError.InternetConnectionRequired` | `initialize()`, `activate()`, `refresh()`              | A network connection is required for this operation.                                                                                                                               |
| `SeamError.DeactivationInProgress`     | `initialize()`, `refresh()`, `deactivate()`            | A deactivation is already running; wait for it to complete before retrying.                                                                                                        |
| `SeamError.ActivationRequired`         | `unlock()`                                             | The SDK has not been activated; call `activate()` first.                                                                                                                           |
| `SeamError.InvalidCredentialId`        | `unlock()`                                             | No credential matches the specified ID. Verify the credential ID against `credentials.value`.                                                                                      |
| `SeamError.IntegrationNotFound`        | `unlock()`                                             | No provider integration was found for this credential. Ensure you added the correct provider module (for example, `seam-phone-sdk-android-assaabloy`) in your Gradle dependencies. |
| `SeamError.CredentialErrors`           | `unlock()`                                             | The credential has unresolved errors. Inspect `e.errors` (a `List<SeamCredentialError>`) and resolve them before retrying the unlock.                                              |
| `SeamError.InvalidUnlockProximity`     | `unlock()`                                             | The specified `UnlockProximity` is not supported by this credential.                                                                                                               |

### Handling SeamError in code

```kotlin theme={null}
try {
    SeamSDK.getInstance().activate()
} catch (e: SeamError) {
    when (e) {
        is SeamError.InitializationRequired     -> showError("SDK not initialized. Please restart the app.")
        is SeamError.InternetConnectionRequired -> showError("No internet connection.")
        is SeamError.InvalidClientSessionToken  -> promptReSignIn()
        is SeamError.DeactivationInProgress     -> { /* Retry after a short delay */ }
        else                                    -> showError("Unexpected error: ${e.message}")
    }
}
```

***

## SeamCredentialError

`SeamCredentialError` is a sealed class stored in `SeamCredential.errors`. A credential may have zero or more errors simultaneously. Check `errors` before calling `unlock()`:

| Subtype                                                    | Description                                                                                                                                    |
| ---------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `SeamCredentialError.Loading`                              | The credential is still being provisioned. Wait for the `credentials` StateFlow to emit an updated list where this error is no longer present. |
| `SeamCredentialError.Expired`                              | The credential has expired. Contact the credential issuer or administrator to reissue it.                                                      |
| `SeamCredentialError.UserInteractionRequired(interaction)` | The user must take a specific action before this credential can be used. Inspect the `interaction` property.                                   |
| `SeamCredentialError.Unknown`                              | An unclassified error occurred. Retry or contact Seam support.                                                                                 |

### Checking credential errors before unlock

```kotlin theme={null}
val credential = SeamSDK.getInstance().credentials.value
    .firstOrNull { it.id == targetCredentialId }
    ?: return showError("Credential not found")

if (credential.errors.isNotEmpty()) {
    credential.errors.forEach { error ->
        when (error) {
            is SeamCredentialError.Loading -> {
                showStatus("Credential is loading, please wait...")
            }
            is SeamCredentialError.Expired -> {
                showError("This credential has expired. Contact your administrator.")
            }
            is SeamCredentialError.UserInteractionRequired -> {
                handleUserInteraction(error.interaction)
            }
            is SeamCredentialError.Unknown -> {
                showError("An unexpected error occurred. Please try again.")
            }
        }
    }
} else {
    // Credential is ready — proceed with unlock
    val credentialId = credential.id ?: return showError("Credential has no ID.")
    performUnlock(credentialId)
}
```

***

## SeamRequiredUserInteraction

When a credential has a `SeamCredentialError.UserInteractionRequired` error, the `interaction` property tells you exactly what the user needs to do:

| Subtype                                                        | Description                                            | Recommended Action                                                                              |
| -------------------------------------------------------------- | ------------------------------------------------------ | ----------------------------------------------------------------------------------------------- |
| `SeamRequiredUserInteraction.CompleteOtpAuthorization(otpUrl)` | The user must complete an OTP authorization flow.      | Open `otpUrl` in a browser or WebView.                                                          |
| `SeamRequiredUserInteraction.EnableInternet`                   | The device has no internet connection.                 | Prompt the user to enable Wi-Fi or mobile data.                                                 |
| `SeamRequiredUserInteraction.EnableBluetooth`                  | Bluetooth is disabled.                                 | Prompt the user to enable Bluetooth in Settings or the quick settings panel.                    |
| `SeamRequiredUserInteraction.GrantPermissions(permissions)`    | One or more Android permissions have not been granted. | Use `ActivityCompat.requestPermissions()` with the list of permission strings in `permissions`. |

### Handling required user interactions

```kotlin theme={null}
fun handleUserInteraction(interaction: SeamRequiredUserInteraction) {
    when (interaction) {
        is SeamRequiredUserInteraction.CompleteOtpAuthorization -> {
            // Open the OTP URL so the user can complete authorization
            openUrl(interaction.otpUrl)
        }
        is SeamRequiredUserInteraction.EnableInternet -> {
            showMessage("Please enable your internet connection and try again.")
        }
        is SeamRequiredUserInteraction.EnableBluetooth -> {
            showMessage("Please enable Bluetooth and try again.")
            // Optionally launch the Bluetooth settings screen:
            // startActivity(Intent(Settings.ACTION_BLUETOOTH_SETTINGS))
        }
        is SeamRequiredUserInteraction.GrantPermissions -> {
            // Request the missing permissions
            ActivityCompat.requestPermissions(
                activity,
                interaction.permissions.toTypedArray(),
                REQUEST_CODE_SEAM_PERMISSIONS
            )
        }
    }
}
```

***

## Handling unlock errors end-to-end

The following example shows a complete unlock handler that covers both pre-flight credential checks and runtime `SeamError` cases:

```kotlin theme={null}
fun performUnlock(credentialId: String) {
    coroutineScope.launch {
        val seam = SeamSDK.getInstance()

        // Check credential errors before attempting unlock
        val credential = seam.credentials.value.firstOrNull { it.id == credentialId }
        if (credential == null) {
            showError("Credential not found.")
            return@launch
        }
        if (credential.errors.isNotEmpty()) {
            // Show the first blocking error to the user
            val firstError = credential.errors.first()
            when (firstError) {
                is SeamCredentialError.Loading                -> showStatus("Loading...")
                is SeamCredentialError.Expired                -> showError("Credential expired.")
                is SeamCredentialError.UserInteractionRequired -> handleUserInteraction(firstError.interaction)
                is SeamCredentialError.Unknown                -> showError("Unknown credential error.")
            }
            return@launch
        }

        // Collect unlock events before initiating the unlock
        launch {
            seam.unlockStatus.collect { event ->
                when (event) {
                    is SeamUnlockEvent.ScanningStarted -> showStatus("Scanning...")
                    is SeamUnlockEvent.AccessGranted   -> showSuccess("Access granted!")
                    is SeamUnlockEvent.Timeout         -> showError("Operation timed out.")
                    is SeamUnlockEvent.ReaderError     -> showError("Reader error: ${event.message}")
                }
            }
        }

        // Initiate the unlock
        try {
            seam.unlock(credentialId = credentialId, timeout = 30.seconds)
        } catch (e: SeamError) {
            when (e) {
                is SeamError.ActivationRequired  -> showError("Please activate the SDK first.")
                is SeamError.InvalidCredentialId -> showError("Credential not found.")
                is SeamError.IntegrationNotFound -> showError("Provider not installed.")
                is SeamError.CredentialErrors    -> {
                    // Errors surfaced at unlock time — re-run the credential check above
                    e.errors.firstOrNull()?.let { handleCredentialError(it) }
                }
                else -> showError("Unlock failed: ${e.message}")
            }
        }
    }
}
```

***

## Best Practices

* **Check `credential.errors` before calling `unlock()`** — An unlock attempt on a credential with unresolved errors will throw `SeamError.CredentialErrors`. Checking upfront lets you present better UX before the call.
* **Subscribe to `unlockStatus` before `unlock()`** — `unlock()` emits events immediately; subscribing after the call can miss early events like `ScanningStarted`.
* **Map errors to UI states** — Distinguish loading states (`SeamCredentialError.Loading`) from actionable errors so you show spinners rather than error messages while credentials are provisioning.
* **Retry transient errors** — `SeamError.InternetConnectionRequired` and `SeamError.DeactivationInProgress` are transient. Implement retry logic with backoff for these cases.

***

## See Also

* [SeamError reference](/mobile-sdks/android/reference/seam-error) — Full type reference for all `SeamError` subtypes.
* [SeamCredentialError reference](/mobile-sdks/android/reference/seam-credential-error) — Full type reference for all `SeamCredentialError` subtypes.
* [Quickstart](/mobile-sdks/android/quickstart) — Initialize the SDK and perform your first unlock.
* [Architecture](/mobile-sdks/android/architecture) — How StateFlows and the SDK lifecycle fit together.


# Android SDK
Source: https://docs.seam.co/mobile-sdks/android/index

Build native Android apps for mobile access and smart device management with the Seam Android SDK, compatible with Android 7.0 (API 24) and above.

The Seam Android SDK lets you build your own mobile app that supports mobile access or smart device management. It provides a reactive, coroutine-friendly API for initializing the SDK, managing credentials, and performing unlock operations with real-time status updates.

Get started with our [quickstart guide](/mobile-sdks/android/quickstart), or browse the [SDK API Reference](/mobile-sdks/android/reference/index).

***

## Requirements

* **Compile SDK:** 35
* **Kotlin:** 2.1.0 or greater
* **Minimum Android SDK:** API Level 24 (Android 7.0) for the base SDK; higher for certain provider modules (see [Installation](/mobile-sdks/android/installation))

***

## Get Started

<CardGroup>
  <Card title="Installation" href="/mobile-sdks/android/installation">
    Add the Seam Android SDK to your project using Gradle and GitHub Packages.
  </Card>

  <Card title="Quickstart" href="/mobile-sdks/android/quickstart">
    Get up and running with a minimal working integration in minutes.
  </Card>

  <Card title="Architecture" href="/mobile-sdks/android/architecture">
    Understand StateFlows, coroutines, offline caching, and the SDK lifecycle.
  </Card>

  <Card title="Error Handling" href="/mobile-sdks/android/error-handling">
    Interpret and handle SeamError, SeamCredentialError, and required user interactions.
  </Card>

  <Card title="API Reference" href="/mobile-sdks/android/reference/index">
    Browse the complete Android SDK API reference documentation.
  </Card>
</CardGroup>


# Installation
Source: https://docs.seam.co/mobile-sdks/android/installation

Add the Seam Android SDK to your project using Gradle and GitHub Packages, configure credentials, and select the provider modules your app needs.

## Requirements

Before integrating the Seam Android SDK, confirm your project meets these requirements:

* **Compile SDK:** 35
* **Kotlin:** 2.1.0 or greater
* **Minimum Android SDK:** Depends on the provider modules you include:

| Module          | Artifact ID                         | Minimum SDK          |
| --------------- | ----------------------------------- | -------------------- |
| Core (required) | `seam-phone-sdk-android-core`       | API 24 (Android 7.0) |
| Salto KS        | `seam-phone-sdk-android-saltoks`    | API 24 (Android 7.0) |
| Salto Space     | `seam-phone-sdk-android-saltospace` | API 24 (Android 7.0) |
| Latch           | `seam-phone-sdk-android-latch`      | API 26 (Android 8.0) |
| Assa Abloy      | `seam-phone-sdk-android-assaabloy`  | API 28 (Android 9.0) |

Your app's `minSdk` must be set to the **highest** level required by any Seam module you include.

<Note>
  Including both `assaabloy` and `latch`, for example, requires `minSdk = 28` because Assa Abloy sets the higher floor.
</Note>

***

## Installation

<Steps>
  <Step title="Request access to the Seam package registry">
    The SDK is distributed as a Maven package on GitHub Packages under the `seampkg/seam-mobile-sdk` repository.

    1. Contact your Seam representative to be added as a collaborator on the repository.
    2. Once added, go to your GitHub [Developer Settings](https://github.com/settings/tokens) and navigate to **Personal access tokens > Tokens (Classic)**.
    3. Click **Generate new token (classic)**.
    4. Give the token a note and an expiration date.
    5. Select the `read:packages` scope.
    6. Click **Generate token** and copy the value — you will not be able to see it again.
  </Step>

  <Step title="Store your credentials in local.properties">
    Open (or create) `local.properties` at the root of your Android project and add your GitHub username and the token you just created:

    ```properties theme={null}
    # local.properties — DO NOT commit this file
    seamUsername=YOUR_GITHUB_USERNAME
    seamPat=ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
    ```

    <Note>
      `local.properties` should be listed in `.gitignore`. Never commit credentials to version control.
    </Note>
  </Step>

  <Step title="Configure the Maven repository in settings.gradle">
    Add a helper function and the GitHub Packages Maven repository to your `settings.gradle.kts` (or `settings.gradle`):

    <Tabs>
      <Tab title="Kotlin DSL (settings.gradle.kts)">
        ```kotlin theme={null}
        import java.util.Properties

        fun getPropertyOrNull(propertyName: String): String? {
            val propertiesFile = file("local.properties")
            if (!propertiesFile.exists()) return null
            val properties = Properties()
            properties.load(propertiesFile.inputStream())
            return properties.getProperty(propertyName, null)
        }

        dependencyResolutionManagement {
            repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
            repositories {
                google()
                mavenCentral()
                maven {
                    name = "GitHubPackages"
                    url = uri("https://maven.pkg.github.com/seampkg/seam-mobile-sdk")
                    credentials {
                        username = getPropertyOrNull("seamUsername")
                        password = getPropertyOrNull("seamPat")
                    }
                }
            }
        }
        ```
      </Tab>

      <Tab title="Groovy DSL (settings.gradle)">
        ```groovy theme={null}
        String getPropertyOrNull(String propertyName) {
            def propertiesFile = file("local.properties")
            if (!propertiesFile.exists()) return null
            def properties = new Properties()
            properties.load(propertiesFile.inputStream())
            return properties.getProperty(propertyName, null)
        }

        dependencyResolutionManagement {
            repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
            repositories {
                google()
                mavenCentral()
                maven {
                    name = "GitHubPackages"
                    url = uri("https://maven.pkg.github.com/seampkg/seam-mobile-sdk")
                    credentials {
                        username = getPropertyOrNull("seamUsername")
                        password = getPropertyOrNull("seamPat")
                    }
                }
            }
        }
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step title="Add SDK dependencies to your app module">
    In your app module's `build.gradle.kts` (or `build.gradle`), add `core` plus whichever provider modules your app requires:

    <Tabs>
      <Tab title="Kotlin DSL (build.gradle.kts)">
        ```kotlin theme={null}
        val seamVersion = "1.9.39" // Replace with the latest version

        dependencies {
            // Required
            implementation("co.seam:seam-phone-sdk-android-core:$seamVersion")

            // Add only the provider integrations you need
            implementation("co.seam:seam-phone-sdk-android-saltoks:$seamVersion")
            implementation("co.seam:seam-phone-sdk-android-saltospace:$seamVersion")
            implementation("co.seam:seam-phone-sdk-android-latch:$seamVersion")
            implementation("co.seam:seam-phone-sdk-android-assaabloy:$seamVersion")
        }
        ```
      </Tab>

      <Tab title="Groovy DSL (build.gradle)">
        ```groovy theme={null}
        def seamVersion = "1.9.39" // Replace with the latest version

        dependencies {
            // Required
            implementation "co.seam:seam-phone-sdk-android-core:$seamVersion"

            // Add only the provider integrations you need
            implementation "co.seam:seam-phone-sdk-android-saltoks:$seamVersion"
            implementation "co.seam:seam-phone-sdk-android-saltospace:$seamVersion"
            implementation "co.seam:seam-phone-sdk-android-latch:$seamVersion"
            implementation "co.seam:seam-phone-sdk-android-assaabloy:$seamVersion"
        }
        ```
      </Tab>
    </Tabs>

    Sync your project with Gradle after saving.
  </Step>
</Steps>

***

## Quick Verification

Once the sync succeeds, verify the SDK is on the classpath by adding a temporary import to any Kotlin file:

```kotlin theme={null}
import co.seam.core.api.SeamSDK
```

If Android Studio resolves the import without errors, the SDK is installed correctly.

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="401 Unauthorized during Gradle sync">
    * Confirm `seamUsername` and `seamPat` are set correctly in `local.properties`.
    * Verify the PAT has the `read:packages` scope and has not expired.
    * Ensure you have been added as a collaborator on the `seampkg/seam-mobile-sdk` repository.
  </Accordion>

  <Accordion title="Package not found / Could not resolve dependency">
    * Confirm the `maven { ... }` block is inside `dependencyResolutionManagement.repositories` in `settings.gradle.kts`, not inside a module's `build.gradle.kts`.
    * Double-check the artifact ID spelling (for example, `seam-phone-sdk-android-core`, not `seam-android-core`).
    * Try a fresh Gradle sync via **File > Sync Project with Gradle Files**.
  </Accordion>

  <Accordion title="minSdk conflict">
    If Gradle reports a manifest merger conflict about `minSdkVersion`, raise your app's `minSdk` to match the highest value required by the Seam modules you have included. See the requirements table above.
  </Accordion>

  <Accordion title="Kotlin version incompatibility">
    The SDK requires Kotlin 2.1.0 or later. Check your project's `libs.versions.toml` or `build.gradle.kts` and update the `kotlin` version entry accordingly.
  </Accordion>
</AccordionGroup>

For additional support, reach out in your dedicated Seam support Slack channel.

***

## Next Steps

* [Quickstart](/mobile-sdks/android/quickstart) — Initialize the SDK and perform your first unlock.
* [Architecture](/mobile-sdks/android/architecture) — How the SDK's reactive model and offline caching work.
* [Error Handling](/mobile-sdks/android/error-handling) — Handling `SeamError` and credential errors.


# Quickstart
Source: https://docs.seam.co/mobile-sdks/android/quickstart

Get up and running with the Seam Android SDK in minutes: install, initialize, activate, observe credentials, and perform your first unlock.

## Prerequisites

* Android project with Compile SDK 35 and Kotlin 2.1.0+
* Seam Android SDK installed (see [Installation](/mobile-sdks/android/installation))
* A client session token (CST) from the Seam API for the current user

***

## Overview

The integration follows three steps:

1. **Initialize** — Bootstrap the SDK once with a client session token.
2. **Activate** — Sync credentials and start background services.
3. **Unlock** — Observe credentials and trigger the unlock flow.

<Steps>
  <Step title="Initialize the SDK">
    Call `SeamSDK.initialize()` once per user session — the best place is `Application.onCreate()` or immediately after sign-in. It is a `suspend` function, so call it from a coroutine.

    ```kotlin theme={null}
    import co.seam.core.api.SeamSDK
    import co.seam.core.sdkerrors.SeamError

    // In your Application class or sign-in flow:
    coroutineScope.launch {
        try {
            SeamSDK.initialize(context, "seam_cst_...")
        } catch (e: SeamError) {
            when (e) {
                is SeamError.AlreadyInitialized -> {
                    // SDK is already set up — safe to ignore
                }
                is SeamError.InvalidClientSessionToken -> {
                    // Token is malformed; check your sign-in flow
                }
                else -> {
                    // Log and surface the error to the user
                }
            }
        }
    }
    ```

    <Note>
      `initialize` is idempotent and thread-safe. Calling it a second time with the same token is a no-op. To re-initialize with a different token, call `deactivate(deintegrate = true)` first.
    </Note>
  </Step>

  <Step title="Activate and observe credentials">
    After initialization, call `activate()` to sync credentials from the server. Then collect the `credentials` StateFlow to react to credential updates in your UI.

    ```kotlin theme={null}
    import co.seam.core.api.SeamSDK
    import co.seam.core.sdkerrors.SeamError

    coroutineScope.launch {
        val seam = SeamSDK.getInstance()

        try {
            seam.activate()
        } catch (e: SeamError) {
            when (e) {
                is SeamError.InternetConnectionRequired -> {
                    showError("No internet connection. Please connect and try again.")
                }
                is SeamError.InvalidClientSessionToken -> {
                    showError("Session expired. Please sign in again.")
                }
                else -> {
                    showError("Activation failed: ${e.message}")
                }
            }
        }

        // Observe the credential list reactively
        seam.credentials.collect { credentials ->
            if (credentials.isEmpty()) {
                showNoCredentialsView()
            } else {
                showCredentialsList(credentials)
            }
        }
    }
    ```

    <Note>
      `credentials` is a `StateFlow` — it emits the current list immediately upon collection and then again whenever the list changes. Use `lifecycleScope.launch` or `repeatOnLifecycle` in a Fragment or Activity to automatically cancel collection when the view is destroyed.
    </Note>
  </Step>

  <Step title="Perform an unlock">
    Before calling `unlock()`, subscribe to `unlockStatus` so you receive all progress events. Pass the credential ID and an optional timeout. The `unlock()` call returns a `Job` that you can cancel if needed.

    ```kotlin theme={null}
    import co.seam.core.api.SeamSDK
    import co.seam.core.sdkerrors.SeamError
    import co.seam.core.events.SeamUnlockEvent
    import kotlin.time.Duration.Companion.seconds

    coroutineScope.launch {
        val seam = SeamSDK.getInstance()

        // Collect unlock status events before starting the unlock
        launch {
            seam.unlockStatus.collect { event ->
                when (event) {
                    is SeamUnlockEvent.ScanningStarted -> showStatus("Scanning...")
                    is SeamUnlockEvent.AccessGranted   -> showSuccess("Access granted!")
                    is SeamUnlockEvent.Timeout         -> showError("Timed out")
                    is SeamUnlockEvent.ReaderError     -> showError("Reader error: ${event.message}")
                }
            }
        }

        // Initiate the unlock — throws SeamError on pre-flight failures
        try {
            val credential = seam.credentials.value.first()
            val credentialId = credential.id ?: return@launch
            seam.unlock(
                credentialId = credentialId,
                timeout = 30.seconds
            )
        } catch (e: SeamError) {
            when (e) {
                is SeamError.ActivationRequired    -> showError("Please activate the SDK first.")
                is SeamError.InvalidCredentialId   -> showError("Credential not found.")
                is SeamError.CredentialErrors      -> handleCredentialErrors(e.errors)
                is SeamError.IntegrationNotFound   -> showError("Provider integration not installed.")
                else                               -> showError("Unlock failed: ${e.message}")
            }
        }
    }
    ```

    <Note>
      Always check `credential.errors` before unlocking. If a credential has unresolved errors (for example, `Loading` or `UserInteractionRequired`), the unlock call will throw `SeamError.CredentialErrors`. See [Error Handling](/mobile-sdks/android/error-handling) for details.
    </Note>
  </Step>
</Steps>

***

## Complete Example

The following shows the three steps wired together in a minimal Activity:

```kotlin theme={null}
import android.os.Bundle
import androidx.activity.ComponentActivity
import androidx.lifecycle.lifecycleScope
import androidx.lifecycle.repeatOnLifecycle
import androidx.lifecycle.Lifecycle
import co.seam.core.api.SeamSDK
import co.seam.core.events.SeamUnlockEvent
import co.seam.core.sdkerrors.SeamError
import kotlinx.coroutines.launch
import kotlin.time.Duration.Companion.seconds

class MainActivity : ComponentActivity() {

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        lifecycleScope.launch {
            // Step 1: Initialize (in practice, do this in Application.onCreate)
            try {
                SeamSDK.initialize(applicationContext, "seam_cst_...")
            } catch (e: SeamError.AlreadyInitialized) {
                // Already initialized — continue
            }

            val seam = SeamSDK.getInstance()

            // Step 2: Activate
            try {
                seam.activate()
            } catch (e: SeamError) {
                return@launch
            }

            // Observe credentials using lifecycle-aware collection
            repeatOnLifecycle(Lifecycle.State.STARTED) {
                seam.credentials.collect { credentials ->
                    // Update your UI here
                }
            }
        }
    }

    fun onUnlockButtonClicked(credentialId: String) {
        lifecycleScope.launch {
            val seam = SeamSDK.getInstance()

            // Step 3: Subscribe to status, then unlock
            launch {
                seam.unlockStatus.collect { event ->
                    when (event) {
                        is SeamUnlockEvent.AccessGranted -> showSuccess()
                        is SeamUnlockEvent.Timeout       -> showError("Timed out")
                        else -> {}
                    }
                }
            }

            try {
                seam.unlock(credentialId = credentialId, timeout = 30.seconds)
            } catch (e: SeamError) {
                showError(e.message ?: "Unlock failed")
            }
        }
    }
}
```

***

## Next Steps

* [Architecture](/mobile-sdks/android/architecture) — Deep dive into StateFlows, coroutine context, offline caching, and SDK lifecycle.
* [Error Handling](/mobile-sdks/android/error-handling) — All `SeamError` subtypes and credential error patterns.
* [API Reference](/mobile-sdks/android/reference/index) — Full reference for `SeamSDK`, `SeamCredential`, and related types.


# Android SDK API Reference
Source: https://docs.seam.co/mobile-sdks/android/reference/index

Public API surface of the Seam Android SDK.

> Auto-generated from the Seam Android SDK Kotlin sources. Do not edit by hand — see `codegen/android-reference/`.

<CardGroup>
  <Card title="SeamSDK" icon="android" href="/mobile-sdks/android/reference/seam-sdk">
    This is the main entry point for the Seam Android SDK.
  </Card>

  <Card title="SeamCredential" icon="android" href="/mobile-sdks/android/reference/seam-credential">
    A Seam credential object.
  </Card>

  <Card title="SeamError" icon="android" href="/mobile-sdks/android/reference/seam-error">
    Base class for all Seam errors.
  </Card>

  <Card title="SeamCredentialError" icon="android" href="/mobile-sdks/android/reference/seam-credential-error">
    A credential error is an error that is related to a credential.
  </Card>

  <Card title="SeamRequiredUserInteraction" icon="android" href="/mobile-sdks/android/reference/seam-required-user-interaction">
    A user interaction that is required to unlock a credential.
  </Card>

  <Card title="SeamUnlockEvent" icon="android" href="/mobile-sdks/android/reference/seam-unlock-event">
    Events related to the co.seam.core.api.SeamSDK.unlock operation.
  </Card>

  <Card title="UnlockProximity" icon="android" href="/mobile-sdks/android/reference/unlock-proximity">
    Represents the proximity at which a credential used to unlock a door.
  </Card>
</CardGroup>


# SeamCredential
Source: https://docs.seam.co/mobile-sdks/android/reference/seam-credential

A Seam credential object.

> Auto-generated from the Seam Android SDK Kotlin sources. Do not edit by hand — see `codegen/android-reference/`.

## Overview

```kotlin theme={null}
data class SeamCredential(
    val id: String?,
    val supportedUnlockProximities: List<UnlockProximity>,
    val name: String,
    val location: String?,
    val expiry: LocalDateTime?,
    val cardNumber: String?,
    val code: String?,
    val errors: List<SeamCredentialError>,
    val isManaged: Boolean,
    val providerName: String
)
```

A Seam credential object. It contains information about a credential, such as its ID, name,
location, expiration date, and any errors that it encountered.

***

## Properties

| Property                     | Type                        | Description                                                                                                                                                                                                                                         |
| ---------------------------- | --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`                         | `String?`                   | The ID of the credential.                                                                                                                                                                                                                           |
| `supportedUnlockProximities` | `List<UnlockProximity>`     | The list of unlock proximities supported by the credential. Possible values in the list: UnlockProximity.TOUCH UnlockProximity.NEARBY UnlockProximity.REMOTE Use one of these values to pass to `SeamSDK.unlock`                                    |
| `name`                       | `String`                    | A human-readable name for the credential.                                                                                                                                                                                                           |
| `location`                   | `String?`                   | A human-readable location for the credential.                                                                                                                                                                                                       |
| `expiry`                     | `LocalDateTime?`            | The date and time when the credential expires.                                                                                                                                                                                                      |
| `cardNumber`                 | `String?`                   | The card number associated with the credential.                                                                                                                                                                                                     |
| `code`                       | `String?`                   | The code associated with the credential.                                                                                                                                                                                                            |
| `errors`                     | `List<SeamCredentialError>` | A list of errors that the credential encountered.                                                                                                                                                                                                   |
| `isManaged`                  | `Boolean`                   | Indicates whether this credential was created and managed by the Seam API (`true`), or was discovered directly through the provider integration (`false`).                                                                                          |
| `providerName`               | `String`                    | The provider name as String. Possible values: "hid\_origo\_credential\_service" "salto\_ks" "brivo" "assa\_abloy\_credential\_service" "visionline\_system" "latch" "assa\_abloy\_vostio" "assa\_abloy\_vostio\_credential\_service" "salto\_space" |


# SeamCredentialError
Source: https://docs.seam.co/mobile-sdks/android/reference/seam-credential-error

A credential error is an error that is related to a credential.

> Auto-generated from the Seam Android SDK Kotlin sources. Do not edit by hand — see `codegen/android-reference/`.

## Overview

```kotlin theme={null}
sealed class SeamCredentialError : SeamError()
```

A credential error is an error that is related to a credential. When a credential error
occurs, it means that the credential is not valid or has some issues. It can be thrown when
trying to unlock with a credential, or they can come in the `SeamCredential.errors` list.

***

## Cases

### `Loading`

The credential is still loading. This error is usually thrown when trying to unlock
with a credential that was not fully loaded.

```kotlin theme={null}
class Loading : SeamCredentialError()
```

### `Expired`

The credential has expired. This error is usually thrown when trying to unlock
with a credential that has expired.

```kotlin theme={null}
class Expired : SeamCredentialError()
```

### `UserInteractionRequired`

The credential requires user interaction to be unlocked. This error is usually thrown
when trying to unlock a credential that requires user interaction, such as completing
an OTP authorization or enabling Bluetooth.

```kotlin theme={null}
data class UserInteractionRequired(
```

**Parameters**

| Parameter     | Description                   |
| ------------- | ----------------------------- |
| `interaction` | the required user interaction |

### `Unknown`

An unknown credential error occurred.

```kotlin theme={null}
class Unknown : SeamCredentialError()
```


# SeamError
Source: https://docs.seam.co/mobile-sdks/android/reference/seam-error

Base class for all Seam errors.

> Auto-generated from the Seam Android SDK Kotlin sources. Do not edit by hand — see `codegen/android-reference/`.

## Overview

```kotlin theme={null}
sealed class SeamError : Exception()
```

Base class for all Seam errors.

These errors are thrown by Seam classes and interfaces. They are all subclasses of
`SeamError`.

***

## Cases

### `InitializationRequired`

The SDK has not been initialized. Call `SeamSDK.initialize` first. Usually
thrown when trying to call a method that requires the SDK to be initialized,
such as `SeamSDK.unlock` or `SeamSDK.activate`.

```kotlin theme={null}
class InitializationRequired : SeamError()
```

### `ActivationRequired`

The app user's phone has not been activated. Call `SeamSDK.activate` first.

```kotlin theme={null}
class ActivationRequired : SeamError()
```

### `IntegrationNotFound`

No integration found for the specified credential. Usually thrown when trying to
unlock a credential that doesn't have an integration (Assa Abloy, Latch, Salto, etc)
associated with it.

```kotlin theme={null}
class IntegrationNotFound : SeamError()
```

### `AlreadyInitialized`

The SDK is already initialized. Thrown when trying to call
`SeamSDK.initialize` multiple times. You can call `SeamSDK.deactivate` first.

```kotlin theme={null}
class AlreadyInitialized : SeamError()
```

### `DeactivationInProgress`

A deactivation is already in progress. Throw when trying to call
`SeamSDK.deactivate` multiple times.

```kotlin theme={null}
class DeactivationInProgress : SeamError()
```

### `InvalidCredentialId`

The credential id is invalid. This error is usually thrown when trying to unlock
with a credential that is invalid, or not recognized by the SDK.

```kotlin theme={null}
class InvalidCredentialId : SeamError()
```

### `CredentialErrors`

There are multiple credential errors. Thrown when trying to unlock with a credential.
Check the `errors` list for more details.

```kotlin theme={null}
class CredentialErrors(val errors: List<SeamCredentialError>) : SeamError()
```

**Parameters**

| Parameter | Description        |
| --------- | ------------------ |
| `errors`  | the list of errors |

### `InternetConnectionRequired`

The device does not have an internet connection. Usually thrown when trying to
call a method that requires an internet connection, such as `SeamSDK.unlock`,
`SeamSDK.initialize`, `SeamSDK.refresh`, `SeamSDK.activate` etc.

```kotlin theme={null}
class InternetConnectionRequired : SeamError()
```

### `InvalidClientSessionToken`

The client session token is invalid. Trhown when trying to call
`SeamSDK.initialize` with an invalid client session token.

```kotlin theme={null}
class InvalidClientSessionToken(
```

**Parameters**

| Parameter | Description       |
| --------- | ----------------- |
| `message` | the error message |

### `InvalidUnlockProximity`

The unlock proximity is invalid. Thrown when trying to unlock with an invalid unlock
proximity.

```kotlin theme={null}
class InvalidUnlockProximity : SeamError()
```

### `Unknown`

An unknown error occurred.

```kotlin theme={null}
class Unknown : SeamError()
```


# SeamRequiredUserInteraction
Source: https://docs.seam.co/mobile-sdks/android/reference/seam-required-user-interaction

A user interaction that is required to unlock a credential.

> Auto-generated from the Seam Android SDK Kotlin sources. Do not edit by hand — see `codegen/android-reference/`.

## Overview

```kotlin theme={null}
sealed class SeamRequiredUserInteraction
```

A user interaction that is required to unlock a credential. This can be one of the following:

* `CompleteOtpAuthorization`: complete an OTP authorization to unlock the credential.
* `EnableInternet`: enable internet to unlock the credential.
* `EnableBluetooth`: enable Bluetooth to unlock the credential.
* `GrantPermissions`: grant the required permissions to unlock the credential.

***

## Cases

### `CompleteOtpAuthorization`

Complete an OTP authorization to unlock with the credential. The user needs to go to
`otpUrl` to complete the authorization.

```kotlin theme={null}
data class CompleteOtpAuthorization(val otpUrl: URL) : SeamRequiredUserInteraction()
```

**Parameters**

| Parameter | Description                               |
| --------- | ----------------------------------------- |
| `otpUrl`  | the URL to complete the OTP authorization |

### `EnableInternet`

Enable internet to unlock with the credential. The user needs to enable internet on their device.

```kotlin theme={null}
class EnableInternet : SeamRequiredUserInteraction()
```

### `EnableBluetooth`

Enable Bluetooth to unlock the credential. The user needs to enable Bluetooth on their device.

```kotlin theme={null}
class EnableBluetooth : SeamRequiredUserInteraction()
```

### `GrantPermissions`

Grant the required permissions to unlock with the credential. The user needs to grant the
required permissions on their device.

```kotlin theme={null}
class GrantPermissions(val permissions: List<String>) : SeamRequiredUserInteraction()
```

**Parameters**

| Parameter     | Description                             |
| ------------- | --------------------------------------- |
| `permissions` | the permissions that need to be granted |


# SeamSDK
Source: https://docs.seam.co/mobile-sdks/android/reference/seam-sdk

This is the main entry point for the Seam Android SDK.

> Auto-generated from the Seam Android SDK Kotlin sources. Do not edit by hand — see `codegen/android-reference/`.

## Overview

```kotlin theme={null}
class SeamSDK()
```

This is the main entry point for the Seam Android SDK.

Use the `getInstance` function to get the instance of this class.
You can only get the instance of the class after you have initialized the SDK by calling
`initialize`.

The `initialize` function will initialize the SDK.

## Thread Safety

* All StateFlow properties (`credentials`, `isActivated`, `unlockStatus`) are thread-safe
* All suspend functions can be called from any coroutine context
* `initialize` is thread-safe and idempotent

## StateFlow Lifecycle

* `credentials`: Emits whenever credential list changes, survives configuration changes
* `unlockStatus`: Emits unlock events, latest event is always available via .value
* `isActivated`: Reflects current SDK activation state

Collecting these flows is lifecycle-safe when used with Android lifecycle-aware scopes

## Offline Behavior

* SDK caches credentials and can work offline for unlock operations
* `activate` requires internet connection initially
* `refresh` requires internet connection
* `unlock` can work offline if credentials are already cached

## Error Recovery

* Most operations can be safely retried after fixing underlying issues
* Credential errors (in SeamCredential.errors) should be resolved before unlock
* Network errors during activate/refresh are transient and can be retried

## Background Processing

* Unlock operations continue in background
* StateFlow emissions work across app lifecycle

## Lifecycle

* Call `initialize` once per app session, typically in Application.onCreate()
* `activate` when user wants to use credential features
* No explicit cleanup needed - Android handles resource cleanup
* `deactivate` stops background operations but preserves credentials

***

## Companion object methods

### `initialize`

Initializes the Seam Android SDK. This should be called once at the
start of your application.

Example:

```kotlin theme={null}
try {
    SeamSDK.initialize(context, "seam_cst_...")
} catch (seamError: SeamError) {
    when (seamError) {
        is SeamError.AlreadyInitialized -> {
            // handle error when SDK is already initialized
        }
        is SeamError.DeactivationInProgress -> {
            // handle error when app is being deactivated
        }
        is SeamError.InternetConnectionRequired -> {
            // handle error when internet connection is required
        }
        is SeamError.InvalidClientSessionToken ->  {
            // handle error when client session token is invalid
        }
        else -> {
            // handle other errors
        }
    }
}
```

```kotlin theme={null}
suspend fun initialize(context: Context, clientSessionToken: String)
```

**Parameters**

| Parameter            | Description                                |
| -------------------- | ------------------------------------------ |
| `context`            | the Android context.                       |
| `clientSessionToken` | the client session token for the app user. |

**Throws**

* `SeamError.AlreadyInitialized` — if the SDK is already initialized.
* `SeamError.InternetConnectionRequired` — if no internet connection is available.
* `SeamError.InvalidClientSessionToken` — if the token format is invalid.
* `SeamError.DeactivationInProgress` — if a deactivation is in progress.

### `getInstance`

Returns the instance of `SeamSDK`. This can be used to get a handle to the
SeamSDK after it has been initialized.

This method is thread-safe and can be called from any thread.

```kotlin theme={null}
fun getInstance() : SeamSDK
```

**Returns** — The initialized SeamSDK instance.

**Throws**

* `SeamError.InitializationRequired` — if `initialize` has not been called yet.

***

## Properties

### `isActivated`

Returns whether the app user's phone has been activated.

This StateFlow emits `true` after successful `activate` call and `false` after `deactivate`.
The flow is thread-safe and can be collected from any coroutine context.
Latest value is always available via `.value` property.

```kotlin theme={null}
val isActivated
```

### `credentials`

Returns the list of `SeamCredential` for the current app user.

This StateFlow emits an immutable list whenever credentials change.
The list may be empty if no credentials are available or while loading.
Check each credential's `errors` property to determine if it's ready for use.

The flow is thread-safe and can be collected from any coroutine context.
Latest value is always available via `.value` property.

```kotlin theme={null}
// Observe credentials
seamSDK.credentials.collect { credentials ->
    // credentials is a list of [SeamCredential]
    if (credentials.isEmpty()) {
        // handle no credentials
    } else {
        // handle credentials (e.g. display them)
    }
}

// handle credential errors
SeamSDK.getInstance().credentials.collect { credentialsList ->
    val errors = credentialsList.flatMap { it.errors }
    errors.forEach { error ->
        when (error) {
            is SeamCredentialError.Expired -> { /* handle credential expiration error */ }
            is SeamCredentialError.Loading -> { /* handle not loaded yet */ }
            is SeamCredentialError.Unknown -> { /* handle unknown error */ }
            is SeamCredentialError.UserInteractionRequired -> {
                handleUserInteractionRequired(error.interaction)
            }
        }
    }
}

fun handleUserInteractionRequired(interaction: SeamRequiredUserInteraction) {
    when (interaction) {
         is SeamRequiredUserInteraction.CompleteOtpAuthorization -> { /* handle OTP authorization */ }
         is SeamRequiredUserInteraction.EnableBluetooth -> { /* handle Bluetooth error */ }
         is SeamRequiredUserInteraction.EnableInternet -> { /* handle Internet connection error*/ }
         is SeamRequiredUserInteraction.GrantPermissions -> { /* handle permissions error*/ }
    }
}
```

```kotlin theme={null}
val credentials
```

### `unlockStatus`

Returns the current status of the unlock feature.

This StateFlow emits `SeamUnlockEvent` instances as unlock operations progress.
Events include scanning, connection, access granted, errors, and timeout.
The flow retains the latest event, accessible via `.value` property.

Subscribe to this flow before calling `unlock` to ensure no events are missed.
The flow is thread-safe and can be collected from any coroutine context.

```kotlin theme={null}
val unlockStatus
```

***

## Methods

### `setUnlockEventListener`

Sets the listener for the unlock events.

```kotlin theme={null}
fun setUnlockEventListener(listener: (SeamUnlockEvent) -> Unit)
```

**Parameters**

| Parameter  | Description                               |
| ---------- | ----------------------------------------- |
| `listener` | the listener to listen for unlock events. |

### `setNotification`

Sets the notification for the unlock feature. Required for Assa Abloy foreground scanning.

```kotlin theme={null}
fun setNotification(notification: Notification)
```

**Parameters**

| Parameter      | Description                                     |
| -------------- | ----------------------------------------------- |
| `notification` | the notification to use for the unlock feature. |

### `setCredentialsListener`

Sets the listener for the credentials.

```kotlin theme={null}
fun setCredentialsListener(listener: (List<SeamCredential>) -> Unit)
```

**Parameters**

| Parameter  | Description                             |
| ---------- | --------------------------------------- |
| `listener` | the listener to listen for credentials. |

### `listCredentials`

Lists the credentials for the current app user.

```kotlin theme={null}
fun listCredentials() : List<SeamCredential>
```

**Returns** — a SeamResult of a list of AcsPhoneCredential. If the SDK has not been initialized yet, the result will be a SeamFailure with `SeamError.InitializationRequired`.

### `unlock`

Unlocks the app user's phone.

Initiates an unlock operation for the specified credential. Progress events are emitted
to `unlockStatus` StateFlow. The operation continues even if the app goes to background.

Works offline if credentials are already cached. Requires the device to have the
necessary hardware (Bluetooth, NFC, etc.) and permissions granted.

```kotlin theme={null}
val seamSDK = SeamSDK.getInstance()
// Start collecting unlock events before unlock
coroutineScope.launch {
    seamSDK.unlockStatus.collect { event ->
        when (event) {
            is SeamUnlockEvent.ScanningStarted -> { /* handle scanning started */ }
            is SeamUnlockEvent.Connecting -> { /* handle connecting */ }
            is SeamUnlockEvent.AccessGranted -> { /* handle access granted */ }
            is SeamUnlockEvent.Timeout -> { /* handle timeout */ }
            is SeamUnlockEvent.ReaderError -> { /* handle reader error */ }
            else -> { /* handle other events */ }
        }
    }
}

// Perform unlock
try {
    val credentialId = credential.id
    // Timeout is optional
    seamSDK.unlock(
        credentialId = credentialId,
        unlockProximity = UnlockProximity.TOUCH,
        timeout = 30.seconds
    )
} catch (seamError: SeamError) {
    when (seamError) {
        is SeamError.ActivationRequired -> {
            // handle error when SDK is not activated
        }
        is SeamError.CredentialErrors -> {
            val credentialErrors = seamError.errors
            handleCredentialErrors(credentialErrors)
            // handle error when there are credential errors
        }
        is SeamError.InitializationRequired -> {
            // handle error when SDK is not initialized
        }
        is SeamError.IntegrationNotFound -> {
            // handle error when integration is not found, Such as Assa Abloy, Latch and Salto
        }
        is SeamError.InvalidCredentialId -> {
            // handle error when credential ID is invalid
        }
        else -> {
            // handle other errors
        }
    }
}

// Handle credential errors on unlock
fun handleCredentialErrors(credentialErrors: List<SeamCredentialError>) {
    credentialErrors.forEach { credentialError ->
        when (credentialError) {
            is SeamCredentialError.Invalid -> {
                // handle error when credential is invalid
            }

            is SeamCredentialError.Expired -> {
                // handle error when credential is expired
            }

            is SeamCredentialError.Loading -> {
                // handle error when credential is not loaded yet
            }

            is SeamCredentialError.UserInteractionRequired -> {
                // handle user interaction required credential error
            }
            is SeamCredentialError.InvalidUnlockProximity -> {
                // handle invalid unlock proximity credential error
            }
            is SeamCredentialError.Unknown -> {
                // handle unknown credential error
            }
        }
    }
}
```

```kotlin theme={null}
fun unlock(credentialId: CredentialId, unlockProximity: UnlockProximity? = null, timeout: Duration? = null) : Job
```

**Parameters**

| Parameter         | Description                                                                                                                                                                                                                    |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `credentialId`    | the credential ID to unlock. CredentialId is a type alias for String.                                                                                                                                                          |
| `timeout`         | the timeout for the unlock operation. If null, uses provider default.                                                                                                                                                          |
| `unlockProximity` | the unlock proximity `UnlockProximity`. If null, uses provider default, which is the first in the list of `SeamCredential.supportedUnlockProximities`. The `SeamCredential` must have at least one supported unlock proximity. |

**Returns** — a Job that can be used to cancel the unlock operation.

**Throws**

* `SeamError.InitializationRequired` — if the SDK has not been initialized yet.
* `SeamError.IntegrationNotFound` — if the integration is not found.
* `SeamError.InvalidCredentialId` — if the credential ID is invalid.
* `SeamError.ActivationRequired` — if the app user's phone has not been activated yet.
* `SeamError.CredentialErrors` — if the credential has unresolved errors.
* `SeamError.InvalidUnlockProximity` — if the unlock proximity is invalid.

### `suspend activate`

Activates the app user's phone.

Prepares the SDK for use by syncing with the server and setting up background services.
This operation requires an active internet connection on first activation.
Safe to call multiple times - subsequent calls are no-ops if already activated.

After successful activation, `isActivated` will emit `true` and credentials will
start syncing automatically.

```kotlin theme={null}
val seamSDK = SeamSDK.getInstance()
try {
    // activate is a suspend function
    seamSDK.activate()
} catch (seamError: SeamError) {
    when (seamError) {
        is SeamError.InitializationRequired -> {
            // handle error when SDK is already initialized
        }
        is SeamError.InternetConnectionRequired -> {
            // handle error when internet connection is required
        }
        is SeamError.InvalidClientSessionToken ->  {
            // handle error when client session token is invalid
        }
        else -> {
            // handle other errors
        }
    }
}
```

```kotlin theme={null}
suspend fun activate()
```

**Throws**

* `SeamError.InitializationRequired` — if the SDK has not been initialized yet.
* `SeamError.InternetConnectionRequired` — if no internet connection is available.
* `SeamError.InvalidClientSessionToken` — if the client session token is invalid.

### `suspend deactivate`

Deactivates the app user's phone.

Stops background operations and cleans up resources. Credentials remain cached
and available for the next activation. After deactivation, `isActivated` will emit `false`.

This method is safe to call multiple times and will not throw if already deactivated.

```kotlin theme={null}
val seamSDK = SeamSDK.getInstance()
try {
    // deactivate is a suspend function
    seamSDK.deactivate(deintegrate = true)
} catch (seamError: SeamError) {
    when (seamError) {
        is SeamError.InitializationRequired -> {
            // handle error when SDK is not initialized
        }
        is SeamError.DeactivationInProgress -> {
            // handle error when internet connection is required
        }
        else -> {
            // handle other errors
        }
    }
}
```

```kotlin theme={null}
suspend fun deactivate(deintegrate: Boolean = false)
```

**Parameters**

| Parameter     | Description                                               |
| ------------- | --------------------------------------------------------- |
| `deintegrate` | If true, removes device association and clears all state. |

**Throws**

* `SeamError.InitializationRequired` — if the SDK has not been initialized yet.
* `SeamError.DeactivationInProgress` — if a deactivation is already in progress.

### `suspend refresh`

Refreshes the credentials for the current app user.

Manually triggers a sync with the server to fetch latest credentials.
This operation requires an active internet connection. You should call
`initialize` and `activate` first.

The `credentials` StateFlow will be updated before this method returns.
In most cases, automatic background sync makes manual refresh unnecessary.

```kotlin theme={null}
val seamSDK = SeamSDK.getInstance()
try {
    seamSDK.refresh()
} catch (seamError: SeamError) {
    when (seamError) {
        is SeamError.InitializationRequired -> {
            // handle error when SDK is not initialized
        }
        is SeamError.DeactivationInProgress -> {
            // handle error when app is being deactivated
        }
        else -> {
            // handle other errors
        }
    }
}
```

```kotlin theme={null}
suspend fun refresh() : List<SeamCredential>
```

**Returns** — The updated list of credentials after refresh completes.

**Throws**

* `SeamError.InitializationRequired` — if the SDK has not been initialized yet.
* `SeamError.DeactivationInProgress` — if a deactivation is in progress.


# SeamUnlockEvent
Source: https://docs.seam.co/mobile-sdks/android/reference/seam-unlock-event

Events related to the co.seam.core.api.SeamSDK.unlock operation.

> Auto-generated from the Seam Android SDK Kotlin sources. Do not edit by hand — see `codegen/android-reference/`.

## Overview

```kotlin theme={null}
sealed class SeamUnlockEvent
```

Events related to the `co.seam.core.api.SeamSDK.unlock` operation.

***

## Cases

### `ScanningStarted`

The unlock operation has started scanning.

```kotlin theme={null}
class ScanningStarted : SeamUnlockEvent()
```

### `AccessGranted`

The unlock operation has been granted access.

```kotlin theme={null}
class AccessGranted : SeamUnlockEvent()
```

### `Timeout`

The unlock operation has timed out.

```kotlin theme={null}
class Timeout : SeamUnlockEvent()
```

### `ReaderError`

An error has occurred while communicating with the reader.

```kotlin theme={null}
class ReaderError(val message: String) : SeamUnlockEvent()
```


# UnlockProximity
Source: https://docs.seam.co/mobile-sdks/android/reference/unlock-proximity

Represents the proximity at which a credential used to unlock a door.

> Auto-generated from the Seam Android SDK Kotlin sources. Do not edit by hand — see `codegen/android-reference/`.

## Overview

```kotlin theme={null}
enum class UnlockProximity
```

Represents the proximity at which a credential used to unlock a door.

***

## Values

### `TOUCH`

Means that user have to touch the back of the phone to unlock the reader.

### `NEARBY`

Means that user have to be close to the reader to unlock it, but not necessarily touch.

### `REMOTE`

The reader is unlocked from a remote location, with wi-fi, for example.


# Mobile SDKs
Source: https://docs.seam.co/mobile-sdks/index

Build native iOS and Android apps with Seam's mobile SDKs, a unified interface for mobile access providers and a wide range of IoT devices.

Our mobile device helper libraries (also known as Mobile SDKs) help you create native applications for Apple's and Android's devices and platforms. These SDKs simplify integration with various mobile access providers and streamline your development process through a single unified interface. With a broad range of functionalities, they allow you to build a fully custom experience for your users. Further, these universal mobile SDKs are compatible with a [wide variety of IoT devices and access systems](/device-and-system-integration-guides).

<CardGroup>
  <Card title="iOS SDK" href="/mobile-sdks/ios/index">
    Build native iOS apps for mobile access and smart device management with the Seam iOS SDK.
  </Card>

  <Card title="Android SDK" href="/mobile-sdks/android/index">
    Build native Android apps for mobile access and smart device management with the Seam Android SDK.
  </Card>
</CardGroup>

***

## Key Features

* Universal SDKs across IoT device and access system providers
* User account and phone management
* Device eligibility handling
* Credential management and unlock handling
* Offline support\*

\*Excludes calls to the web API. Your users must initially authenticate your application, which requires an internet connection.


# Architecture
Source: https://docs.seam.co/mobile-sdks/ios/architecture

A high-level view of how the Seam iOS SDK integrates with your app, Seam Cloud services, and lock hardware — including data flow, security, and offline support.

## System Components

SeamSDK connects four main components:

* **Mobile App** — Your iOS application, written in Swift, that calls the Seam SDK.
* **SeamSDK** — A native library responsible for credential management, unlock flows, and event streaming.
* **Seam Cloud API** — The cloud service that provisions credentials, handles revocation, and provides analytics.
* **Lock Hardware** — Physical locks that communicate over BLE and/or NFC.

```
Mobile App  ──SDK Calls──▶  Seam SDK  ──HTTP──▶  Seam Cloud API
                               │                       │
                           BLE/NFC               Push Events
                               │                       │
                               ▼                       ▼
                          Lock Hardware          Seam SDK (update)
```

***

## Unlock Sequence

The following sequence shows what happens from initialization through a successful unlock:

<Steps>
  <Step title="Initialization">
    Your app calls `Seam.initialize(clientSessionToken:)` and then `activate()`.
  </Step>

  <Step title="Credential Fetch">
    The SDK automatically fetches and keeps credentials up to date by syncing with Seam Cloud.
  </Step>

  <Step title="Unlock Request">
    Your app invokes `unlock(using: credentialId)`.
  </Step>

  <Step title="Connection">
    The SDK connects to the lock via BLE or NFC.
  </Step>

  <Step title="Authentication and Confirmation">
    The lock authorizes the credential and responds.
  </Step>

  <Step title="Event Stream">
    The SDK emits `SeamUnlockEvent` values: `launched`, `grantedAccess`, and others.
  </Step>

  <Step title="Completion">
    Your app handles the events and updates its UI accordingly.
  </Step>
</Steps>

***

## Key Data Types

| Type                           | Description                                                                                                                                                                       |
| ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Client Session Token (CST)** | A short-lived token used to authenticate SDK API calls. Obtained from your server via the Seam API.                                                                               |
| **SeamCredential**             | Represents a single access credential with `id`, `name`, `location`, `expiry`, and `metadata`. Immutable snapshot; observe the `credentials` published property for live updates. |
| **SeamUnlockEvent**            | Enum describing each stage of an unlock operation (`launched`, `grantedAccess`, `timedOut`, `connectionFailed`).                                                                  |
| **SeamError**                  | Thrown for SDK setup and API-level failures. See [Error Handling](/mobile-sdks/ios/error-handling).                                                                               |
| **SeamCredentialError**        | Returned when a specific credential has an issue (expired, unsupported device, user interaction required).                                                                        |

***

## Security and Offline Support

* **Secure Transport** — All API calls use HTTPS. Lock communication is secured by the lock vendor's protocol.
* **Keychain Storage** — Tokens and other sensitive data are stored in the iOS Keychain.
* **Offline Support** — SeamSDK supports offline usage. Credentials are cached locally so that unlock attempts and recent credential data remain available during network interruptions.

***

## See Also

* [Quickstart](/mobile-sdks/ios/quickstart) — How to initialize SeamSDK and perform your first unlock.
* [Error Handling](/mobile-sdks/ios/error-handling) — How to interpret and handle errors emitted by SeamSDK.


# Error Handling
Source: https://docs.seam.co/mobile-sdks/ios/error-handling

Interpret and handle errors thrown by the Seam iOS SDK, including API setup errors (SeamError) and credential-specific errors (SeamCredentialError), using Combine or async/await.

## Overview

Errors in SeamSDK fall into two categories:

* **SeamError** — Thrown for SDK initialization, configuration, or API-level failures (for example, invalid token or no network).
* **SeamCredentialError** — Returned when a specific credential has an issue (for example, expired, unsupported device, or user action required).

Handling both types ensures your app can provide resilient, user-friendly access flows.

<Note>
  SeamComponents includes a complete reference implementation that presents UI and
  messaging for all `SeamError` and `SeamCredentialError` cases. You can use it
  as a guide or drop it in directly. See [UI Components](/mobile-sdks/ios/ui-components).
</Note>

***

## SeamError Cases

| Case                          | Description                                                                                                                                                                        |
| ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `.internetConnectionRequired` | A network connection is required to perform this operation.                                                                                                                        |
| `.initializationRequired`     | The SDK is not initialized; call `initialize(clientSessionToken:)` first.                                                                                                          |
| `.invalidClientSessionToken`  | The provided session token is malformed or invalid.                                                                                                                                |
| `.deactivationInProgress`     | A deactivation operation is already running; retry later.                                                                                                                          |
| `.alreadyInitialized`         | The SDK is already initialized; call `deactivate(deintegrate:)` before reinitializing.                                                                                             |
| `.invalidCredentialId`        | No credential matches the specified identifier.                                                                                                                                    |
| `.integrationNotFound`        | No credential matching the specified credential was found. This usually indicates that the provider integration was not included when installing SeamSDK via your package manager. |
| `.credentialErrors(errors)`   | One or more `SeamCredentialError` occurred for this credential.                                                                                                                    |

***

## SeamCredentialError Cases

| Case                               | Description                                                              |
| ---------------------------------- | ------------------------------------------------------------------------ |
| `.awaitingLocalCredential`         | Waiting for a local credential to become available.                      |
| `.expired`                         | The credential has expired and is no longer valid.                       |
| `.userInteractionRequired(action)` | The user must perform a specific action (for example, enable Bluetooth). |
| `.contactSeamSupport`              | Configuration error requiring developer attention.                       |
| `.unsupportedDevice`               | The current device is not supported.                                     |
| `.unknown`                         | An unclassified or unexpected error occurred.                            |

***

## Resolving Required User Interactions

When you encounter `.userInteractionRequired(let action)`, inspect the `action` to guide the user:

| Action                                   | Resolution                                                              |
| ---------------------------------------- | ----------------------------------------------------------------------- |
| `.completeOtpAuthorization(otpUrl: URL)` | Open the provided URL to complete OTP authorization.                    |
| `.enableInternet`                        | Prompt the user to enable internet connectivity or switch to a network. |
| `.enableBluetooth`                       | Prompt the user to enable Bluetooth in Settings or Control Center.      |
| `.grantBluetoothPermission`              | Present a permissions request dialog to grant Bluetooth access.         |
| `.appRestartRequired`                    | Ask the user to restart the app to recover from this error.             |

**Example:**

```swift theme={null}
if case .userInteractionRequired(let action) = error {
    switch action {
    case .enableBluetooth:
        showBluetoothEnableAlert()
    case .completeOtpAuthorization:
        navigateToOtpScreen()
    default:
        break
    }
}
```

***

## Handling Errors in Code

### Using Combine

```swift theme={null}
let unlockPublisher = try Seam.shared.unlock(using: credential.id)

unlockPublisher
    .sink(
        receiveCompletion: { _ in
            print("Unlock finished")
        },
        receiveValue: { event in
            // Handle unlock events
        }
    )
```

### Using async/await

```swift theme={null}
do {
    let events = try Seam.shared.unlock(using: credential.id)
    for await event in events.values {
        // Handle unlock events
    }
} catch let error as SeamError {
    // Handle SDK-level errors
}
```

### Generic Helper Function

```swift theme={null}
func handleError(_ error: Error) {
    switch error {
    case let sdkError as SeamError:
        // Map to user-friendly messages
        break
    case let credError as SeamCredentialError:
        // Prompt user based on error type
        break
    default:
        // Generic fallback
        break
    }
}
```

***

## Best Practices

* **Map errors to UI states** — Show loading, success, or error screens based on the error type.
* **Provide actionable feedback** — For credential expiration, guide the user to renew or reissue their credential.
* **Check credentials before unlocking** — If `unlock(using:)` would throw `.credentialErrors([...])`, present the top error to the user and wait until it is resolved before attempting the unlock.

***

## See Also

* [Quickstart](/mobile-sdks/ios/quickstart) — How to initialize SeamSDK and perform your first unlock.
* [Architecture](/mobile-sdks/ios/architecture) — How SeamSDK integrates with your app, cloud services, and hardware.
* [UI Components](/mobile-sdks/ios/ui-components) — SeamComponents handles error presentation automatically.


# Expo Integration
Source: https://docs.seam.co/mobile-sdks/ios/expo-integration

Configure the Seam iOS SDK for use with Expo and React Native projects that use static linking.

Static linking with React Native or Expo requires additional steps to enable dynamic framework compatibility for SeamSDK.

## Prerequisites

Before following this guide, complete the standard [Installation](/mobile-sdks/ios/installation) steps to add SeamSDK to your project via CocoaPods.

***

## Configure Dynamic Framework Support

### Step 1: Add the helper block to your Podfile

Add the following block to your `Podfile`. It detects all SeamSDK targets and converts them to dynamic frameworks at install time:

```ruby theme={null}
# ============================================================================
# Dynamic Framework Support for SeamSDK with Static Linking
# ============================================================================
SEAM_DEPENDENCIES = Set.new

def collect_dependent_targets(target, dependencies = Set.new)
  return dependencies if dependencies.include?(target.name)

  dependencies.add(target.name)
  target.dependent_targets.each do |dependent|
    collect_dependent_targets(dependent, dependencies)
  end
  dependencies
end

def setup_seam_dynamic_frameworks(installer)
  seam_target = installer.pod_targets.find { |target| target.name.start_with?('SeamSDK') }
  SEAM_DEPENDENCIES.merge(collect_dependent_targets(seam_target))

  puts "Converting to dynamic frameworks: #{SEAM_DEPENDENCIES.to_a.join(', ')}"

  installer.pod_targets.each do |pod|
    if SEAM_DEPENDENCIES.include?(pod.name)
      def pod.build_type
        Pod::BuildType.dynamic_framework
      end
    end
  end
end

def configure_seam_dynamic_frameworks(installer)
  installer.pods_project.targets.each do |target|
    if SEAM_DEPENDENCIES.include?(target.name)
      target.build_configurations.each do |config|
        config.build_settings['BUILD_LIBRARY_FOR_DISTRIBUTION'] = 'YES'
      end
    end
  end
end
# ============================================================================
```

### Step 2: Call the helpers in your post\_install hook

Call both helpers inside your `post_install` block:

```ruby theme={null}
post_install do |installer|
  setup_seam_dynamic_frameworks(installer)
  configure_seam_dynamic_frameworks(installer)
end
```

### Step 3: Run pod install

```bash theme={null}
pod install
```

***

## Avoiding File Duplication with Expo Modules

<Warning>
  If you are using an Expo module that includes a broad wildcard in its Podspec
  (for example, `s.source_files = "**/*.{h,m,mm,swift,hpp,cpp}"`), **do not**
  nest the `SeamSDK` folder inside that module's directory. Otherwise,
  CocoaPods may include the same files twice — once via your module's Podspec
  and again via the `SeamSDK.podspec` — leading to duplication or build
  conflicts.
</Warning>

**How to fix or avoid this:**

1. **Place the `SeamSDK` folder outside** your Expo module's directory structure so it is not picked up by the module's wildcard pattern.

2. If it must remain nested, **exclude it** in your Expo module's Podspec:

   ```ruby theme={null}
   s.exclude_files = "**/SeamSDK/**/*"
   ```

   This tells CocoaPods not to include the SeamSDK sources a second time.

***

## Next Steps

* [Quickstart](/mobile-sdks/ios/quickstart) — Initialize and activate the SDK, then perform your first unlock.
* [Architecture](/mobile-sdks/ios/architecture) — Understand how SeamSDK integrates with your app, the Seam Cloud, and lock hardware.


# iOS SDK
Source: https://docs.seam.co/mobile-sdks/ios/index

Build native iOS apps for mobile access and smart device management with the Seam iOS SDK, compatible with iOS 15 and above.

The Seam iOS SDK allows you to build your own mobile app that supports mobile access or smart device management.

Get started with our [integration guide](/capability-guides/mobile-access/mobile-device-sdks/index) and sample integration (coming soon!), or browse the [SDK API Reference](/mobile-sdks/ios/reference/index).

***

## Requirements

The Seam iOS SDK is compatible with apps supporting iOS 15 or above.

See the [HID list of compatible devices](https://www.hidglobal.com/mobile-access-compatible-devices) to see what phone models are compatible with the Seam SDK.

***

## Get Started

<CardGroup>
  <Card title="Installation" href="/mobile-sdks/ios/installation">
    Add the Seam iOS SDK to your project using Swift Package Manager.
  </Card>

  <Card title="Quickstart" href="/mobile-sdks/ios/quickstart">
    Get up and running with a minimal working integration in minutes.
  </Card>

  <Card title="Architecture" href="/mobile-sdks/ios/architecture">
    Understand how the SDK is structured and how it integrates with Seam.
  </Card>

  <Card title="API Reference" href="/mobile-sdks/ios/reference/index">
    Browse the complete iOS SDK API reference documentation.
  </Card>
</CardGroup>


# Installation
Source: https://docs.seam.co/mobile-sdks/ios/installation

Add the Seam iOS SDK to your project using CocoaPods or Swift Package Manager, configure Git LFS, and get your app building.

## Requirements

SeamSDK integrates with various vendor SDKs to deliver robust access control functionality. Before you begin, confirm your environment meets the following requirements:

* **iOS 15.0+**
* **[Git LFS](https://git-lfs.github.com)** (required for large binary assets)
* **[CocoaPods](https://cocoapods.org)** (if installing via CocoaPods)
* **[Swift Package Manager](https://swift.org/package-manager/)** (if installing via SPM)

<Note>
  Some vendor SDKs that SeamSDK integrates with may have additional platform requirements. The minimum iOS version and other technical prerequisites are designed to ensure compatibility across all integrated systems.
</Note>

***

## Installation

<Steps>
  <Step title="Install Git LFS">
    SeamSDK includes large binary assets (xcframeworks) tracked via Git LFS. Install and initialize Git LFS before cloning or adding the package:

    ```bash theme={null}
    brew install git-lfs
    git lfs install
    ```
  </Step>

  <Step title="Obtain SeamSDK">
    Contact your Seam representative to gain access to the SeamSDK package. The SDK is distributed as a private package.
  </Step>

  <Step title="Install the SDK">
    Choose your preferred package manager.

    <Tabs>
      <Tab title="CocoaPods">
        SeamSDK supports CocoaPods subspecs, so you can integrate only the modules you need.

        #### Full SDK Installation

        Add the following to your `Podfile`:

        ```ruby theme={null}
        platform :ios, '15.0'

        target 'YourAppName' do
          use_frameworks!

          pod 'SeamSDK', :path => 'PATH_TO_SEAM_SDK/SeamSDK.podspec'
        end
        ```

        #### Selective Module Installation

        To include only specific lock-provider integrations, specify the desired subspecs:

        ```ruby theme={null}
        pod 'SeamSDK/SeamDormakabaIntegration', :path => 'PATH_TO_SEAM_SDK/SeamSDK.podspec'
        pod 'SeamSDK/SeamLatchIntegration', :path => 'PATH_TO_SEAM_SDK/SeamSDK.podspec'
        ```

        After updating your `Podfile`, run:

        ```bash theme={null}
        pod install
        ```
      </Tab>

      <Tab title="Swift Package Manager">
        SeamSDK is also available as a **local Swift package**.

        #### Adding via Xcode

        1. Open your Xcode project.
        2. Navigate to **File > Add Packages...**
        3. Click **Add Local...**
        4. Select the folder containing `Package.swift` for SeamSDK.
        5. Choose the desired libraries:
           * `SeamSDK` — core SDK
           * `SeamDormakabaIntegration` — Dormakaba support
           * `SeamLatchIntegration` — Latch support
           * `SeamSaltoIntegration` — Salto support
           * `SeamAssaAbloyIntegration` — Assa Abloy support

        #### Adding via Package.swift

        Alternatively, add SeamSDK manually to your `Package.swift`:

        ```swift theme={null}
        dependencies: [
            .package(path: "PATH_TO_SEAM_SDK/SeamSDK")
        ],
        targets: [
            .target(
                name: "YourApp",
                dependencies: ["SeamSDK", "SeamSaltoIntegration"]
            )
        ]
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step title="Configure Xcode Settings">
    #### Disable User Script Sandboxing (CocoaPods)

    If you are using CocoaPods, disable **User Script Sandboxing** to prevent build errors related to rsync/samba:

    1. Open your project in Xcode.
    2. Select your project in the navigator.
    3. Select your target.
    4. Go to **Build Settings**.
    5. Search for "sandbox".
    6. Set **User Script Sandboxing** to **No**.
  </Step>
</Steps>

***

## Integration with Custom SDKs

If you are developing a custom SDK that depends on SeamSDK, apply the same CocoaPods or SPM patterns described above to manage dependencies and versioning.

***

## Basic Example

Once SeamSDK is installed, initialize and activate it in your app, then perform an unlock:

```swift theme={null}
import SeamSDK

let seam = Seam.initialize(clientSessionToken: CLIENT_SESSION_TOKEN)

// Activate Seam.
try await Seam.shared.activate()

// Perform unlock.
let publisher = try Seam.shared.unlock(using: Seam.shared.credentials.first!.id)
```

For full API documentation and additional examples, see the [Seam iOS SDK reference](/mobile-sdks/ios/reference/index).

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="&#x22;No such module SeamSDK&#x22; error">
    * Ensure you have properly installed the dependency via CocoaPods or SPM.
    * Run `pod install` or confirm that SPM has resolved dependencies correctly.
    * Open the `.xcworkspace` file (not `.xcodeproj`) after a CocoaPods install.
  </Accordion>

  <Accordion title="Build errors related to rsync/samba">
    Disable **User Script Sandboxing** in Build Settings as described in the **Configure Xcode Settings** step above.
  </Accordion>

  <Accordion title="Git LFS issues">
    Ensure Git LFS is installed (`brew install git-lfs`) and initialized (`git lfs install`). Re-clone or re-pull the repository after installing Git LFS.
  </Accordion>

  <Accordion title="Version conflicts">
    Run `pod update SeamSDK` (CocoaPods) or use Xcode's package resolution (**File > Packages > Resolve Package Versions**) to refresh SPM dependencies.
  </Accordion>

  <Accordion title="&#x22;Symbol Not Found&#x22; errors">
    * Confirm all dependencies are correctly installed and match the required versions.
    * Verify that `BUILD_LIBRARY_FOR_DISTRIBUTION` is set to `YES` in Build Settings.
  </Accordion>
</AccordionGroup>

For additional support, reach out in your dedicated Seam support Slack channel.


# Quickstart
Source: https://docs.seam.co/mobile-sdks/ios/quickstart

Get up and running with the Seam iOS SDK in minutes: prerequisites, installation, initialization, and your first unlock.

## Prerequisites

* iOS 15.0+
* Git LFS installed for large assets

See [Installation](/mobile-sdks/ios/installation) for full setup instructions, including CocoaPods and Swift Package Manager options.

***

## Install Git LFS

SeamSDK includes large binary assets (xcframeworks) tracked via Git LFS. Install and initialize Git LFS before cloning or adding the package:

```bash theme={null}
brew install git-lfs
git lfs install
```

## Obtain SeamSDK

Contact your Seam representative to download the private SeamSDK package.

***

## Package Manager Installation

SeamSDK provides per-lock-provider granularity — include only the modules your app needs.

<Tabs>
  <Tab title="Swift Package Manager">
    1. In Xcode, choose **File > Add Packages...**
    2. Click **Add Local...** and select the folder containing `Package.swift`.
    3. Select `SeamSDK` (core) and any provider packages (for example, `SeamDormakabaIntegration`).

    Or add to your `Package.swift`:

    ```swift theme={null}
    dependencies: [
        .package(path: "PATH_TO_SEAM_SDK/SeamSDK")
    ],
    targets: [
        .target(
            name: "YourApp",
            dependencies: ["SeamSDK", "SeamSaltoIntegration"]
        )
    ]
    ```
  </Tab>

  <Tab title="CocoaPods">
    Select your desired provider integrations (for example, `SeamDormakabaIntegration`) and the Seam core is automatically included.

    ```ruby theme={null}
    pod 'SeamSDK', :path => 'PATH_TO_SEAM_SDK/SeamSDK.podspec'
    # Optional subspecs for specific providers:
    pod 'SeamSDK/SeamDormakabaIntegration', :path => 'PATH_TO_SEAM_SDK/SeamSDK.podspec'
    pod 'SeamSDK/SeamLatchIntegration', :path => 'PATH_TO_SEAM_SDK/SeamSDK.podspec'
    ```

    ```bash theme={null}
    pod install
    ```

    After installing, disable **User Script Sandboxing** in Build Settings to avoid rsync/samba issues.
  </Tab>
</Tabs>

***

## Integration with Custom SDKs

If you build a custom SDK on top of SeamSDK, apply the same CocoaPods or SPM patterns to manage dependencies and versioning.

***

## Initialize and Activate

Use the client session token you obtain from the Seam API to bootstrap the SDK. Call `initialize` once (typically after sign-in), then call `activate()` to begin syncing credentials.

```swift theme={null}
import SeamSDK

// After obtaining your client session token:
do {
    try Seam.initialize(clientSessionToken: "USER_TOKEN")
    print("Seam SDK initialized")
} catch {
    print("Initialization failed: \(error)")
}

Task {
    do {
        try await Seam.shared.activate()
        print("Seam SDK activated")
    } catch {
        print("Activation error: \(error)")
    }
}
```

<Note>
  See `Seam.initialize(clientSessionToken:)` and `Seam.activate()` in the
  [iOS SDK reference](/mobile-sdks/ios/reference/seam) for
  full parameter details.
</Note>

***

## Perform an Unlock

Once the SDK is active, iterate over the async event stream returned by `unlock(using:)`:

```swift theme={null}
import SeamSDK

// Perform unlock and handle events:
do {
    for await event in try Seam.shared.unlock(using: "credentialId").values {
        if case .grantedAccess = event {
            print("Unlocked successfully")
        }
    }
} catch {
    print("Unlock error: \(error)")
}
```

<Note>
  See `Seam.unlock(using:timeout:)` and the [Error Handling](/mobile-sdks/ios/error-handling)
  guide for details on error types and recovery flows.
</Note>

***

## Troubleshooting

* **No such module 'SeamSDK':** Ensure dependencies are installed via CocoaPods or SPM and run `pod install` or resolve SPM packages in Xcode.
* **rsync/samba build errors:** Disable **User Script Sandboxing** in Build Settings.
* **Git LFS errors:** Verify Git LFS is installed and `git lfs install` has been run.
* **Version conflicts:** Update your Pod or SPM dependencies to the latest SeamSDK version.

For additional support, reach out via your dedicated Seam support Slack channel or visit the [Seam Console](https://console.seam.co).

***

## Next Steps

* [Architecture](/mobile-sdks/ios/architecture) — How SeamSDK integrates with your app, cloud services, and hardware.
* [Error Handling](/mobile-sdks/ios/error-handling) — How to interpret and handle errors emitted by SeamSDK.
* [UI Components](/mobile-sdks/ios/ui-components) — Drop-in SwiftUI components for mobile key flows.


# Extensions
Source: https://docs.seam.co/mobile-sdks/ios/reference/extensions

Public extensions on String and PKAutomaticPassPresentationSuppressionResult provided by SeamSDK.

> **Interim hand-authored reference.** This page is authored from the SeamSDK public Swift sources. See the [reference overview](/mobile-sdks/ios/reference) for context.

## Overview

SeamSDK adds two public extensions to types outside the SDK's own namespace. Both are minor utility conformances.

***

## `extension String`

```swift theme={null}
extension String: @retroactive Error { }
```

Conforms `String` to `Error` retroactively. This allows string literals to be used as throwable error values in SDK-internal bridging code. It is a low-level utility conformance with no public API surface beyond what `Error` already provides.

***

## `extension PKAutomaticPassPresentationSuppressionResult`

Defined in `PassKit`. SeamSDK adds a `CustomStringConvertible` conformance so that suppression result values produce human-readable descriptions in logs.

```swift theme={null}
extension PKAutomaticPassPresentationSuppressionResult: @retroactive CustomStringConvertible {
    public var description: String { get }
}
```

### `description`

Returns a human-readable name for the suppression result.

| Value                | `description`           |
| -------------------- | ----------------------- |
| `.notSupported`      | `"NotSupported"`        |
| `.alreadyPresenting` | `"AlreadyPresenting"`   |
| `.denied`            | `"Denied"`              |
| `.cancelled`         | `"Cancelled"`           |
| `.success`           | `"Success"`             |
| unknown future cases | `"Unknown(<rawValue>)"` |

This conformance is used internally by SeamSDK to log Apple Wallet pass-suppression state during unlock operations. You do not need to interact with it directly.


# iOS SDK API Reference
Source: https://docs.seam.co/mobile-sdks/ios/reference/index

Public API surface of the Seam iOS SDK.

<CardGroup>
  <Card title="Seam" icon="swift" href="/mobile-sdks/ios/reference/seam">
    Class — Manages the Seam SDK lifecycle: initialization, activation, credential sync, unlock operations, and cleanup.
  </Card>

  <Card title="SeamCredential" icon="swift" href="/mobile-sdks/ios/reference/seam-credential">
    Struct — Represents a Seam access credential for display, selection, and management.
  </Card>

  <Card title="SeamCredentialError" icon="swift" href="/mobile-sdks/ios/reference/seam-credential-error">
    Enum — Credential-specific errors returned by the Seam SDK when a credential can’t be used.
  </Card>

  <Card title="SeamError" icon="swift" href="/mobile-sdks/ios/reference/seam-error">
    Enum — Errors thrown by `Seam` for initialization, usage, and credential-precondition failures.
  </Card>

  <Card title="SeamSDKService" icon="swift" href="/mobile-sdks/ios/reference/seam-sdk-service">
    Class — Class reference
  </Card>

  <Card title="SeamUnlockEvent" icon="swift" href="/mobile-sdks/ios/reference/seam-unlock-event">
    Enum — Represents the stages of a door unlock operation performed by the Seam SDK.
  </Card>

  <Card title="SeamUnlockProximity" icon="swift" href="/mobile-sdks/ios/reference/seam-unlock-proximity">
    Enum — Defines the **required proximity** for an unlock attempt.
  </Card>
</CardGroup>


# Seam
Source: https://docs.seam.co/mobile-sdks/ios/reference/seam

Manages the Seam SDK lifecycle: initialization, activation, credential sync, unlock operations, and cleanup.

## Overview

```swift theme={null}
final class Seam
```

Manages the Seam SDK lifecycle: initialization, activation, credential sync, unlock operations, and cleanup.

***

## Instance Properties

### `credentials`

A published list of current credentials, automatically synchronized in the background. Subscribe to updates to refresh your UI or business logic.

```swift theme={null}
@Published var credentials: [SeamCredential] { get set }
```

### `isActive`

A published Boolean indicating whether the SDK is active. Use this to enable or disable UI or logic based on the SDK’s activation state.

```swift theme={null}
@Published var isActive: Bool { get set }
```

***

## Instance Methods

### `activate()`

Starts the SDK to begin credential synchronization and processing.

```swift theme={null}
func activate() async throws
```

### `deactivate(deintegrate:)`

Stops the SDK and releases resources, optionally removing device association.

```swift theme={null}
func deactivate(deintegrate: Bool = false) async
```

**Parameters**

| Parameter     | Description                                                                                                       |
| ------------- | ----------------------------------------------------------------------------------------------------------------- |
| `deintegrate` | If `true`, performs a full deintegration; if `false`, logs out and retains device endpoints. Defaults to `false`. |

### `refresh()`

Requests the latest credential list and updates the published `credentials` property.

```swift theme={null}
func refresh() async throws -> [SeamCredential]
```

### `unlock(using:proximity:timeout:)`

Unlocks a door or device using the given credential ID.

```swift theme={null}
func unlock(using credentialId: String, proximity: SeamUnlockProximity? = nil, timeout: TimeInterval = 10.0) throws -> AnyPublisher<SeamUnlockEvent, Never>
```

**Parameters**

| Parameter      | Description                                                                                                                                            |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `credentialId` | The identifier of the credential to use for unlocking.                                                                                                 |
| `proximity`    | The **required proximity** for this unlock attempt. If `nil`, the SDK uses the credential’s default (the first value in `supportedUnlockProximities`). |
| `timeout`      | The maximum time, in seconds, to wait for the unlock operation. Defaults to 10.                                                                        |

***

## Type Properties

### `shared`

The shared singleton instance of `Seam`.

```swift theme={null}
static let shared: Seam
```

***

## Type Methods

### `initialize(clientSessionToken:)`

Sets up the SDK using the provided client session token.

```swift theme={null}
static func initialize(clientSessionToken: String) throws
```

**Parameters**

| Parameter            | Description                                     |
| -------------------- | ----------------------------------------------- |
| `clientSessionToken` | Optional - A valid client session token string. |


# SeamCredential
Source: https://docs.seam.co/mobile-sdks/ios/reference/seam-credential

Represents a Seam access credential for display, selection, and management.

## Overview

```swift theme={null}
struct SeamCredential
```

Represents a Seam access credential for display, selection, and management.

***

## Initializers

### `init(id:isManaged:name:location:providerName:expiry:cardNumber:code:supportedUnlockProximities:errors:)`

```swift theme={null}
init(id: String, isManaged: Bool, name: String, location: String, providerName: String?, expiry: Date?, cardNumber: String?, code: String?, supportedUnlockProximities: [SeamUnlockProximity], errors: [SeamCredentialError])
```

***

## Instance Properties

### `cardNumber`

The card number associated with this credential, if any.

```swift theme={null}
let cardNumber: String?
```

### `code`

The code associated with this credential, if any.

```swift theme={null}
let code: String?
```

### `errors`

The list of errors currently affecting this credential.

```swift theme={null}
let errors: [SeamCredentialError]
```

### `expiry`

The expiration date of the credential, if available.

```swift theme={null}
let expiry: Date?
```

### `id`

The unique identifier for this credential.

```swift theme={null}
let id: String
```

### `isManaged`

Indicates whether this credential was created and managed by the Seam API (`true`) or was discovered directly through the provider integration (`false`).

```swift theme={null}
let isManaged: Bool
```

### `location`

The credential’s associated location.

```swift theme={null}
let location: String
```

### `name`

The display name associated with this credential.

```swift theme={null}
let name: String
```

### `providerName`

The third party provider (latch, salto space) associated with this credential, if any.

```swift theme={null}
let providerName: String?
```

### `supportedUnlockProximities`

The set of proximity levels this credential supports, ordered by preference.

```swift theme={null}
let supportedUnlockProximities: [SeamUnlockProximity]
```


# SeamCredentialError
Source: https://docs.seam.co/mobile-sdks/ios/reference/seam-credential-error

Credential-specific errors returned by the Seam SDK when a credential can’t be used.

## Overview

```swift theme={null}
enum SeamCredentialError
```

Credential-specific errors returned by the Seam SDK when a credential can’t be used.

***

## Enumeration Cases

### `SeamCredentialError.awaitingLocalCredential`

The system is waiting for a local credential to become available.

```swift theme={null}
case awaitingLocalCredential
```

### `SeamCredentialError.contactSeamSupport`

Configuration error requiring developer attention.

```swift theme={null}
case contactSeamSupport
```

### `SeamCredentialError.expired`

The credential has expired and is no longer valid.

```swift theme={null}
case expired
```

### `SeamCredentialError.unknown`

An unclassified or unexpected credential error occurred.

```swift theme={null}
case unknown
```

### `SeamCredentialError.unsupportedDevice`

The current device is not supported.

```swift theme={null}
case unsupportedDevice
```

### `SeamCredentialError.userInteractionRequired(_:)`

User interaction is required to resolve the credential issue.

```swift theme={null}
case userInteractionRequired(RequiredUserInteraction)
```

**Parameters**

| Parameter                 | Description                                                   |
| ------------------------- | ------------------------------------------------------------- |
| `userInteractionRequired` | Specifies the action the user must take to resolve the error. |

***

## Enumerations

### `SeamCredentialError.RequiredUserInteraction`

Detailed actions that users must take to resolve a credential issue.

```swift theme={null}
enum RequiredUserInteraction
```


# SeamError
Source: https://docs.seam.co/mobile-sdks/ios/reference/seam-error

Errors thrown by `Seam` for initialization, usage, and credential-precondition failures.

## Overview

```swift theme={null}
enum SeamError
```

Errors thrown by `Seam` for initialization, usage, and credential-precondition failures.

***

## Enumeration Cases

### `SeamError.alreadyInitialized`

SDK is already initialized; call `deactivate(deintegrate:)` before reinitializing.

```swift theme={null}
case alreadyInitialized
```

### `SeamError.credentialErrors(_:)`

One or more credential-specific errors occurred.

```swift theme={null}
case credentialErrors([SeamCredentialError])
```

**Parameters**

| Parameter | Description                                                        |
| --------- | ------------------------------------------------------------------ |
| `errors`  | List of `SeamCredentialError` values for the specified credential. |

### `SeamError.deactivationInProgress`

A deactivation operation is already in progress.

```swift theme={null}
case deactivationInProgress
```

### `SeamError.initializationRequired`

SDK has not been initialized; call `initialize(clientSessionToken:)` first.

```swift theme={null}
case initializationRequired
```

### `SeamError.integrationNotFound`

No credential matching the specified credential was found. This usually indicates that the provider integration wasn’t included when installing the Seam SDK via your package manager.

```swift theme={null}
case integrationNotFound
```

### `SeamError.internetConnectionRequired`

Network connection is required to perform this operation.

```swift theme={null}
case internetConnectionRequired
```

### `SeamError.invalidClientSessionToken`

Provided client session token is malformed or invalid.

```swift theme={null}
case invalidClientSessionToken
```

### `SeamError.invalidCredentialId`

No credential matching the specified identifier was found.

```swift theme={null}
case invalidCredentialId
```


# SeamSDKService
Source: https://docs.seam.co/mobile-sdks/ios/reference/seam-sdk-service

Class reference

## Overview

```swift theme={null}
@objc(SeamSDKService) final class SeamSDKService
```

***

## Instance Properties

### `credentials`

```swift theme={null}
@objc var credentials: NSArray { get }
```

### `isActive`

```swift theme={null}
@objc var isActive: NSNumber { get }
```

***

## Instance Methods

### `activate(_:)`

```swift theme={null}
@objc(activateWithCompletion:) func activate(_ completion: @escaping (NSNumber, NSString?) -> Void)
```

### `credentialsPublisher()`

```swift theme={null}
@objc(credentialsPublisher) func credentialsPublisher() -> AnyObject
```

### `isActivePublisher()`

```swift theme={null}
@objc(isActivePublisher) func isActivePublisher() -> AnyObject
```

### `refresh(_:)`

```swift theme={null}
@objc(refreshWithCompletion:) func refresh(_ completion: @escaping (NSNumber, NSArray?) -> Void)
```

### `unlock(credentialId:timeout:)`

```swift theme={null}
@objc(unlockWithCredentialId:timeout:) func unlock(credentialId: NSString, timeout: NSNumber) -> AnyObject
```

***

## Type Properties

### `shared`

```swift theme={null}
@objc(shared) static let shared: SeamSDKService
```

***

## Type Methods

### `initialize(clientSessionToken:)`

```swift theme={null}
@objc(initializeWithClientSessionToken:) class func initialize(clientSessionToken: NSString) -> NSNumber
```


# SeamUnlockEvent
Source: https://docs.seam.co/mobile-sdks/ios/reference/seam-unlock-event

Represents the stages of a door unlock operation performed by the Seam SDK.

## Overview

```swift theme={null}
enum SeamUnlockEvent
```

Represents the stages of a door unlock operation performed by the Seam SDK.

***

## Enumeration Cases

### `SeamUnlockEvent.connectionFailed(debugDescription:)`

The unlock operation failed to connect.

```swift theme={null}
case connectionFailed(debugDescription: String?)
```

**Parameters**

| Parameter          | Description                                       |
| ------------------ | ------------------------------------------------- |
| `debugDescription` | Optional debug message providing failure details. |

### `SeamUnlockEvent.grantedAccess`

The lock granted access; entry is allowed.

```swift theme={null}
case grantedAccess
```

### `SeamUnlockEvent.launched`

The unlock operation has started scanning for a lock.

```swift theme={null}
case launched
```

### `SeamUnlockEvent.timedOut`

The unlock operation timed out.

```swift theme={null}
case timedOut
```


# SeamUnlockProximity
Source: https://docs.seam.co/mobile-sdks/ios/reference/seam-unlock-proximity

Defines the **required proximity** for an unlock attempt.

## Overview

```swift theme={null}
enum SeamUnlockProximity
```

Defines the **required proximity** for an unlock attempt.

***

## Enumeration Cases

### `SeamUnlockProximity.nearby`

Requires the user to be **within a few meters** of the lock/reader.

```swift theme={null}
case nearby
```

### `SeamUnlockProximity.remote`

**No proximity requirement**; operation may be performed via network/relay.

```swift theme={null}
case remote
```

### `SeamUnlockProximity.touch`

Requires the user’s mobile device to be **physically touching** the lock hardware/reader.

```swift theme={null}
case touch
```


# Custom Integration
Source: https://docs.seam.co/mobile-sdks/ios/ui-components/custom-integration

Build fully custom UI experiences using SeamComponents building blocks, dependency injection, and the SeamServiceProtocol.

While `SeamAccessView` is the fastest way to integrate mobile keys, many apps need more control over layout, navigation, or data flow. SeamComponents supports full customization through composable building blocks and protocol-based dependency injection.

***

## Building Blocks

SeamComponents exports a set of reusable, domain-specific SwiftUI views:

| Component                 | Description                                                                                                                                                    |
| ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **`SeamAccessView`**      | All-in-one mobile access experience: credential fetching, display, unlocking, and error handling.                                                              |
| **`SeamCredentialsView`** | Coordinator/container view that manages sheet presentation, selection, pull-to-refresh, and empty state handling. Delegates unlocking to `SeamUnlockCardView`. |
| **`SeamCredentialGrid`**  | Pure, stateless subview for displaying credentials in a grid layout.                                                                                           |
| **`SeamCredentialTable`** | Pure, stateless subview for displaying credentials in a list/table format.                                                                                     |
| **`SeamKeyCardView`**     | Displays an individual credential as a visually rich key card with status and error overlays. Supports custom `SeamAccessCredentialErrorStyle`.                |
| **`SeamUnlockCardView`**  | Manages all unlock functionality for a selected credential, including progress and error feedback.                                                             |

Each component works with a single service wrapper conforming to `SeamServiceProtocol`, so you can inject live or mock implementations as needed.

***

## Example: Custom Key List and Unlock Flow

Create and own a `SeamCredentialsViewModel`, then pass it to the credential views. The coordinator views handle selection, navigation, refresh, and empty state automatically.

```swift theme={null}
import SeamComponents

struct CustomKeysScreen: View {
    @StateObject var viewModel = SeamCredentialsViewModel(seam: SeamService())

    var body: some View {
        VStack {
            // Coordinator view with grid layout: handles selection, refresh,
            // empty state UI, and unlock sheet presentation automatically.
            SeamCredentialsGridView(viewModel: viewModel)

            // Or use table layout:
            // SeamCredentialsTableView(viewModel: viewModel)

            // If you want full control over selection and navigation,
            // compose with the pure subviews instead:
            // SeamCredentialGrid(
            //     credentials: viewModel.credentials,
            //     selectedId: viewModel.selectedCredentialId,
            //     onSelect: viewModel.select
            // )

            // When using pure subviews, manage empty states and unlock
            // sheet presentation yourself.
            if let selectedId = viewModel.selectedCredentialId {
                SeamUnlockCardView(
                    viewModel: SeamUnlockCardViewModel(
                        credentialId: selectedId,
                        service: viewModel.service
                    )
                )
            }
        }
    }
}
```

<Tip>
  Use the coordinator views (`SeamCredentialsGridView`, `SeamCredentialsTableView`) for
  a full-featured experience — empty states, selection, refresh, and unlock presentation
  are all handled for you.
</Tip>

***

## Dependency Injection and Mocks

SeamComponents uses a single wrapper `ObservableObject` API:

| Type                      | Role                                                                                    |
| ------------------------- | --------------------------------------------------------------------------------------- |
| **`SeamServiceProtocol`** | Protocol that your UI and view models depend on.                                        |
| **`SeamService`**         | Production implementation that mirrors `Seam` state and forwards commands.              |
| **Mock conformers**       | Custom classes (e.g., `MockSeamService`) that you fully control for tests and previews. |

### Live Usage

```swift theme={null}
let service: SeamServiceProtocol = SeamService()
let vm = SeamCredentialsViewModel(seam: service)
```

### Mock Usage (Tests and Previews)

```swift theme={null}
final class MockSeamService: SeamServiceProtocol {
    @Published private(set) var credentials: [SeamAccessCredential] = []
    @Published private(set) var isActive: Bool = false

    var isActivePublisher: AnyPublisher<Bool, Never> { $isActive.eraseToAnyPublisher() }
    var credentialsPublisher: AnyPublisher<[SeamAccessCredential], Never> { $credentials.eraseToAnyPublisher() }

    func initialize(clientSessionToken: String?) throws {}
    func activate() async throws { isActive = true }
    @discardableResult
    func refresh() async throws -> [SeamAccessCredential] { credentials }
    func unlock(using credentialId: String, timeout: TimeInterval) throws -> AnyPublisher<SeamAccessUnlockEvent, Never> {
        Just(.launched).append(Just(.grantedAccess)).eraseToAnyPublisher()
    }
    func deactivate(deintegrate: Bool) async { isActive = false }
}

// Inject into your view model
let mock = MockSeamService()
let vm = SeamCredentialsViewModel(seam: mock)
```

```swift theme={null}
#Preview {
    CustomKeysScreen()
}
```

This design keeps your UI and business logic independent of concrete SDK types, while remaining iOS 16-friendly.

***

## Custom Styling and Extensibility

All views are built with SwiftUI best practices — system fonts, SF Symbols, and color styles. You can:

* Override styles using environment modifiers.
* Add your own accessibility labels and localization.
* Compose SeamComponents with your own views and navigation.
* Use `SeamAccessCredentialErrorStyle` to override error/status badge appearance, icons, and messaging in key card and unlock views.

See [Customizing Appearance](/mobile-sdks/ios/ui-components/customizing-appearance) for the full theming API.

***

## Handling Unlock Events and Errors

The unlock stream emits `SeamAccessUnlockEvent` values and never fails. Available events:

| Event                                 | Description                                    |
| ------------------------------------- | ---------------------------------------------- |
| `launched`                            | The unlock process started (scanning/probing). |
| `grantedAccess`                       | Access granted by the lock (success).          |
| `timedOut`                            | The attempt timed out without success.         |
| `connectionFailed(debugDescription:)` | Connection or protocol negotiation failed.     |

Subscribe to these events to show custom notifications, present modals, or log analytics.

### Credential Errors and Presentation

Per-credential issues surface via each credential's `errors: [SeamCredentialError]` array. Use `SeamAccessCredentialErrorStyle` to present badges, messages, and actions consistently across key cards and unlock views.

**Rendering an error badge on a key card:**

```swift theme={null}
let style = SeamAccessCredentialErrorStyle.default
let theme = SeamTheme.default

SeamKeyCardView(credential: credential, style: style)
    .overlay(alignment: .bottomLeading) {
        if let error = credential.errors.first {
            HStack(spacing: 8) {
                Image(systemName: style.systemIcon(error, theme: theme))
                Text(style.message(error))
            }
            .padding(8)
        }
    }
```

**Offering a corrective action:**

```swift theme={null}
if let error = credential.errors.first,
   let actionTitle = style.primaryActionTitle(error) {
    Button(actionTitle) {
        style.primaryAction(error)() // e.g., open Settings or OTP URL
    }
}
```

<Tip>
  The `errors` array is ordered by severity. Show the first item as the primary badge
  on a key card, and reveal details or actions on tap.
</Tip>

<Note>
  If `unlock(using:)` throws `.credentialErrors([...])`, present the top error using
  your style and avoid starting the unlock until it is resolved.
</Note>

**Credential error types:**

* `awaitingLocalCredential` — Waiting for a local credential to become available.
* `expired` — The credential has expired and cannot be used.
* `userInteractionRequired(action)` — The user must perform a specific action.
* `contactSeamSupport` — Configuration error requiring developer attention.
* `unsupportedDevice` — The current device is not supported for this credential.
* `unknown` — An unclassified or unexpected issue occurred.

**Possible `userInteractionRequired` actions:**

* `completeOtpAuthorization(otpUrl:)` — Open the provided URL to complete OTP authorization.
* `enableInternet` — Prompt the user to enable internet connectivity.
* `enableBluetooth` — Prompt the user to turn on Bluetooth.
* `grantBluetoothPermission` — Direct the user to grant Bluetooth permission.
* `appRestartRequired` — Ask the user to restart the app.

***

## See Also

* [Getting Started](/mobile-sdks/ios/ui-components) — Add SeamComponents to your project and display your first key.
* [Customizing Appearance](/mobile-sdks/ios/ui-components/customizing-appearance) — Override colors, fonts, and card styles using the SeamTheme system.
* [Error Handling](/mobile-sdks/ios/error-handling) — SDK-level error types and recovery patterns.


# Customizing Appearance
Source: https://docs.seam.co/mobile-sdks/ios/ui-components/customizing-appearance

Customize every aspect of SeamComponents appearance — including colors, fonts, and status indicators — using the composable SeamTheme system.

## Overview

SeamComponents provides a flexible theming system that lets you fully customize the look and feel of all UI elements. This enables easy white-labeling, brand alignment, and accessibility support.

Theming is accomplished by:

1. Building a `SeamTheme` value that groups together colors and fonts.
2. Injecting it into your SwiftUI view hierarchy via `.environment(\.seamTheme, ...)`.

All SeamComponents — `SeamAccessView`, `SeamKeyCardView`, `SeamCredentialsView`, and `SeamUnlockCardView` — automatically use the active theme from the environment.

<Note>
  If you do not inject a theme, SeamComponents use `SeamTheme.default`, which
  matches the native iOS style.
</Note>

***

## Why Theming Matters

Applying a custom theme lets you:

* **White-label your app** by replacing default colors and fonts with your brand's identity.
* **Align with brand guidelines** for a consistent and professional appearance.
* **Support accessibility features** such as Dynamic Type and high-contrast modes.

***

## Quick Start

### Basic Custom Theme

Override the accent color and large title font:

```swift theme={null}
// Start from the default theme and override specific roles.
let myTheme = SeamTheme.default
    .with(colors: .default.with(accent: .orange))
    .with(fonts: .default.with(largeTitle: .system(size: 36, weight: .bold)))

// Apply to your view hierarchy:
SeamAccessView()
    .environment(\.seamTheme, myTheme)
```

### Partial Customization

Override only what you need — everything else falls back to the default:

```swift theme={null}
let partialTheme = SeamTheme.default
    .with(colors: .default.with(accent: .green))
    .with(fonts: .default.with(body: .system(size: 16, weight: .medium)))

SeamAccessView()
    .environment(\.seamTheme, partialTheme)
```

### Key Card Customization

Customize the key card's gradient, accent color, and corner radius:

```swift theme={null}
let customTheme = SeamTheme.default.with(
    keyCard: .default.with(
        backgroundGradient: [Color.white, Color.blue],
        accentColor: .blue,
        cornerRadius: 16
    )
)

SeamAccessView()
    .environment(\.seamTheme, customTheme)
```

***

## Design Tips

* **Accent drives actions:** The `colors.accent` role powers primary buttons and highlights.
* **Prefer dynamic colors:** Use light/dark-aware colors so your theme looks great in both appearances.
* **Keep fonts accessible:** Favor Dynamic Type-friendly fonts; avoid locking sizes unless necessary.

***

## Theme Scope and Environment

Themes can be applied globally or scoped to a portion of your UI:

* **Global theming:** Apply a theme at the root of your app's view hierarchy to affect all SeamComponents.
* **Subtree theming:** Apply a theme to a specific view or container to override it only for that subtree.

```swift theme={null}
// Global — applies to all SeamComponents in the app
MyRootView()
    .environment(\.seamTheme, myTheme)

// Scoped — applies only within this sheet
SeamAccessView()
    .environment(\.seamTheme, specialTheme)
```

Because theming is driven by SwiftUI's environment system, updating the theme dynamically will automatically update all affected SeamComponents.

***

## FAQ

**Q: What happens if I don't provide a theme?**

All SeamComponents will use the built-in default theme, which matches the native iOS style.

**Q: Can I override only some colors or fonts?**

Yes. `SeamTheme` is fully composable — provide only the values you want to override; everything else falls back to the default.

**Q: Does theming work with accessibility features?**

Yes. All theme values work with Dynamic Type, high-contrast settings, and other accessibility features.

**Q: Can I change the theme at runtime?**

Yes. Because theming is driven by SwiftUI's environment system, updating the injected value dynamically will automatically update all affected SeamComponents.

***

## See Also

* [Getting Started](/mobile-sdks/ios/ui-components) — Add SeamComponents to your project and display your first key.
* [Custom Integration](/mobile-sdks/ios/ui-components/custom-integration) — Compose building blocks and inject mock services for full UI control.


# UI Components
Source: https://docs.seam.co/mobile-sdks/ios/ui-components/index

SeamComponents is a themeable SwiftUI library for mobile access. Add fully-featured key flows to your app with two lines of code, or compose custom experiences from reusable building blocks.

## What is SeamComponents?

SeamComponents is a themeable SwiftUI component library designed to work hand-in-hand with the [Seam iOS SDK](/mobile-sdks/ios/installation). It provides:

* **An all-in-one view** — `SeamAccessView` handles key retrieval, credential display, unlocking, error handling, and user interactions with two lines of code.
* **Composable building blocks** — `SeamCredentialsView`, `SeamKeyCardView`, and `SeamUnlockCardView` let you build custom experiences that fit your app's design.
* **Flexible theming** — Override colors, fonts, and card appearance globally or per-subtree using the `SeamTheme` environment system.
* **Protocol-based service** — `SeamServiceProtocol` makes it easy to inject live, mock, or preview implementations without changing your UI code.
* **Accessibility first** — All components are built with accessibility as a first-class feature.

SeamComponents is ideal for hotels, multi-family properties, or any app integrating digital access.

***

## Prerequisites

* **iOS 15.0+**
* Add to your `Info.plist`:
  * `NSBluetoothAlwaysUsageDescription`
* **Optional:** Request the `com.apple.developer.passkit.pass-presentation-suppression` entitlement to prevent Apple Wallet from appearing during BLE/NFC scans.

***

## Getting Started

<Steps>
  <Step title="Add SeamComponents to your project">
    Add SeamComponents using Swift Package Manager:

    1. Open your Xcode project.
    2. Go to **File > Add Packages...**
    3. Enter the package URL:
       ```
       https://github.com/seamapi/seam-components-swift
       ```
    4. Choose the latest version and add it to your app target.
  </Step>

  <Step title="Initialize the Seam SDK">
    Before using any SeamComponents UI, initialize and activate the Seam SDK with your client session token:

    ```swift theme={null}
    import SeamSDK

    do {
        try Seam.initialize(clientSessionToken: "YOUR_TOKEN")
        Task { try await Seam.shared.activate() }
    } catch {
        // Handle initialization/activation errors (e.g., show an alert)
    }
    ```

    Call `initialize` after sign-in (or app launch), then `activate()` to begin syncing credentials.

    See [Quickstart](/mobile-sdks/ios/quickstart) for full initialization details.
  </Step>

  <Step title="Add the all-in-one access view">
    For the easiest integration, add `SeamAccessView` to your SwiftUI view hierarchy:

    ```swift theme={null}
    import SeamComponents

    var body: some View {
        SeamAccessView()
    }
    ```

    That's it. `SeamAccessView` handles key retrieval, credential display, unlocking, error handling, and user interactions automatically.
  </Step>
</Steps>

***

## Theming and Appearance

SeamComponents supports full white-labeling via the `SeamTheme` environment system. Override colors, fonts, and card appearance by injecting a custom theme:

```swift theme={null}
import SeamComponents

let customTheme = SeamTheme.default.with(
    keyCard: .default.with(
        backgroundGradient: [Color.white, Color.blue],
        accentColor: .blue,
        cornerRadius: 16
    ),
    fonts: .default.with(
        title: .system(size: 22, weight: .bold)
    )
)

var body: some View {
    SeamAccessView()
        .environment(\.seamTheme, customTheme)
}
```

<Note>
  If you do not inject a theme, SeamComponents use `SeamTheme.default`, which
  matches the native iOS style.
</Note>

The `SeamTheme` API uses a builder pattern with nested `.with(...)` calls. Override only the parts you need — everything else falls back to the default. Theming can be applied globally at your app root or scoped to any view subtree.

See [Customizing Appearance](/mobile-sdks/ios/ui-components/customizing-appearance) for details and advanced examples.

***

## Custom Integration

If you need more control over layout, navigation, or data flow, compose your own UI using SeamComponents building blocks:

* **`SeamCredentialsView`** — Coordinator view that manages selection, pull-to-refresh, and empty state handling.
* **`SeamCredentialGrid` / `SeamCredentialTable`** — Pure, stateless subviews for displaying credentials in grid or list format.
* **`SeamKeyCardView`** — Displays an individual credential as a visually rich key card with status and error overlays.
* **`SeamUnlockCardView`** — Manages all unlock functionality for a selected credential, including progress and error feedback.

Inject a live `SeamService` or a mock conforming to `SeamServiceProtocol` for previews and tests.

See [Custom Integration](/mobile-sdks/ios/ui-components/custom-integration) for code samples and advanced patterns.

***

## What's Next

<CardGroup>
  <Card title="Customizing Appearance" href="/mobile-sdks/ios/ui-components/customizing-appearance">
    Override colors, fonts, and card styles using the SeamTheme system.
  </Card>

  <Card title="Custom Integration" href="/mobile-sdks/ios/ui-components/custom-integration">
    Compose building blocks and inject mock services for full UI control.
  </Card>
</CardGroup>


# Quick Start
Source: https://docs.seam.co/quickstart

Seam provides a unified API to connect and control IoT devices, such as smart locks, thermostats, cameras, and sensors. This guide walks you through granting your first access with the Seam API.

<Info>
  **Building with an AI coding assistant?** Connect the [Seam MCP
  Server](developer-tools/seam-mcp) to give your assistant direct access to
  Seam documentation — setup takes under a minute, no API keys needed.
</Info>

## Step 1: Connect Devices

To get started with Seam, first connect a set of devices.

1. In a web browser, go to [Seam Console](/core-concepts/seam-console/index) at [https://console.seam.co/](https://console.seam.co/) and create an account.\
   Once you have logged in to Seam Console, you are working in the default [sandbox workspace](/core-concepts/workspaces/index#sandbox-workspaces).

2. In the upper-right corner of the **Devices** page, click **Add Devices**.

   Seam Console displays an authorization flow (known as a [Connect Webview](/core-concepts/connect-webviews/index)) that enables you to connect a device account to Seam.

3. In the Connect Webview, click **Continue**.

4. In the manufacturer list, select [**August**](https://august.com/).

5. When prompted, type the following sample (sandbox) credentials:
   * **Email:** `jane@example.com`
   * **Password:** `1234`

6. Click **Submit**.

7. When prompted for a two-factor authentication (2FA) method, select **Email**.

8. In the **Two Factor Code** field, type `123456` and then click **Submit and Continue**.

Once authorized, the devices associated with this test account appear in your workspace. These are shared sandbox credentials; for the test accounts that work with every manufacturer Seam supports, see [Test Accounts](/developer-tools/test-accounts).

## Step 2: Get an API Key and SDK

To control the devices that you connected in [Step 1](#step-1-connect-devices), you must create an API key and install the Seam SDK in the programming language of your choice.

### Create an API Key

1. In the top navigation pane of [Seam Console](https://console.seam.co/), click **Developer**.
2. In the left navigation pane, click **API Keys**.
3. In the upper-right corner of the **API Keys** page, click **Add API Key**.
4. In the **Add API Key** dialog, type a name for your new API key and then click **Create API Key**.
5. Copy the newly-created API key and store it for future use.

### Install the Seam SDK

Install one of the Seam SDKs in the programming language of your choice.

Seam provides client libraries for many languages, such as JavaScript, Python, Ruby, PHP, and others, as well as a Postman collection and [OpenAPI](https://connect.getseam.com/openapi.json) spec.

* JavaScript / TypeScript ([npm](https://www.npmjs.com/package/seam), [GitHub](https://github.com/seamapi/javascript))
* Python ([pip](https://pypi.org/project/seam/), [GitHub](https://github.com/seamapi/python))
* Ruby Gem ([rubygem](https://rubygems.org/gems/seam), [GitHub](https://github.com/seamapi/ruby))
* PHP ([packagist](https://packagist.org/packages/seamapi/seam), [GitHub](https://github.com/seamapi/php))
* C# ([nuget](https://www.nuget.org/packages/Seam), [GitHub](https://github.com/seamapi/csharp))

<Tabs>
  <Tab title="JavaScript">
    ```bash theme={null}
    npm i seam
    ```
  </Tab>

  <Tab title="Python">
    ```bash theme={null}
    pip install seam
    # For some development environments, use pip3 in this command instead of pip.
    ```
  </Tab>

  <Tab title="Ruby">
    ```bash theme={null}
    bundle add seam
    ```
  </Tab>

  <Tab title="PHP">
    ```bash theme={null}
    composer require seamapi/seam
    ```
  </Tab>

  <Tab title="C#">
    Install using [nuget](https://www.nuget.org/packages/Seam).
  </Tab>
</Tabs>

## Step 3: Grant Access

Grant your first access! You'll create an [Access Grant](./use-cases/granting-access/index)—the default and recommended way to grant a person access to any physical space through Seam—and get back a PIN code that your user could enter on the lock's keypad.

To start, open a terminal window and export your API key as an environment variable.

```sh theme={null}
$ export SEAM_API_KEY=seam_test2bMS_94SrGUXuNR2JmJkjtvBQDg5c
```

The Seam SDK that you have installed automatically uses this API key once you have exported it.

Next, use the following code to retrieve one of the devices that you connected in [Step 1](#step-1-connect-devices), inspect the supported capabilities of the device, and create an Access Grant that issues a PIN code on the lock:

**Code:**

<CodeGroup>
  ```javascript JavaScript theme={null}
  import { Seam } from 'seam'

  const seam = new Seam() // Seam automatically uses your exported SEAM_API_KEY.

  // Retrieve all devices, filtered by manufacturer,
  // which is one of several filters that list() supports.
  const allAugustLocks = await seam.devices.list({ manufacturer: 'august' })

  // Select the first device as an example.
  const frontDoor = allAugustLocks[0]

  // Confirm that the device can program access codes.
  // You're using a capability flag here!
  if (frontDoor.can_program_online_access_codes) {
    // Grant your user access to the device
    // for a specific time window.
    const accessGrant = await seam.accessGrants.create({
      user_identity: {
        full_name: 'Jane Doe',
        email_address: 'jane.doe@example.com',
      },
      device_ids: [frontDoor.device_id],
      requested_access_methods: [{ mode: 'code' }],
      starts_at: '2025-07-13T15:00:00.000Z',
      ends_at: '2025-07-16T11:00:00.000Z',
    })

    // Retrieve the issued access method to get the PIN code.
    const accessMethod = await seam.accessMethods.get({
      access_method_id:
        accessGrant.requested_access_methods[0].created_access_method_ids[0],
    })

    console.log(accessMethod.code)
  }
  ```

  ```bash cURL theme={null}
  # Retrieve all devices, filtered by manufacturer, which is
  # one of several filters that the list endpoint supports.
  all_august_locks=$(
    curl -X 'POST' \
      'https://connect.getseam.com/devices/list' \
      -H 'accept: application/json' \
      -H "Authorization: Bearer ${SEAM_API_KEY}" \
      -H 'Content-Type: application/json' \
      -d '{
      "manufacturer": "august"
    }')

  # Select the first device as an example.
  front_door=$(jq -r '.devices[0]' <<< ${all_august_locks})

  # Confirm that the device can program access codes.
  # You're using a capability flag here!
  if  $(jq -r '.can_program_online_access_codes' <<< ${front_door}); then \
    # Grant your user access to the device
    # for a specific time window.
    access_grant=$(curl -X 'POST' \
      'https://connect.getseam.com/access_grants/create' \
      -H 'accept: application/json' \
      -H "Authorization: Bearer ${SEAM_API_KEY}" \
      -H 'Content-Type: application/json' \
      -d "{
        \"user_identity\": {
          \"full_name\": \"Jane Doe\",
          \"email_address\": \"jane.doe@example.com\"
        },
        \"device_ids\": [\"$(jq -r '.device_id' <<< ${front_door})\"],
        \"requested_access_methods\": [{\"mode\": \"code\"}],
        \"starts_at\": \"2025-07-13T15:00:00.000Z\",
        \"ends_at\": \"2025-07-16T11:00:00.000Z\"
    }");

    # Retrieve the issued access method to get the PIN code.
    access_method_id=$(jq -r '.access_grant.requested_access_methods[0].created_access_method_ids[0]' <<< ${access_grant});
    curl -X 'POST' \
      'https://connect.getseam.com/access_methods/get' \
      -H 'accept: application/json' \
      -H "Authorization: Bearer ${SEAM_API_KEY}" \
      -H 'Content-Type: application/json' \
      -d "{
        \"access_method_id\": \"${access_method_id}\"
    }" | jq -r '.access_method.code';
  fi
  ```

  ```python Python theme={null}
  from seam import Seam

  seam = Seam()  # Seam automatically uses your exported SEAM_API_KEY.

  # Retrieve all devices, filtered by manufacturer,
  # which is one of several filters that list() supports.
  all_august_locks = seam.devices.list(manufacturer="august")

  # Select the first device as an example.
  front_door = all_august_locks[0]

  # Confirm that the device can program access codes.
  # You're using a capability flag here!
  if front_door.can_program_online_access_codes:
    # Grant your user access to the device
    # for a specific time window.
    access_grant = seam.access_grants.create(
      user_identity={
        "full_name": "Jane Doe",
        "email_address": "jane.doe@example.com"
      },
      device_ids=[front_door.device_id],
      requested_access_methods=[{"mode": "code"}],
      starts_at="2025-07-13T15:00:00.000Z",
      ends_at="2025-07-16T11:00:00.000Z"
    )

    # Retrieve the issued access method to get the PIN code.
    access_method = seam.access_methods.get(
      access_method_id=access_grant.requested_access_methods[0].created_access_method_ids[0]
    )

    print(access_method.code)
  ```

  ```ruby Ruby theme={null}
  require "seam"

  seam = Seam.new() # Seam automatically uses your exported SEAM_API_KEY.

  # Retrieve all devices, filtered by manufacturer,
  # which is one of several filters that list() supports.
  all_august_locks = seam.devices.list(manufacturer: "august")

  # Select the first device as an example.
  front_door = all_august_locks[0]

  # Confirm that the device can program access codes.
  # You're using a capability flag here!
  if (front_door.can_program_online_access_codes)
    # Grant your user access to the device
    # for a specific time window.
    access_grant = seam.access_grants.create(
      user_identity: {
        full_name: "Jane Doe",
        email_address: "jane.doe@example.com",
      },
      device_ids: [front_door.device_id],
      requested_access_methods: [{"mode": "code"}],
      starts_at: "2025-07-13T15:00:00.000Z",
      ends_at: "2025-07-16T11:00:00.000Z"
    )

    # Retrieve the issued access method to get the PIN code.
    access_method = seam.access_methods.get(
      access_method_id: access_grant.requested_access_methods[0].created_access_method_ids[0]
    )

    puts access_method.code
  end
  ```

  ```php PHP theme={null}
  <?php
  require 'vendor/autoload.php';

  $seam = new Seam\SeamClient(); // Seam automatically uses your exported SEAM_API_KEY.

  // Retrieve all devices, filtered by manufacturer,
  // which is one of several filters that list() supports.
  $all_august_locks = $seam->devices->list(manufacturer: "august");

  // Select the first device as an example.
  $front_door = $all_august_locks[0];

  // Confirm that the device can program access codes.
  // You're using a capability flag here!
  if ($front_door->can_program_online_access_codes) {
    // Grant your user access to the device
    // for a specific time window.
    $access_grant = $seam->access_grants->create(
      user_identity: [
        "full_name" => "Jane Doe",
        "email_address" => "jane.doe@example.com",
      ],
      device_ids: [$front_door->device_id],
      requested_access_methods: [["mode" => "code"]],
      starts_at: "2025-07-13T15:00:00.000Z",
      ends_at: "2025-07-16T11:00:00.000Z"
    );

    // Retrieve the issued access method to get the PIN code.
    $access_method = $seam->access_methods->get(
      access_method_id: $access_grant->requested_access_methods[0]->created_access_method_ids[0]
    );

    echo $access_method->code;
  }
  ```

  ```csharp C# theme={null}
  // Coming Soon!
  ```
</CodeGroup>

**Output:**

<CodeGroup>
  ```json JavaScript theme={null}
  "1234"
  ```

  ```json cURL theme={null}
  "1234"
  ```

  ```json Python theme={null}
  1234
  ```

  ```json Ruby theme={null}
  1234
  ```

  ```json PHP theme={null}
  1234
  ```

  ```json C# theme={null}
  // Coming Soon!
  ```
</CodeGroup>

<Info>
  In a sandbox workspace, the access method is issued almost instantly. On real
  devices, issuance can take a few moments—poll the access method until
  `is_issued` is `true` or watch for the `access_method.issued` event before
  reading the `code`.
</Info>

## Congrats! :tada:

Now that you have completed the Seam API Quick Start, you are well on your way to writing code that can actually control the physical world! :sunglasses:

Here are some ideas of what you can do next...

### Go Deeper on Granting Access

You just created your first Access Grant. The same API issues mobile keys, [Instant Keys](./use-cases/granting-access/using-instant-keys), and plastic cards, grants access to multiple devices and [access system entrances](./use-cases/granting-access/creating-an-access-grant) in one call, and manages the full credential lifecycle. See the [Granting Access guide](./use-cases/granting-access/index).

You can also control devices directly—for example, [lock and unlock doors](./low-level-apis/smart-locks/lock-and-unlock) remotely.

### Connect a Real Device

If you have a real device, you can try to control it using the steps in this Quick Start. Note that you must first [create a production workspace](./go-live#create-a-production-workspace) because sandbox workspaces only enable you to connect test accounts and devices. For more information, see [Workspaces](/core-concepts/workspaces/index).

### Connect Users' Devices

If you are creating an app to control your users' devices, see [Connect Webviews](/core-concepts/connect-webviews/index). Seam Connect Webviews are fully-embedded client-side components that you add to your app if you want to enable your users to import their own devices using your app. Your users interact with your embedded Connect Webviews to link their IoT device accounts to Seam through your app. That is, Connect Webviews walk your users through the process of logging in to their device accounts. Seam handles all the authentication steps, and—once your user has completed the authorization through your app—you can access and control their devices using the Seam API.

<img alt="Use Connect Webviews to enable your users to authorize your app to control their devices." />

### Learn about Devices and Capabilities

Seam supports many device categories. Each device can be broken down into [device capabilities](./capability-guides/device-and-system-capabilities). A capability indicates what the device can do, what properties it has, and what events it emits. To learn more about specific capabilities, such as access codes or thermostats, see the following guides:

<CardGroup>
  <Card title="Door Locks API" href="/low-level-apis/smart-locks">
    Get started →
  </Card>

  <Card title="Thermostats API" href="/capability-guides/thermostats">
    Get started →
  </Card>

  <Card title="Noise Sensors API" href="/capability-guides/noise-sensors">
    Get started →
  </Card>

  <Card title="Access Control Systems API" href="/low-level-apis/access-systems">
    Get started →
  </Card>
</CardGroup>


# Supported Device Table
Source: https://docs.seam.co/ui-components/device-database-components/supported-device-table

Embed Seam's live table of supported devices on your own website, filtered by the capabilities and manufacturers you care about.

The Supported Device Table is an embeddable web component that renders Seam's device database on your own site. Your customers can search it, filter it by capability, and see exactly which of their locks, thermostats, or access control systems work with your product—without you maintaining a compatibility list by hand.

The table reads from the same database that powers Seam's own integration guides, so it stays current as Seam adds device support.

Here it is embedded in this page, restricted to three lock manufacturers:

<DeviceList />

## Before You Begin

To embed the table, you need an **embed token** from Seam.

Email [support@getseam.com](mailto:support@getseam.com) and include every domain you plan to embed the table on. Seam creates the token for you and replies with it. This is a manual step on Seam's side, so request your token before you need it.

<Info>
  Send **full origins**, including the scheme and any non-default port—not bare hostnames. Seam matches them against the browser's `Origin` header, so `example.com` matches nothing while `https://example.com` matches. Include every environment you'll embed on:

  ```
  https://www.example.com
  https://staging.example.com
  https://*.preview.example.com
  http://localhost:3000
  ```

  Wildcards are supported per path segment, so `https://*.preview.example.com` covers your preview subdomains. Ask for a `localhost` origin at the port your dev server uses if you want the table working while you build.
</Info>

## Add the Table to Your Site

<Steps>
  <Step title="Load the component">
    Add the script tag to your page. `0.0.16` is the current release—see [Pin a Version](#pin-a-version) for how versioning works.

    ```html theme={null}
    <script
      type="module"
      src="https://cdn.devicedb.seam.co/v/0.0.16/DeviceListByCapability.global.js"
    ></script>
    ```
  </Step>

  <Step title="Place the element">
    Add the `device-list-by-capability` element wherever you want the table to appear, and set `capability-name` to the capability your customers care about.

    ```html theme={null}
    <device-list-by-capability
      capability-name="can_remotely_unlock"
      token="your-embed-token"
    ></device-list-by-capability>
    ```
  </Step>

  <Step title="Confirm it loads">
    Open the page on one of the domains you registered with Seam. You should see devices grouped by manufacturer with a search box above them.

    If you see nothing or an error, see [Troubleshooting](#troubleshooting).
  </Step>
</Steps>

The component renders inside a [shadow root](https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_shadow_DOM) and brings its own styles, so it cannot inherit from or interfere with the CSS on the rest of your page.

## How the Embed Token Works

An embed token is **not** a Seam API key and carries no account access. It identifies your embed, and it only works on the domains you registered.

Seam matches the browser's `Origin` header against the origins registered for your token:

* A request from a registered origin succeeds.
* A request from any other origin returns `403 Origin not allowed for this token`.
* A request with no `Origin` header at all also returns `403`.

Matching is on the whole origin string, scheme included. `https://example.com` and `http://example.com` are different origins, and so is the same host on a different port.

Because of this, the token is safe to include in your page's HTML, where anyone can read it. Someone who copies it cannot use it on their own site.

<Warning>
  Because a missing `Origin` is rejected too, the token will not work from `curl`, from a page opened over `file://`, or from a native app shell that sends no `Origin` header. The component expects a page served over HTTP(S) from a domain you have registered.
</Warning>

To add or remove domains later, email [support@getseam.com](mailto:support@getseam.com).

## How Support Is Reported

Each device row carries a support badge for the selected capability, rather than a plain yes-or-no:

| Badge             | Meaning                                                                                                                                                     |
| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Live**          | The device supports the capability outright.                                                                                                                |
| **Conditionally** | Supported, but with requirements—for example, a compatible [Seam Bridge](/capability-guides/seam-bridge) may be needed. Expand the row to see what applies. |
| **No**            | The device does not support the capability.                                                                                                                 |
| **Unknown**       | Seam has no compatibility data for this device and capability yet.                                                                                          |

A device is reported as **Conditionally** whenever caveats exist, even if the underlying record says the capability is supported. The same applies when a device matches the capability more than once and those matches disagree—the table reports the more cautious answer rather than the optimistic one.

This is the main reason to embed the table instead of publishing a static list: your customers see the caveat attached to the specific model they own, and it updates as Seam's compatibility data changes.

Use `initial-supported-filter="true"` to open the table with only supported devices shown.

## Attributes

Seam can also preset any of these on your token, so the table renders the way you want without you repeating attributes on every page. Attributes you set on the element always win over the presets, so you can override a default on a single page. Ask support if you'd like defaults configured.

| Attribute                  | Type    | Default                    | Description                                                                                                                                                  |
| -------------------------- | ------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `capability-name`          | string  | —                          | **Required.** One or more [capabilities](#capabilities), comma-separated. Supplying more than one adds a dropdown so your customers can switch between them. |
| `token`                    | string  | —                          | **Required.** Your embed token.                                                                                                                              |
| `manufacturers`            | string  | —                          | Comma-separated manufacturer slugs. When set, only these manufacturers appear.                                                                               |
| `excluded-manufacturers`   | string  | —                          | Comma-separated manufacturer slugs to leave out.                                                                                                             |
| `initial-capability`       | string  | first in `capability-name` | Which capability is selected when the table loads.                                                                                                           |
| `initial-supported-filter` | boolean | `false`                    | When `true`, the table opens with the "supported only" filter already applied.                                                                               |
| `unsupported-systems`      | string  | —                          | Comma-separated slugs to display as unsupported rather than omit. Use this to be explicit about systems you do not support.                                  |
| `max-visible-rows`         | number  | `4`                        | How many device rows to show per manufacturer before a "show more" control appears.                                                                          |
| `hide-search`              | boolean | `false`                    | Hides the search input.                                                                                                                                      |
| `locale`                   | string  | `en`                       | Display language: `en`, `fr`, or `pt`.                                                                                                                       |

## Capabilities

Set `capability-name` to one or more of the following. These are the same capability flags the [Seam API](/capability-guides/device-and-system-capabilities) reports on a device, so a capability you filter by here is one you can check in code later.

| Capability                               | Shown in the table as |
| ---------------------------------------- | --------------------- |
| `can_remotely_unlock`                    | Remote Unlock         |
| `can_remotely_lock`                      | Remote Lock           |
| `can_program_online_access_codes`        | Online Access Codes   |
| `can_program_offline_access_codes`       | Offline Codes         |
| `can_provision_mobile_keys`              | Mobile Keys           |
| `can_provision_wallet_keys`              | Wallet Keys           |
| `can_encode_plastic_cards`               | Plastic Cards         |
| `can_hvac_heat`                          | HVAC Heat             |
| `can_hvac_cool`                          | HVAC Cool             |
| `can_hvac_fan`                           | HVAC Fan              |
| `can_hvac_auto`                          | HVAC Auto             |
| `can_program_thermostat_weekly_programs` | Weekly Program        |
| `can_monitor`                            | Monitoring            |

<Warning>
  Use the full `can_*` flag names exactly as written above. Shorthand names such as `remoteunlock` are not recognized, and the table renders empty when it receives one.
</Warning>

## Examples

### Offer several capabilities

Pass multiple capabilities to give your customers a dropdown, and use `initial-capability` to choose which one loads first.

```html theme={null}
<device-list-by-capability
  capability-name="can_remotely_unlock,can_program_online_access_codes,can_provision_mobile_keys"
  initial-capability="can_program_online_access_codes"
  token="your-embed-token"
></device-list-by-capability>
```

### Show only the manufacturers you integrate with

```html theme={null}
<device-list-by-capability
  capability-name="can_remotely_unlock"
  manufacturers="schlage,yale,august"
  token="your-embed-token"
></device-list-by-capability>
```

### Exclude specific manufacturers

Useful when you want the full catalog minus a few brands you do not resell.

```html theme={null}
<device-list-by-capability
  capability-name="can_remotely_unlock"
  excluded-manufacturers="ttlock"
  token="your-embed-token"
></device-list-by-capability>
```

### Build a compact thermostat table

Hide the search box, show more rows per manufacturer, and open with only supported devices visible.

```html theme={null}
<device-list-by-capability
  capability-name="can_hvac_heat,can_hvac_cool"
  max-visible-rows="10"
  hide-search="true"
  initial-supported-filter="true"
  token="your-embed-token"
></device-list-by-capability>
```

### Render the table in French

```html theme={null}
<device-list-by-capability
  capability-name="can_remotely_unlock"
  locale="fr"
  token="your-embed-token"
></device-list-by-capability>
```

`en`, `fr`, and `pt` are available. Seam can also set a default locale on your token, so the table renders in your language without the attribute.

## Dark Mode

The table follows a `dark` class on any ancestor element rather than the browser's color-scheme preference. This lets it match whatever your site's own theme toggle does.

```html theme={null}
<div class="dark">
  <device-list-by-capability
    capability-name="can_remotely_unlock"
    token="your-embed-token"
  ></device-list-by-capability>
</div>
```

If your theme switcher toggles a class on `<html>` or `<body>`, the table picks up the change automatically—no extra wiring required.

## Pin a Version

Versioned CDN URLs are immutable: the contents of `/v/0.0.16/` never change once published. Pin an explicit version in production so a new release cannot alter your page unexpectedly.

```html theme={null}
<!-- Recommended: pinned -->
<script
  type="module"
  src="https://cdn.devicedb.seam.co/v/0.0.16/DeviceListByCapability.global.js"
></script>
```

`https://cdn.devicedb.seam.co/v/latest/DeviceListByCapability.global.js` also works and always serves the newest release. It is convenient for a quick trial, but avoid it in production.

To upgrade, change the version in the URL. To roll back, point at the previous version.

## Framework Notes

The table is a standard [custom element](https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_custom_elements), so plain HTML, Vue, Svelte, and Angular render it directly.

**React needs one extra step.** React does not manage custom elements the way it manages its own components, and a component that mutates the DOM during hydration can throw a hydration error. Rendering the table inside an `<iframe>` sidesteps this by giving it its own document, fully outside React's tree. The `postMessage` listener keeps the frame's height matched to its content, so the table reads as an inline part of the page rather than a fixed-height box with its own scrollbar.

<Warning>
  Report the height from a timer, not from a `ResizeObserver`. A `srcdoc` iframe that the browser treats as non-rendered has its animation loop throttled, so `ResizeObserver` and `requestAnimationFrame` never fire—but timers and `load` still do. Reading `scrollHeight` inside the timer forces a reflow, so the value stays correct even while the render loop is idle, and it re-syncs when the table rewraps on window resize.
</Warning>

```jsx theme={null}
export const SupportedDeviceTable = ({ capabilityName, manufacturers, token }) => {
  const cdn =
    'https://cdn.devicedb.seam.co/v/0.0.16/DeviceListByCapability.global.js'
  // Split so the literal never terminates a surrounding <script> block if this
  // component is ever server-rendered inline into a page.
  const close = '</scr' + 'ipt>'

  const srcDoc = [
    '<!doctype html><html><head><meta charset="utf-8">',
    '<style>html,body{margin:0;padding:0;background:transparent}</style></head><body>',
    `<script type="module" src="${cdn}">${close}`,
    `<device-list-by-capability manufacturers="${manufacturers}" capability-name="${capabilityName}" token="${token}"></device-list-by-capability>`,
    `<script>var _h=0;function _post(){var h=document.documentElement.scrollHeight;if(h&&h!==_h){_h=h;parent.postMessage({__devicedb:true,height:h},"*")}}setInterval(_post,300);addEventListener("load",_post);_post();${close}`,
    '</body></html>',
  ].join('')

  const onRef = (iframe) => {
    if (!iframe || iframe.dataset.devicedbBound) return
    iframe.dataset.devicedbBound = '1'
    window.addEventListener('message', (event) => {
      if (
        event.source === iframe.contentWindow &&
        event.data &&
        event.data.__devicedb
      ) {
        iframe.style.height = `${event.data.height}px`
      }
    })
  }

  return (
    <iframe
      ref={onRef}
      srcDoc={srcDoc}
      title='Compatible devices'
      style={{ width: '100%', minHeight: '320px', border: 'none' }}
    />
  )
}
```

This is the same approach Seam uses to embed the table throughout these docs, including the example at the top of this page.

<Info>
  The iframe inherits your page's origin, so your registered domains keep working without any additional configuration.
</Info>

## Troubleshooting

<AccordionGroup>
  <Accordion title="The table is empty, with no error">
    Check your `capability-name` values against the [capability list](#capabilities). The attribute must use the full `can_*` flag—`can_remotely_unlock`, not `remoteunlock`. An unrecognized capability matches no devices and renders an empty table.

    If you also set `manufacturers`, confirm the slugs are correct. A misspelled slug filters everything out.
  </Accordion>

  <Accordion title="Requests fail with 403 Origin not allowed for this token">
    The domain serving the page is not on your token's list. Email [support@getseam.com](mailto:support@getseam.com) with the domain to have it added.

    This also appears when the page sends no `Origin` header—when opened over `file://`, for example. Serve the page over HTTP(S) from a registered domain.
  </Accordion>

  <Accordion title="Requests fail with 401 Invalid token">
    The token was not recognized. Check for a truncated or misquoted value in your HTML, and confirm you are using the embed token Seam sent you rather than a Seam API key.
  </Accordion>

  <Accordion title="Nothing renders at all">
    Confirm the script tag includes `type="module"` and that the CDN URL resolves. Custom elements upgrade once their definition loads, so a blocked or misspelled script URL leaves the element on the page with nothing inside it.
  </Accordion>

  <Accordion title="A device is missing or its support status looks wrong">
    The table reflects Seam's device database. To report a missing device or an incorrect status, email [support@getseam.com](mailto:support@getseam.com) with the manufacturer and model.
  </Accordion>
</AccordionGroup>

## Next Steps

* Browse Seam's own [device and system integration guides](/device-and-system-integration-guides/august-locks) to see the table in context.
* Check capabilities programmatically with [Device and System Capabilities](/capability-guides/device-and-system-capabilities).
* Build device management UI into your app with [Seam Components](/ui-components/overview/index).

If you have questions or want to report an issue, email [support@getseam.com](mailto:support@getseam.com).


# Get started with Client Side Components
Source: https://docs.seam.co/ui-components/overview/getting-started-with-seam-components/get-started-with-client-side-components

Use Seam Components without touching the backend.

## Overview

Seam Components may be used on any website, in any web app, and with any framework all without needing a backend!

This guide will show you how to create a web page where a user may connect their third-party account to Seam and instantly start managing their devices. You can use plain HTML, React, or any framework that supports web components.

## 1 - Get a Publishable Key from the Seam Console

To access the Seam API, you'll need a publishable key. This key identifies your application when making requests to Seam and is safe to embed in your frontend code.

Go to [console.seam.co](https://console.seam.co) and select "Client Sessions" from the sidebar. You should then see a "Publishable Key" that you can copy.

## 2: Add Seam Components

<Tabs>
  <Tab title="Plain HTML">
    Seam Components are implemented in React, but may be used as native web components.

    Create a plain HTML page with the content below. You can serve this anyway you like, or even open it directly in your browser. The version in the script tag can be any [released version](https://github.com/seamapi/react/releases).

    ```html theme={null}
    <!DOCTYPE html>
    <html lang="en">
      <head>
        <meta charset="utf-8" />
        <meta name="viewport" content="width=device-width, initial-scale=1" />
        <title>Seam Components</title>
      </head>
      <body>
        <main>
          <seam-connect-account-button
            publishable-key="your_publishable_key"
          ></seam-connect-account-button>
          <seam-device-table
            publishable-key="your_publishable_key"
          ></seam-device-table>
        </main>
        <script
          type="module"
          src="https://react.seam.co/v/1.42.1/dist/elements.js"
        ></script>
      </body>
    </html>
    ```
  </Tab>

  <Tab title="React">
    Install `@seamapi/react` in your React application

    ```bash theme={null}
    npm install --save @seamapi/react
    ```

    Add the components anywhere in your React app

    ```javascript theme={null}
    import { ConnectAccountButton, DeviceTable, SeamProvider } from '@seamapi/react'

    export const App = () => {
      return (
        <SeamProvider publishableKey='your_publishable_key'>
          <main>
            <h1>Seam Components</h1>
            <ConnectAccountButton />
            <DeviceTable />
          </main>
        </SeamProvider>
      )
    }
    ```
  </Tab>

  <Tab title="Any JavaScript Framework">
    Install `@seamapi/react` in your application

    ```bash theme={null}
    npm install --save @seamapi/react
    ```

    Then import the custom elements bundle in your application entrypoint:

    ```javascript theme={null}
    import '@seamapi/react/elements.js'
    ```

    Add the components where your framework renders HTML. Some frameworks require additional configuration to enable web component support: refer to your framework's documentation (for example, [Vue's web components guide](https://vuejs.org/guide/extras/web-components.html) or Angular's `CUSTOM_ELEMENTS_SCHEMA`).

    ```html theme={null}
    <seam-connect-account-button
      publishable-key="your_publishable_key"
    ></seam-connect-account-button>
    <seam-device-table publishable-key="your_publishable_key"></seam-device-table>
    ```
  </Tab>
</Tabs>

You should see a page with an empty list of devices and a button to connect an account.

You could press the button now, but before you add some devices, there is one more step to complete to enable persisting and resuming the client session.

## 3: Select a User Identifier Key

A User Identifier Key allows a device owner to make API requests to Seam where interactions are restricted only to the devices they own. You'll need to choose a scheme for uniquely segmenting device owners and pass it to the components.

Here are some suggestions for selecting a key:

* The key should be a secret only known by the user.
* The key should not be displayed anywhere visible in the app or URL bar.
* The key should be opaque and contain sufficient entropy like a version 4 UUID.
* You should have a way to invalidate and generate a new key.
* Do NOT use an email, name, phone number, or anything that might be known by a third party.

We recommend either using a version 4 UUID that you generate and store with your user metadata, or a salted hash of your internal user identifier.

Once you have selected a user identifier key, update your code as follows:

<CodeGroup>
  ```html Plain HTML theme={null}
  <!DOCTYPE html>
  <html lang="en">
    <head>
      <meta charset="utf-8" />
      <meta name="viewport" content="width=device-width, initial-scale=1" />
      <title>Seam Components</title>
    </head>
    <body>
      <main>
        <seam-connect-account-button
          publishable-key="your_publishable_key"
          user-identifier-key="your_user_identifier_key"
        ></seam-connect-account-button>
        <seam-device-table
          publishable-key="your_publishable_key"
          user-identifier-key="your_user_identifier_key"
        ></seam-device-table>
      </main>
      <script
        type="module"
        src="https://react.seam.co/v/1.18.0/dist/elements.js"
      ></script>
    </body>
  </html>
  ```

  ```javascript React theme={null}
  import { ConnectAccountButton, DeviceTable, SeamProvider } from "@seamapi/react";

  export const App = () => {
    const { userIdentifierKey } = useAuth() // or however you manage client side auth
    return (
      <SeamProvider
        publishableKey='your_publishable_key'
        userIdentifierKey={userIdentifierKey}
      >
        <main>
          <h1>Seam Components</h1>
          <ConnectAccountButton />
          <DeviceTable />
        </main>
      </SeamProvider>
    )
  }

  ```

  ```html Any JavaScript Framework theme={null}
  <seam-connect-account-button
    publishable-key="your_publishable_key"
    user-identifier-key="your_user_identifier_key"
  >
  </seam-connect-account-button>
  <seam-device-table
    publishable-key="your_publishable_key"
    user-identifier-key="your_user_identifier_key"
  >
  </seam-device-table>
  ```
</CodeGroup>

Now, press the Connect Account button to open a Seam Connect Webview where you can login with your device provider. After logging in, you will be redirected back to this page where you should see your devices.

## Next Steps

* [Minimal sample apps](https://github.com/seamapi/seam-components-sample-apps) running Seam Components in various frameworks.
* View and play with other components in the [interactive storybook component library](https://react.seam.co/)
* Check out some [Full Example Apps](https://github.com/seamapi/react/tree/main/examples)

If you have any questions or want to report an issue, email us at [support@seam.co](mailto:support@seam.co).


# Get Started with React
Source: https://docs.seam.co/ui-components/overview/getting-started-with-seam-components/get-started-with-react-components-and-client-session-tokens

Learn to use Seam Components with your React application

## Overview

Seam Components may be used on any website, in any web app, and with any framework.

For this guide, we expect you to have a **backend server** and a **client frontend react application**. If you want to integrate Seam using only a client without a backend, you'll need to [use a Publishable Key](/ui-components/overview/getting-started-with-seam-components/get-started-with-client-side-components).

Seam provides React components and hooks to connect and control many types of smart devices. This guide provides a rapid introduction to using React components with Client Sessions.

### What is a Client Session Token?

A Client Session Token allows a device owner to make API requests to Seam where interactions are restricted only to the devices they own. To enable your users to interact with their devices, you'll need to create a client session and pass its token to the `<SeamProvider />`.

## 1 — Install the Seam SDK on your Server

Seam provides client libraries for many languages such as Javascript, Python, Ruby, and PHP, as well as a Postman collection and [OpenAPI](https://connect.getseam.com/openapi.json) spec.

* **Javascript:** `npm i seam` ([npm](https://www.npmjs.com/package/seam), [github](https://github.com/seamapi/javascript))
* **Python:** `pip install seam` ([pip](https://pypi.org/project/seamapi/), [github](https://github.com/seamapi/python))
* **Ruby:** `bundle add seam` ([rubygem](https://rubygems.org/gems/seam), [github](https://github.com/seamapi/ruby))
* **PHP:** `composer require seamapi/seam` ([packagist](https://packagist.org/packages/seamapi/seam), [github](https://github.com/seamapi/php))

Once installed, [sign-up for Seam](https://console.seam.co/) to get your API key, and export it as an environment variable:

```
$ export SEAM_API_KEY=seam_test2ZTo_0mEYQW2TvNDCxG5Atpj85Ffw
```

<Info>
  This guide uses a Sandbox Workspace. Only virtual devices can be connected. If
  you need to connect a real August Lock, use a non-sandbox workspace and API
  key.
</Info>

## 2 - Install `@seamapi/react` in your React application

```bash theme={null}
npm install --save @seamapi/react
```

## 3 — Create a Seam Client Session on your Server, and pass it to the Client

We'll start by writing some server code that returns a client session. There are a lot of ways to do this depending on your server framework:

* Create an endpoint such as `/api/seam/get_client_session` and call it from your frontend app.
* Inject the client session token in your html if you're using an HTML templating engine.

For this guide, we'll assume you're creating an endpoint that will return a client session token. This is often appropriate for Single Page Applications.

<Info>
  For most applications, the `user_identifier_key` below should be be your
  internal user id. For a detailed explanation, see [selecting a user Identifier
  key](/ui-components/overview/getting-started-with-seam-components/get-started-with-client-side-components#3-select-a-user-identifier-key).
</Info>

<Tabs>
  <Tab title="Javascript/NextJS API">
    ```javascript theme={null}
    import { Seam } from "seamapi"

    export default (req, res) => {
      // Handle authentication logic.
      const userId = req.auth.userId

    // Pull any connected accounts associated with this user.
    // If the user will create connect webviews from the client using the client session token,
    // e.g., via the <ConnectAccountButton /> component,
    // ensure your application associates those connected account ids here,
    // otherwise the client will not see devices connected from those accounts.
    const accountsAssociatedWithUser = [{ seamConnectedAccountId: "..." }]

    const seam = new Seam()

    // Get or create the client session for the user.
    // Pass an array of connected_account_ids, connect_webview_ids or both.
    // If the client session already exists, Seam will update the allowed connected_account_ids
    // and connect_webview_ids to the latest value provided here.
    const clientSession = await seam.clientSessions.getOrCreate({
    user_identifier_key: userId,
    connected_account_ids: accountsAssociatedWithUser.map(
    (acc) => acc.seamConnectedAccountId
    ),
    })

    res.status(200).json({
    token: clientSession.token,
    })
    }

    ```
  </Tab>

  <Tab title="Laravel/PHP API">
    ```php theme={null}
    <?php

    namespace App\Http\Controllers\Api;

    use App\Http\Controllers\Controller;
    use Illuminate\Http\Request;

    class SeamController extends Controller
    {
        public function getSeamClientSession()
        {
          // Handle authentication logic.
          $userId = request()->userId;

          // Pull any connected accounts associated with this user.
          // If the user will create connect webviews from the client using the client session token,
          // e.g., via the <ConnectAccountButton /> component,
          // ensure your application associates those connected account ids here,
          // otherwise the client will not see devices connected from those accounts.
          $accountsAssociatedWithUser = array(["seamConnectedAccountId" => "..."]);

            $data = [
                // Get or create the client session for the user.
                // Pass an array of connected_account_ids, connect_webview_ids or both.
                // If the client session already exists, Seam will update the allowed connected_account_ids
                // and connect_webview_ids to the latest value provided here.
                'seamClientSession' => $seam->client_sessions->get_or_create(
                  connected_account_ids: array_column($accountsAssociatedWithUser, 'seamConnectedAccountId');
                )
            ];

            return response()->json($data);
        }
    }
    ```

    ```php theme={null}
    // routes/api.php
    // ...
    Route::get('/seam/get_seam_client_session', 'Api\SeamController@getSeamClientSession');
    // ...

    ```
  </Tab>
</Tabs>

Awesome! We can now request this from the frontend client application using a hook like this:

```javascript theme={null}
// lib/hooks/use-seam-client-session-token.js
import { useState, useEffect } from 'react'

export const useSeamClientSessionToken = () => {
  const { myAppAuthToken } = useAuth() // or however you manage client side auth
  const [token, setToken] = useState()

  useEffect(async () => {
    const res = await fetch('/api/seam/get_client_session', {
      method: 'POST',
      headers: {
        Authorization: `Bearer ${myAppAuthToken}`,
      },
    })
    if (res.ok) {
      const data = await res.json()
      setToken(res.token)
    }
  }, [myAppAuthToken])

  return token
}
```

<Info>
  Why do we need the backend for getting the Client Session Token? It allows you
  to use your application's existing authentication! If you want to have Seam
  handle all the user authentication, you can use a publishable key, but we
  recommend using client session tokens!
</Info>

## 4 - Use Your Client Session Token to Display a User's Devices

```javascript theme={null}
import { SeamProvider, DeviceTable } from '@seamapi/react'
import { useSeamClientSessionToken } from 'lib/hooks/use-seam-client-session-token'

export const App = () => {
  const clientSessionToken = useSeamClientSessionToken()
  if (clientSessionToken == null) return <p>Loading...</p>
  return (
    <SeamProvider clientSessionToken={clientSessionToken}>
      <DeviceTable />
    </SeamProvider>
  )
}
```

You should see a list of devices like what's shown below:

## Next Steps

* [Minimal sample apps](https://github.com/seamapi/seam-components-sample-apps) running Seam Components in various frameworks.
* View and play with components in the [interactive storybook component library](https://react.seam.co/)
* Check out some [Full Example Apps](https://github.com/seamapi/react/tree/main/examples)

If you have any questions or want to report an issue, email us at [support@seam.co](mailto:support@seam.co).


# Getting Started with Seam Components
Source: https://docs.seam.co/ui-components/overview/getting-started-with-seam-components/index

Learn how to get started using Seam Components.

The following topics help you to get started using Seam Components in various types of applications:

* [Get Started with React](/ui-components/overview/getting-started-with-seam-components/get-started-with-react-components-and-client-session-tokens)
* [Get Started with Client Side Components](/ui-components/overview/getting-started-with-seam-components/get-started-with-client-side-components)


# Seam Components
Source: https://docs.seam.co/ui-components/overview/index

Create your own device management dashboards with prebuilt UI components.

[Seam Components](https://github.com/seamapi/react) are a set of prebuilt UI components for building your device management flow.

Features include:

* Device debugging flows that allow your customers to uncover issues
* Responsive design to fit seamlessly on any screen size

## [Getting started with Components ->](/ui-components/overview/getting-started-with-seam-components/get-started-with-client-side-components)

<CardGroup>
  <Card title="Device TableDisplay a list of devices, and filter for all the devices with issues." href="/ui-components/overview/react-components/device-table" />

  <Card title="Device Details" href="/ui-components/overview/react-components/device-details" />

  <Card title="Access Code TableDisplay a list of access codes, and filter for all the access codes with issues." href="/ui-components/overview/react-components/access-code-table" />

  <Card title="Access Code Details" href="/ui-components/overview/react-components/access-code-details" />
</CardGroup>

## Next Steps

* [Minimal sample apps](https://github.com/seamapi/seam-components-sample-apps) running Seam Components in various frameworks.
* View our [**Getting Started Guide**](/ui-components/overview/getting-started-with-seam-components/get-started-with-client-side-components)
* View and play with other components in the [**interactive storybook component library**](https://react.seam.co/)
* Check out some [**Full Example Apps**](https://github.com/seamapi/react/tree/main/examples)

If you have any questions or want to report an issue, email us at [support@seam.co](mailto:support@seam.co).


# Access Code Details
Source: https://docs.seam.co/ui-components/overview/react-components/access-code-details

Display the properties, settings, and issues for an access code in your app with Seam's React Access Code Details component.

## \<AccessCodeDetails /> [(preview)](https://react.seam.co/?path=/docs/components-accesscodedetails--docs)

The access code details component shows the properties, settings, and issues for an access code.

```
<AccessCodeDetails accessCodeId={accessCodeId} />
```

### Size: Mobile

### Props

| Name                    | Type     | Description                                                                                                           |
| ----------------------- | -------- | --------------------------------------------------------------------------------------------------------------------- |
| accessCodeId\*          | string   | The id for the access code to be displayed.                                                                           |
| disableLockUnlock       | boolean  | Hide the lock/unlock button for devices. Default: `false`.                                                            |
| disableDeleteAccessCode | boolean  | Hide the delete button. Default: `false`.                                                                             |
| onBack                  | function | <p>Optional callback fired when the Back chevron button is clicked.<br /><br />Signature: <code>() => void</code></p> |
| className               | string   | Optional class name to add to the rendered component's containing element.                                            |


# Access Code Table
Source: https://docs.seam.co/ui-components/overview/react-components/access-code-table

Show a list of current and future access codes and their statuses in your app with Seam's React Access Code Table component.

## \<AccessCodeTable /> [(preview)](https://react.seam.co/?path=/docs/components-accesscodetable--docs)

The access codes table shows a list of current and future access codes and their statuses.

```
<AccessCodeTable deviceId={deviceId} />
```

### Size: Mobile

### Size: Desktop

### Props

<table>
  <thead>
    <tr>
      <th>Name</th>
      <th>Type</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        deviceId<mark>\*</mark>
      </td>

      <td>string</td>

      <td>
        The id for the device whose access codes will be shown in the table.
      </td>
    </tr>

    <tr>
      <td>disableLockUnlock</td>
      <td>boolean</td>

      <td>
        Hide the lock/unlock button for devices. Default: <code>false</code>.
      </td>
    </tr>

    <tr>
      <td>disableDeleteAccessCode</td>
      <td>boolean</td>

      <td>
        Hide the delete action. Default: <code>false</code>
      </td>
    </tr>

    <tr>
      <td>
        <code>disableSearch</code>
      </td>

      <td>boolean</td>

      <td>
        Hide the search box. Default: <code>false</code>.
      </td>
    </tr>

    <tr>
      <td>accessCodeFilter</td>
      <td>function</td>

      <td>
        Optional filter function to filter the listed access codes.

        <br />

        <br />

        Signature:

        <code>
          (accessCode: AccessCode, searchInputValue: string) => boolean
        </code>
      </td>
    </tr>

    <tr>
      <td>accessCodeComparator</td>
      <td>function</td>

      <td>
        Optional comparator function to order the listed access codes.

        <br />

        <br />

        Signature:

        <code>
          (accessCodeA: AccessCode, accessCodeB: AccessCode) => number
        </code>
      </td>
    </tr>

    <tr>
      <td>onAccessCodeClick</td>
      <td>function</td>

      <td>
        Optional callback fired when an access code is clicked.

        <br />

        <br />

        Signature: <code>(accessCodeId: string) => void</code>
      </td>
    </tr>

    <tr>
      <td>preventDefaultOnAccessCodeClick</td>
      <td>boolean</td>

      <td>
        Prevent the default behavior when an access code is clicked. Default:
        <code>false</code>
      </td>
    </tr>

    <tr>
      <td>onBack</td>
      <td>function</td>

      <td>
        Optional callback fired when the Back chevron button is clicked.

        <br />

        <br />

        Signature: <code>() => void</code>
      </td>
    </tr>

    <tr>
      <td>className</td>
      <td>string</td>

      <td>
        Optional class name to add to the rendered component's containing
        element.
      </td>
    </tr>
  </tbody>
</table>


# Connect Account Button
Source: https://docs.seam.co/ui-components/overview/react-components/connect-account-button

Button that opens up a Connect Webview for connecting a new account

The connect account button opens a new Connect Webview. Accounts connected from this webview will be associated with the active client session.

```
<ConnectAccountButton />
```

### [See Live Preview](https://react.seam.co/?path=/docs/components-connectaccountbutton--docs)

### Props

| Name      | Type   | Description                                                                |
| --------- | ------ | -------------------------------------------------------------------------- |
| className | string | Optional class name to add to the rendered component's containing element. |


# Create Access Code Form
Source: https://docs.seam.co/ui-components/overview/react-components/create-access-code-form

Let users create access codes directly in your app with Seam's React Create Access Code Form component.

## \<CreateAccessCodeForm /> [(preview)](https://react.seam.co/?path=/docs/components-createaccesscodeform--docs)

The create access code form component allows you to create an access code.

```
<CreateAccessCodeForm deviceId={deviceId}/>
```

### Size: Mobile

### Props

| Name      | Type     | Description                                                                                                                                                                                 |
| --------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| deviceId  | string   | Optional. The ID for the device for which the access code will be created for. When set, it will skip the device selection pane.                                                            |
| onSuccess | function | <p>Optional callback fired when an access code is created.<br /><br />Signature: <code>(accessCode: AccessCode) => void</code></p>                                                          |
| onError   | function | <p>Optional callback triggered if an error occurs during the creation of an access code.<br /><br />Signature: <code>(err: SeamError, params: UseCreateAccessCodeParams) => void</code></p> |
| onBack    | function | <p>Optional callback fired when the Back chevron button is clicked.<br /><br />Signature: <code>() => void</code></p>                                                                       |
| className | string   | Optional class name to add to the rendered component's containing element.                                                                                                                  |


# Device Details
Source: https://docs.seam.co/ui-components/overview/react-components/device-details

Display the properties, settings, and issues for a device in your app with Seam's React Device Details component, with views per device type.

## \<DeviceDetails /> [(preview)](https://react.seam.co/?path=/docs/components-devicedetails--docs)

The device details component shows the properties, settings, and issues for a device.

```
<DeviceDetails deviceId={deviceId} />
```

### Different Device Views

The `DeviceDetails` will display varying views based on the device type.

#### Door Lock details

The "Lock" detail view displays a button leading to the list of access codes, along with various lock properties.

#### Thermostat details

The "Thermostat" detail view provides a button to view the list of scheduled climates and buttons to adjust the thermostat settings.

### Props

The `DeviceDetails` component displays the device as identified by the `deviceId` property. You can customize the component by turning off features like `disableLockUnlock` for door locks.

| Name                    | Type     | Description                                                                                                           |
| ----------------------- | -------- | --------------------------------------------------------------------------------------------------------------------- |
| deviceId<mark>\*</mark> | string   | The id for the device that will be shown in the table.                                                                |
| disableLockUnlock       | boolean  | Hide the lock/unlock button for devices. Default: `false`.                                                            |
| onBack                  | function | <p>Optional callback fired when the Back chevron button is clicked.<br /><br />Signature: <code>() => void</code></p> |
| className               | string   | Optional class name to add to the rendered component's containing element.                                            |


# Device Table
Source: https://docs.seam.co/ui-components/overview/react-components/device-table

Show a list of devices and their statuses in your app with Seam's React Device Table component, filterable by device or connected account.

## \<DeviceTable /> [(preview)](https://react.seam.co/?path=/docs/components-devicetable--docs)

The devices table shows a list of devices and their statuses.

```
<SeamProvider clientSessionToken={clientSessionToken}>
    <DeviceTable />
</SeamProvider
```

## Responsive Views

### Size: Desktop

### Size: Modal

## Props

<table>
  <thead>
    <tr>
      <th>Name</th>
      <th>Type</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        <code>deviceIds</code>
      </td>

      <td>array</td>

      <td>
        Optional list of specific device ids to return when requesting devices
        from the Seam API.
      </td>
    </tr>

    <tr>
      <td>
        <code>connectedAccountIds</code>
      </td>

      <td>array</td>

      <td>
        Optional list of connected account ids to filter devices by when
        requesting devices from the Seam API.
      </td>
    </tr>

    <tr>
      <td>
        <code>disableLockUnlock</code>
      </td>

      <td>boolean</td>

      <td>
        Hide the lock/unlock button for devices. Default: <code>false</code>.
      </td>
    </tr>

    <tr>
      <td>
        <code>disableSearch</code>
      </td>

      <td>boolean</td>

      <td>
        Hide the search box. Default: <code>false</code>.
      </td>
    </tr>

    <tr>
      <td>
        <code>deviceFilter</code>
      </td>

      <td>function</td>

      <td>
        Optional filter function to filter the listed devices.

        <br />

        <br />

        Signature:
        <code>(device: Device, searchInputValue: string) => boolean</code>
      </td>
    </tr>

    <tr>
      <td>
        <code>deviceComparator</code>
      </td>

      <td>function</td>

      <td>
        Optional comparator function to order the listed devices.

        <br />

        <br />

        Signature: <code>(deviceA: Device, deviceB: Device) => number</code>
      </td>
    </tr>

    <tr>
      <td>
        <code>onDeviceClick</code>
      </td>

      <td>function</td>

      <td>
        Optional callback fired when a device is clicked.

        <br />

        <br />

        Signature: <code>(deviceId: string) => void</code>
      </td>
    </tr>

    <tr>
      <td>
        <code>preventDefaultOnDeviceClick</code>
      </td>

      <td>boolean</td>

      <td>
        Prevent the default behavior when a device is clicked. Default:
        <code>false</code>
      </td>
    </tr>

    <tr>
      <td>
        <code>onBack</code>
      </td>

      <td>function</td>

      <td>
        Optional callback fired when the Back chevron button is clicked.

        <br />

        <br />

        Signature: <code>() => void</code>
      </td>
    </tr>

    <tr>
      <td>
        <code>className</code>
      </td>

      <td>string</td>

      <td>
        Optional class name to add to the rendered component's containing
        element.
      </td>
    </tr>
  </tbody>
</table>


# Components
Source: https://docs.seam.co/ui-components/overview/react-components/index

Browse Seam's React components for building smart lock, access code, and device management interfaces directly into your application.

Seam supports the following [Seam Components](/index):

<CardGroup>
  <Card title="Device TableDisplay a list devices, and filter for all the devices with issues." href="/ui-components/overview/react-components/device-table" />

  <Card title="Device Details" href="/ui-components/overview/react-components/device-details" />
</CardGroup>

## Smart Lock Components

<CardGroup>
  <Card title="Access Code Table" href="/ui-components/overview/react-components/access-code-table" />

  <Card title="Access Code Details" href="/ui-components/overview/react-components/access-code-details" />

  <Card title="Create Access Code Form" href="/ui-components/overview/react-components/create-access-code-form" />

  <Card title="Update Access Code Form" href="/ui-components/overview/react-components/update-access-code-form" />
</CardGroup>


# Seam Provider
Source: https://docs.seam.co/ui-components/overview/react-components/seam-provider

Load in a clientSessionToken into your components.

The SeamProvider component accepts a `clientSessionToken` that enables descendants of the SeamProvider to use the Seam API. A Client Session Token allows a device owner to make API requests to Seam where interactions are restricted only to devices they own. To enable your users to interact with their devices, you'll need to create a client session and pass its token to the `<SeamProvider />\`.

See [this guide](../getting-started-with-seam-components/get-started-with-react-components-and-client-session-tokens) for instructions on how to create a client session token.

```
<SeamProvider clientSessionToken={clientSessionToken}>
  <DeviceTable />
</SeamProvider>
```

### Props

| Name                              | Type   | Description                                                                                                                           |
| --------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------- |
| clientSessionToken<mark>\*</mark> | string | A Client Session Token allows a device owner to make API requests to Seam where interactions are restricted only to devices they own. |


# Update Access Code Form
Source: https://docs.seam.co/ui-components/overview/react-components/update-access-code-form

Let users modify an existing access code directly in your app with Seam's React Update Access Code Form component.

## \<UpdateAccessCodeForm /> (Coming soon!)

The update access code form component allows you to modify an access code.

```
<UpdateAccessCodeForm accessCodeId={accessCodeId}/>
```

### Props

| Name           | Type     | Description                                                                                                                                                                               |
| -------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| accessCodeId\* | string   | The ID for the access code to be updated.                                                                                                                                                 |
| onSuccess      | function | <p>Optional callback fired when an access code is updated.<br /><br />Signature: <code>(accessCode: AccessCode) => void</code></p>                                                        |
| onError        | function | <p>Optional callback triggered if an error occurs during the update of an access code.<br /><br />Signature: <code>(err: SeamError, params: UseUpdateAccessCodeParams) => void</code></p> |
| onBack         | function | <p>Optional callback fired when the Back chevron button is clicked.<br /><br />Signature: <code>() => void</code></p>                                                                     |
| className      | string   | Optional class name to add to the rendered component's containing element.                                                                                                                |


# Using User Identities to Scope Users' Device Access
Source: https://docs.seam.co/ui-components/overview/using-user-identities-to-scope-users-device-access

You can limit your users' access to a subset of devices.

First, create the [user identity](../../capability-guides/mobile-access/managing-mobile-app-user-accounts-with-user-identities#what-is-a-user-identity) that corresponds to your user. Configure the user identity with your internal user ID or other identifying information. Then, use the [Grant Access to Device](/api/user_identities/grant_access_to_device) method to assign the user identity access to specific devices.

After creating and configuring the user identity, create a [client session](/core-concepts/authentication/client-session-tokens/index) and capture the resulting [client session token](/core-concepts/authentication/client-session-tokens/index). When you use this token in your application, such as in a [Seam Component](/ui-components/overview/index), Seam limits you user's access to only the devices that you specified for the associated user identity.

<CodeGroup>
  ```javascript JavaScript theme={null}
  // Create the user identity.
  const user_identity = await seam.userIdentities.create({
      user_identity_key: "user-1"
  });

  // Grant the user identity access to a specific device.
  await seam.userIdentities.grantAccessToDevice(
      user_identity_id: user_identity.user_identity_id,
      // Specify the ID of the device that you want your
      // user to be able to access.
      device_id: "054765c8-a2fc-4599-b486-14c19f462c45"
  )

  // Create the client session.
  const client_session = await seam.clientSessions.create({
      user_identity_ids: [user_identity.user_identity_id]
  });

  // Use this token in your app.
  const token = client_session.token;
  ```

  ```bash cURL theme={null}
  # Create the user identity.
  user_identity=$(curl -X 'POST' \
    'https://connect.getseam.com/user_identities/create' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${API_KEY}" \
    -H 'Content-Type: application/json' \
    -d '{
          "user_identity_key": "user-1"
    }')

  # Get the user identity ID.
  user_identity_id=$(echo $user_identity | jq -r '.user_identity.user_identity_id')

  # Grant the user identity access to a specific device.
  # For device_id, specify the ID of the device that you
  # want your user to be able to access.
  curl -X 'POST' \
    'https://connect.getseam.com/user_identities/grant_access_to_device' \
    -H 'accept: application/json' \
    -H 'Authorization: Bearer ${API_KEY}' \
    -H 'Content-Type: application/json' \
    -d "{
          \"user_identity_id\": \"$user_identity_id\",
          \"device_id\": \"054765c8-a2fc-4599-b486-14c19f462c45\"
    }"

  # Create the client session.
  client_session=$(curl -X 'POST' \
    'https://connect.getseam.com/client_sessions/create' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${API_KEY}" \
    -H 'Content-Type: application/json' \
    -d "{
          \"user_identity_ids\": [\"$user_identity_id\"]
    }")

  # Get the resulting client session token and
  # use this token in your app.
  token=$(echo $client_session | jq -r '.client_session.token')
  ```

  ```python Python theme={null}
  # Create the user identity.
  user_identity = seam.user_identities.create(
      user_identity_key="user-1"
  )

  # Grant the user identity access to a specific device.
  seam.user_identities.grant_access_to_device(
      user_identity_id=user_identity.user_identity_id,
      # Specify the ID of the device that you want your
      # user to be able to access.
      device_id="054765c8-a2fc-4599-b486-14c19f462c45"
  )

  # Create the client session.
  client_session = seam.client_sessions.create(
      user_identity_ids=[user_identity.user_identity_id]
  )

  # Use this token in your app.
  token = client_session.token
  ```

  ```php PHP theme={null}
  // Create the user identity.
  $user_identity = $seam->user_identities->create(
    user_identity_key: "user-1"
  );

  // Grant the user identity access to a specific device.
  $seam->user_identities->grant_access_to_device(
      user_identity_id: $user_identity->user_identity_id,
      // Specify the ID of the device that you want your
      // user to be able to access.
      device_id: "054765c8-a2fc-4599-b486-14c19f462c45"
  );

  // Create the client session.
  $client_session = $seam->client_sessions->create(
    user_identity_ids: [$user_identity->user_identity_id]
  );

  // Use this token in your app.
  $token = $client_session->token;
  ```
</CodeGroup>


# ‘Seam Mobile Components’
Source: https://docs.seam.co/ui-components/seam-mobile-components/index

Drop-in UI components for unlocking and credential handling, fully customizable to match your app’s brand.

Seam Mobile Components are pre-built views that let you deliver end-user access flows in your mobile app with minimal effort. Instead of manually wiring together the Seam Mobile SDK, you can drop in a component like `SeamAccessView` to provide a fully functional access experience, including unlock interactions, credential error handling, haptics, and more.

***

### Why Mobile Seam Components?

* **Faster integration** – Add a complete access flow to your iOS app in minutes.
* **Consistent UX** – Components are designed to match Seam’s best practices for user experience.
* **Extensible** – Built on top of the Seam Mobile SDK; you can mix and match with your own custom views.
* **Customizable** – White-label theming is supported through SeamTheme.
* **Battle-tested** – Includes error handling, retries, and feedback (toasts + haptics) out of the box.

***

### Platform Guides

<CardGroup>
  <Card title="iOS GuideIntegrate Seam Mobile Components into your iOS app" href="/ui-components/seam-mobile-components/seam-mobile-components-for-ios/index" />
</CardGroup>


# Seam Mobile Components for iOS
Source: https://docs.seam.co/ui-components/seam-mobile-components/seam-mobile-components-for-ios/index

Learn how to set up Seam Mobile Components in your iOS project using Swift Package Manager, drop in SeamAccessView for a complete unlock flow, and customize the look with SeamTheme.

#### Prerequisites

* Xcode 15+
* iOS 16+ target

You should already have a Seam workspace and API key set up. If you’re new to Seam, start with the [Seam Mobile SDK](/mobile-sdks/ios).

***

### Installation

Add the [Seam Mobile Components](https://github.com/seamapi/ios) package via Swift Package Manager:

```swift theme={null}
dependencies: [
    .package(url: "https://github.com/seamapi/iOS", from: "1.0.0")
]
```

Then import it in your SwiftUI code:

```swift theme={null}
import SeamComponents
```

***

### Quick Start: `SeamAccessView`

The fastest way to get started is with SeamAccessView.

This view orchestrates all the underlying Mobile Seam Components to deliver a complete unlock experience.

```swift theme={null}
import SwiftUI
import SeamSDK
import SeamComponents

struct ContentView: View {
    init() {
        try? Seam.initialize(clientSessionToken: "YOUR_CLIENT_SESSION_TOKEN")
    }

    var body: some View {
        SeamAccessView()
    }
}
```

That’s it — you now have a ready-to-use, production-ready unlock interface.

***

### How It Works with the Seam Mobile SDK

* If you’re using Seam Mobile SDK:

  SeamAccessView automatically hooks into the SDK for device discovery, credential management, and unlock flows. No extra setup is needed.

* If you’re only using Mobile Seam Components:

  You still get a fully functional unlock UI without writing SDK-level code. Under the hood, the component takes care of talking to the Seam SDK for you.

Think of SeamAccessView as a shortcut to a complete access solution, while the SDK gives you deeper programmatic control.

***

### Customization with `SeamTheme`

Mobile Seam Components are white-label ready. You can use SeamTheme to apply your brand colors, fonts, and visual style across all components.

```swift theme={null}
SeamAccessView()
    .seamTheme(.init(
        accentColor: .blue,
        backgroundColor: .black,
        cornerRadius: 12
    ))
```

By default, components are styled with Seam’s design system, but theming lets you align them to your app’s identity.

***

### See Also

* Explore [Seam Mobile SDK](/mobile-sdks/ios)


# Colors
Source: https://docs.seam.co/ui-components/seam-mobile-components/seam-mobile-components-for-ios/theming/colors

Define semantic colors for text, backgrounds, states, and accents with SeamTheme.Colors.

Semantic app-wide colors used across components.

```swift theme={null}
public struct Colors {
    public var accent: Color
    public var primaryText: Color
    public var secondaryText: Color
    public var primaryTextLight: Color
    public var primaryTextDark: Color
    public var danger: Color
    public var error: Color
    public var warning: Color
    public var info: Color
    public var success: Color
    public var grayFill: Color
    public var lightFill: Color
    public var darkFill: Color
    public var secondaryFill: Color
    public var progress: Color
    public var primaryBackground: Color
    public var secondaryBackground: Color
}
```

#### Example (partial override):

```swift theme={null}
let colors = SeamTheme.Colors.default.with(
    accent: .teal,
    primaryBackground: Color(UIColor.systemBackground)
)
```


# Fonts
Source: https://docs.seam.co/ui-components/seam-mobile-components/seam-mobile-components-for-ios/theming/fonts

Set typography roles with SeamTheme.Fonts to match your app’s text hierarchy.

Semantic typography roles aligned to Dynamic Type.

```swift theme={null}
public struct Fonts {
    public var largeTitle: Font
    public var title: Font
    public var title2: Font
    public var title3: Font
    public var headline: Font
    public var subheadline: Font
    public var body: Font
    public var callout: Font
    public var footnote: Font
    public var caption: Font
    public var caption2: Font
    public var actionTitle: Font
    public var sectionHeader: Font
}
```

Example:

```swift theme={null}
let fonts = SeamTheme.Fonts.default.with(
    largeTitle: .system(size: 40, weight: .bold),
    actionTitle: .headline.weight(.semibold)
)
```


# Theming
Source: https://docs.seam.co/ui-components/seam-mobile-components/seam-mobile-components-for-ios/theming/index

Theming — Apply your brand’s colors, fonts, and styles to Seam Mobile Components with SeamTheme.

<div>
  <img alt="" />

  <img alt="" />

  <img alt="" />
</div>

Seam Mobile Components are white-label ready. You control appearance by providing a SeamTheme via the SwiftUI environment. The theme is a semantic palette composed of nested palettes—colors, fonts, keyCard, toast, and unlockCard—so you can brand globally or override locally.

> All SeamComponents (e.g., SeamAccessView, SeamKeyCardView, SeamCredentialsView, SeamUnlockCardView) automatically read the theme from EnvironmentValues.seamTheme.

***

### How theming works

* Environment-driven: Inject a SeamTheme anywhere in your view hierarchy:

```swift theme={null}
.environment(\.seamTheme, customTheme)
```

* Defaults provided: If you don’t inject a theme, components use SeamTheme.default.
* Partial overrides: Every nested palette supports .with(...) so you can change a few fields without redefining everything.

***

### Quick start

#### **App-wide theme (recommended)**

Inject a theme at the root so all Seam components share a consistent look:

```swift theme={null}
import SwiftUI
import SeamComponents

@main
struct MyApp: App {
    private let customTheme = SeamTheme(
        colors: .default.with(
            accent: .orange,
            error: .pink
        ),
        fonts: .default.with(
            largeTitle: .system(size: 36, weight: .bold)
        ),
        keyCard: .default.with(
            cornerRadius: 20 // see KeyCard palette
        )
    )

    var body: some Scene {
        WindowGroup {
            SeamAccessView()
                .environment(\.seamTheme, customTheme)
        }
    }
}
```

#### Local override

Scope a different look to a subsection of your UI:

```swift theme={null}
let alertyToast = SeamTheme.Toast.default.with(
    background: .red.opacity(0.1),
    borderColor: .red,
    textColor: .primary
)

SeamAccessView()
    .environment(\.seamTheme, .default.with(
        toast: alertyToast
    ))
```

### Theme structure

SeamTheme groups styling into five nested palettes. Each has:

* A default value that matches iOS look & feel.
* A memberwise initializer (for full control).
* A with(...) builder to override specific fields.

***

### Composing a theme

Use the top-level SeamTheme.with(...) to swap in any subset of palettes:

```swift theme={null}
let theme = SeamTheme.default.with(
    colors: .default.with(accent: .indigo),
    fonts: .default.with(title2: .system(.title2, design: .rounded)),
    keyCard: .default.with(cornerRadius: 22),
    toast: .default.with(accentColor: .indigo),
    unlockCard: .default.with(progressColor: .indigo)
)
```

Then inject:

```swift theme={null}
SeamAccessView()
    .environment(\.seamTheme, theme)
```

***

### Dark mode

* The defaults are light/dark adaptive by relying on system colors (e.g., Color(UIColor.systemBackground), .primary, .secondary).
* When customizing, prefer dynamic colors or provide your own light/dark logic:

```swift theme={null}
let colors = SeamTheme.Colors.default.with(
    primaryBackground: Color(light: .white, dark: .black)
)
```

***

### Best practices

* Start with defaults, then override selectively with .with(...).
* Keep contrast high for accessibility; test in light and dark modes.
* Brand consistently by driving accent, key button gradient, and toast accent from the same hue family.
* Scope locally if a one-off component needs a different visual treatment.

***

### API reference at a glance

* SeamTheme.default — system-aligned theme
* EnvironmentValues.seamTheme — environment key for theming
* Builders:
  * SeamTheme.with(colors:fonts:keyCard:toast:unlockCard:)
  * SeamTheme.Colors.default.with(...)
  * SeamTheme.Fonts.default.with(...)
  * SeamTheme.KeyCard.default.with(...)
  * SeamTheme.Toast.default.with(...)
  * SeamTheme.UnlockCard.default.with(...)


# Keycard styles
Source: https://docs.seam.co/ui-components/seam-mobile-components/seam-mobile-components-for-ios/theming/keycard-styles

Style key card components with custom gradients, logos, corner radius, and shadows.

Controls the look of key card UI (background gradient, logo, shadow, corner radius, etc.).

```swift theme={null}
public struct KeyCard {
    public var backgroundGradient: [Color]
    public var accentColor: Color
    public var logoAssetName: String
    public var cornerRadius: CGFloat
    public var shadowColor: Color
    public var shadowRadius: CGFloat
    public var shadowYOffset: CGFloat
}
```

#### Examples:

```swift theme={null}
// Change only the corner radius (uses builder).
let rounded = SeamTheme.KeyCard.default.with(cornerRadius: 24)

// Full control via initializer.
let branded = SeamTheme.KeyCard(
    backgroundGradient: [.blue, .purple],
    accentColor: .white,
    logoAssetName: "MyBrandLogo",
    cornerRadius: 18,
    shadowColor: .black.opacity(0.12),
    shadowRadius: 12,
    shadowYOffset: 6
)
```


# Toast styles
Source: https://docs.seam.co/ui-components/seam-mobile-components/seam-mobile-components-for-ios/theming/toast-styles

Configure transient banners by customizing background, text, accent, and layout.

Styles transient banners shown by components.

```swift theme={null}
public struct Toast {
    public var background: Color
    public var textColor: Color
    public var accentColor: Color
    public var borderColor: Color
    public var cornerRadius: CGFloat
    public var shadowColor: Color
    public var shadowRadius: CGFloat
    public var shadowYOffset: CGFloat
    public var horizontalPadding: CGFloat
    public var verticalPadding: CGFloat
}
```

#### **Example:**

```swift theme={null}
let toast = SeamTheme.Toast.default.with(
    background: Color(UIColor.secondarySystemBackground),
    borderColor: Color(UIColor.separator),
    cornerRadius: 14
)
```


# UnlockCard styles
Source: https://docs.seam.co/ui-components/seam-mobile-components/seam-mobile-components-for-ios/theming/unlockcard-styles

Control unlock card appearance, including header, key button, progress, instructions, and status states.

Used by `SeamUnlockCardView` and related UI (container, header, key button, progress, instructions, status colors).

```swift theme={null}
public struct UnlockCard {
    // Container & header
    public var cardBackground: Color?
    public var headerBackground: Color?
    public var dividerColor: Color
    public var headerTitleColor: Color
    public var headerSubtitleColor: Color
    public var providerLogoTint: Color

    // Primary action (big key)
    public var keyIconColorIdle: Color
    public var keyIconColorActive: Color
    public var keyButtonGradient: [Color]
    public var keyButtonShadowColor: Color
    public var keyButtonShadowRadius: CGFloat
    public var keyButtonShadowYOffset: CGFloat

    // Progress & labels
    public var progressColor: Color
    public var phaseTitleColor: Color

    // Instructions
    public var instructionTextColor: Color
    public var bulletBackground: Color
    public var bulletTextColor: Color

    // Status
    public var successColor: Color
    public var errorColor: Color
    public var statusMessageColor: Color
}
```

#### Examples:

```
// Subtle gradient and soft shadow for the big key button
let unlock = SeamTheme.UnlockCard.default.with(
    keyButtonGradient: [Color.accentColor.opacity(0.75), .accentColor],
    keyButtonShadowColor: .black.opacity(0.12),
    keyButtonShadowRadius: 10,
    keyButtonShadowYOffset: 6,
    progressColor: .accentColor
)

// Dark header with light title/subtitle
let darkHeader = SeamTheme.UnlockCard.default.with(
    headerBackground: .black,
    headerTitleColor: .white,
    headerSubtitleColor: .white.opacity(0.7),
    providerLogoTint: .white.opacity(0.8)
)
```


# Creating an Access Grant
Source: https://docs.seam.co/use-cases/granting-access/creating-an-access-grant

Create an Access Grant, check the resulting access methods, and deliver credentials to your user.

An Access Grant is a single API call that defines **who** gets access, **where** they can go, **when** access is valid, and **how** they get in. This guide walks through the full flow from creation to delivery.

## Before You Begin

* A Seam workspace with at least one connected device or access system. You can use a [sandbox workspace](/core-concepts/workspaces/index#sandbox-workspaces) with test devices.
* An [API key](/core-concepts/authentication/api-keys).
* The Seam SDK installed in your language of choice (see [Quick Start](/quickstart)).

***

## Step 1: Create the Access Grant

Call `/access_grants/create` with four things:

1. **Who** — a `user_identity_id` for an existing user, or pass `user_identity` to create one inline
2. **Where** — the resources to grant access to
3. **When** — the access schedule (`starts_at` and `ends_at`)
4. **How** — the access method modes to issue (e.g., `code`, `mobile_key`, `card`, `cloud_key`)

### Choosing Resources

You specify *where* to grant access using one or more of these parameters:

| Parameter          | Best for                        | Description                                                                                                                                                              |
| ------------------ | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `device_ids`       | Standalone smart locks          | Pass IDs of individual devices like August, Yale, or Schlage locks connected through a [Connect Webview](/core-concepts/connect-webviews/index).                         |
| `space_ids`        | Grouped access points           | Grant access to all entrances and devices in one or more [spaces](/api/spaces/object). Useful when a guest needs access to a room door, lobby, and elevator in one call. |
| `acs_entrance_ids` | Access control system entrances | Pass IDs of individual ACS entrances for fine-grained control.                                                                                                           |

You can combine these in a single Access Grant — for example, a standalone smart lock (`device_ids`) plus a set of ACS entrances (`acs_entrance_ids`).

<Info>
  If you're using Dormakaba Ambiance, Dormakaba Community, Visionline, Salto Space, or Vostio, you'll also need to pass a `reservation_key` to coordinate credential override sequencing. See [Reservation Access Grants](/use-cases/granting-access/reservation-access-grants).
</Info>

<Info>
  If you create multiple Access Grants for the same `user_identity_id`, Seam tries to reuse the same access methods across grants — for example, assigning the same PIN code so the user doesn't have to learn a new one for each reservation.
</Info>

<Info>
  When an Access Grant provisions a PIN code on a standalone lock, some devices only accept certain access schedules — for example, a minimum or maximum duration, or fixed check-in and check-out times. Before setting `starts_at` and `ends_at`, review the device's time frame options so that your schedule is valid. See [Understanding Time Frame Options](/low-level-apis/smart-locks/access-codes/creating-access-codes/understanding-time-frame-options).
</Info>

### Example

The example below creates an Access Grant for a single smart lock with a PIN code. To grant access to multiple doors at once, pass `space_ids` instead of `device_ids`. To target specific ACS entrances, use `acs_entrance_ids`. You can also request multiple modes in one call — for example, `[{"mode": "code"}, {"mode": "mobile_key"}]`.

<CodeGroup>
  ```python Python theme={null}
  from seam import Seam

  seam = Seam()

  access_grant = seam.access_grants.create(
      user_identity={
          "full_name": "Jane Doe",
          "email_address": "jane@example.com",
      },
      device_ids=["6ba7b811-9dad-11d1-80b4-00c04fd430c8"],
      requested_access_methods=[{"mode": "code"}],
      starts_at="2025-07-13T15:00:00.000Z",
      ends_at="2025-07-16T11:00:00.000Z",
  )
  ```

  ```javascript JavaScript theme={null}
  import { Seam } from "seam";

  const seam = new Seam();

  const accessGrant = await seam.accessGrants.create({
    user_identity: {
      full_name: "Jane Doe",
      email_address: "jane@example.com",
    },
    device_ids: ["6ba7b811-9dad-11d1-80b4-00c04fd430c8"],
    requested_access_methods: [{ mode: "code" }],
    starts_at: "2025-07-13T15:00:00.000Z",
    ends_at: "2025-07-16T11:00:00.000Z",
  });
  ```

  ```ruby Ruby theme={null}
  require "seam"

  seam = Seam.new()

  access_grant = seam.access_grants.create(
    user_identity: {
      full_name: "Jane Doe",
      email_address: "jane@example.com",
    },
    device_ids: ["6ba7b811-9dad-11d1-80b4-00c04fd430c8"],
    requested_access_methods: [{ "mode": "code" }],
    starts_at: "2025-07-13T15:00:00.000Z",
    ends_at: "2025-07-16T11:00:00.000Z"
  )
  ```

  ```php PHP theme={null}
  <?php
  require 'vendor/autoload.php';

  $seam = new Seam\SeamClient();

  $access_grant = $seam->access_grants->create(
      user_identity: [
          "full_name" => "Jane Doe",
          "email_address" => "jane@example.com",
      ],
      device_ids: ["6ba7b811-9dad-11d1-80b4-00c04fd430c8"],
      requested_access_methods: [["mode" => "code"]],
      starts_at: "2025-07-13T15:00:00.000Z",
      ends_at: "2025-07-16T11:00:00.000Z"
  );
  ```

  ```csharp C# theme={null}
  // Coming soon!
  ```

  ```java Java theme={null}
  // Coming soon!
  ```

  ```bash cURL (bash) theme={null}
  curl -X 'POST' \
    'https://connect.getseam.com/access_grants/create' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d '{
      "user_identity": {
        "full_name": "Jane Doe",
        "email_address": "jane@example.com"
      },
      "device_ids": ["6ba7b811-9dad-11d1-80b4-00c04fd430c8"],
      "requested_access_methods": [{"mode": "code"}],
      "starts_at": "2025-07-13T15:00:00.000Z",
      "ends_at": "2025-07-16T11:00:00.000Z"
    }'
  ```
</CodeGroup>

<Info>
  When you request `mobile_key`, Seam also generates an `instant_key_url` on the Access Grant — a shareable link that gives your user mobile access without downloading an app. See [Using Instant Keys](/use-cases/granting-access/using-instant-keys).
</Info>

### Requesting a Custom Access Code

By default, Seam generates a PIN code for each `code` access method. To request a specific code instead — for example, to reuse a code a guest already knows — include a `code` value alongside `mode: "code"` in `requested_access_methods`. The code must be **4–9 digits** and contain only digits.

<CodeGroup>
  ```python Python theme={null}
  from seam import Seam

  seam = Seam()

  access_grant = seam.access_grants.create(
      user_identity={
          "full_name": "Jane Doe",
          "email_address": "jane@example.com",
      },
      device_ids=["6ba7b811-9dad-11d1-80b4-00c04fd430c8"],
      requested_access_methods=[{"mode": "code", "code": "1234"}],
      starts_at="2025-07-13T15:00:00.000Z",
      ends_at="2025-07-16T11:00:00.000Z",
  )
  ```

  ```javascript JavaScript theme={null}
  import { Seam } from "seam";

  const seam = new Seam();

  const accessGrant = await seam.accessGrants.create({
    user_identity: {
      full_name: "Jane Doe",
      email_address: "jane@example.com",
    },
    device_ids: ["6ba7b811-9dad-11d1-80b4-00c04fd430c8"],
    requested_access_methods: [{ mode: "code", code: "1234" }],
    starts_at: "2025-07-13T15:00:00.000Z",
    ends_at: "2025-07-16T11:00:00.000Z",
  });
  ```

  ```ruby Ruby theme={null}
  require "seam"

  seam = Seam.new()

  access_grant = seam.access_grants.create(
    user_identity: {
      full_name: "Jane Doe",
      email_address: "jane@example.com",
    },
    device_ids: ["6ba7b811-9dad-11d1-80b4-00c04fd430c8"],
    requested_access_methods: [{ "mode": "code", "code": "1234" }],
    starts_at: "2025-07-13T15:00:00.000Z",
    ends_at: "2025-07-16T11:00:00.000Z"
  )
  ```

  ```php PHP theme={null}
  <?php
  require 'vendor/autoload.php';

  $seam = new Seam\SeamClient();

  $access_grant = $seam->access_grants->create(
      user_identity: [
          "full_name" => "Jane Doe",
          "email_address" => "jane@example.com",
      ],
      device_ids: ["6ba7b811-9dad-11d1-80b4-00c04fd430c8"],
      requested_access_methods: [["mode" => "code", "code" => "1234"]],
      starts_at: "2025-07-13T15:00:00.000Z",
      ends_at: "2025-07-16T11:00:00.000Z"
  );
  ```

  ```csharp C# theme={null}
  // Coming soon!
  ```

  ```java Java theme={null}
  // Coming soon!
  ```

  ```bash cURL (bash) theme={null}
  curl -X 'POST' \
    'https://connect.getseam.com/access_grants/create' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d '{
      "user_identity": {
        "full_name": "Jane Doe",
        "email_address": "jane@example.com"
      },
      "device_ids": ["6ba7b811-9dad-11d1-80b4-00c04fd430c8"],
      "requested_access_methods": [{"mode": "code", "code": "1234"}],
      "starts_at": "2025-07-13T15:00:00.000Z",
      "ends_at": "2025-07-16T11:00:00.000Z"
    }'
  ```
</CodeGroup>

<Info>
  A requested code is a preference, not a guarantee. Seam applies it when it can and falls back to a generated code when it can't:

  * **The code is already in use on a device:** Seam assigns a different code for that device and records a warning on the Access Grant (`warning_code: "requested_code_unavailable"`) that includes both the original and the replacement code.
  * **The grant spans multiple Salto locks:** Seam ignores the requested code and assigns a single shared generated code across those devices, because Salto can't guarantee the same PIN on every device.
  * **The provider has stricter code-length limits:** Some devices accept a narrower range than 4–9 digits. If the requested code isn't valid for a device, Seam assigns a compatible code for that device instead.

  Always read the resulting `code` back from the access method (see [Step 2: Deliver the Access Methods](#step-2-deliver-the-access-methods)) rather than assuming the requested value was used, and check the grant's `warning_map` for any `requested_code_unavailable` warnings. For more on delivering and updating codes, see [Using PIN Codes](/use-cases/granting-access/using-pin-codes) and [Managing Access Methods](/use-cases/granting-access/managing-access-methods).
</Info>

***

## Step 2: Deliver the Access Methods

After creating the grant, list the access methods to see what was created and check their issuance status.

<CodeGroup>
  ```python Python theme={null}
  access_methods = seam.access_methods.list(
      access_grant_id=access_grant.access_grant_id
  )

  for method in access_methods:
      print(f"{method.mode}: is_issued={method.is_issued}")
  ```

  ```javascript JavaScript theme={null}
  const accessMethods = await seam.accessMethods.list({
    access_grant_id: accessGrant.access_grant_id,
  });

  for (const method of accessMethods) {
    console.log(`${method.mode}: is_issued=${method.is_issued}`);
  }
  ```

  ```ruby Ruby theme={null}
  access_methods = seam.access_methods.list(
    access_grant_id: access_grant.access_grant_id
  )

  access_methods.each do |method|
    puts "#{method.mode}: is_issued=#{method.is_issued}"
  end
  ```

  ```php PHP theme={null}
  $access_methods = $seam->access_methods->list(
      access_grant_id: $access_grant->access_grant_id
  );

  foreach ($access_methods as $method) {
      echo $method->mode . ": is_issued=" . $method->is_issued . "\n";
  }
  ```

  ```csharp C# theme={null}
  // Coming soon!
  ```

  ```java Java theme={null}
  // Coming soon!
  ```

  ```bash cURL (bash) theme={null}
  curl -X 'POST' \
    'https://connect.getseam.com/access_methods/list' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d "{\"access_grant_id\": \"${access_grant_id}\"}"
  ```
</CodeGroup>

Each access method has an `is_issued` flag. Once it's `true`, the credential is active and ready to deliver. How you deliver depends on the mode:

| Mode         | What to do                                                                                               | Guide                                                                                                                             |
| ------------ | -------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `code`       | Read the `code` property and share the PIN with your user.                                               | [Using PIN Codes](/use-cases/granting-access/using-pin-codes)                                                                     |
| `mobile_key` | Initialize the Seam mobile SDK with the `client_session_token`, or send the `instant_key_url`.           | [Using Mobile Keys](/use-cases/granting-access/using-mobile-keys) / [Instant Keys](/use-cases/granting-access/using-instant-keys) |
| `card`       | Encode a fresh card or assign an existing card. `is_issued` becomes `true` after encoding or assignment. | [Using Key Cards](/use-cases/granting-access/using-key-cards)                                                                     |
| `cloud_key`  | Call `access_methods.unlock_door` from your web app to unlock on behalf of the user.                     | [Using Cloud Keys](/use-cases/granting-access/using-cloud-keys)                                                                   |

<Info>
  In a sandbox workspace, automatically-issued access methods are ready almost instantly. On real devices, issuance can take a few moments.
</Info>

### Tracking Issuance with Events

Instead of polling `is_issued`, you can listen for [webhook](/developer-tools/webhooks) events:

| Event                                    | Meaning                                                                 |
| ---------------------------------------- | ----------------------------------------------------------------------- |
| `access_method.issued`                   | The access method is ready to deliver.                                  |
| `access_method.card_encoding_required`   | A card needs to be encoded before it can be delivered.                  |
| `access_method.card_assignment_required` | A card needs to be assigned to a physical card before it can be issued. |


# Overview
Source: https://docs.seam.co/use-cases/granting-access/index

One API to grant access across smart locks and access control systems — PIN codes, mobile keys, key cards, and cloud keys.

**Access Grants** are a single API for granting access to any physical space. Whether you're working with standalone smart locks, enterprise access control systems, or both — one call handles it all.

* **One integration** for smart locks (August, Yale, Schlage, TTLock, igloohome, and more) and access control systems (Salto, ASSA ABLOY Visionline, dormakaba, Brivo, and more).
* **Every access method** — PIN codes, mobile keys, Instant Keys, key cards, and cloud keys — through the same `requested_access_methods` parameter.
* **Automatic lifecycle management** — Seam propagates credentials to devices, re-materializes them as hardware comes online, and cleans up when access expires.

<Tabs>
  <Tab title="JavaScript">
    ```javascript theme={null}
    await seam.accessGrants.create({
      user_identity: {
        full_name: 'Jane Doe',
        email_address: 'jane@example.com',
      },
      device_ids: ['6ba7b811-9dad-11d1-80b4-00c04fd430c8'],
      requested_access_methods: [{ mode: 'code' }],
      starts_at: '2025-07-13T15:00:00.000Z',
      ends_at: '2025-07-16T11:00:00.000Z',
    })
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    seam.access_grants.create(
        user_identity={
            "full_name": "Jane Doe",
            "email_address": "jane@example.com",
        },
        device_ids=["6ba7b811-9dad-11d1-80b4-00c04fd430c8"],
        requested_access_methods=[{"mode": "code"}],
        starts_at="2025-07-13T15:00:00.000Z",
        ends_at="2025-07-16T11:00:00.000Z",
    )
    ```
  </Tab>

  <Tab title="Ruby">
    ```ruby theme={null}
    seam.access_grants.create(
      user_identity: {
        full_name: "Jane Doe",
        email_address: "jane@example.com",
      },
      device_ids: %w[6ba7b811-9dad-11d1-80b4-00c04fd430c8],
      requested_access_methods: [{ mode: "code" }],
      starts_at: "2025-07-13T15:00:00.000Z",
      ends_at: "2025-07-16T11:00:00.000Z",
    )
    ```
  </Tab>

  <Tab title="PHP">
    ```php theme={null}
    $seam->access_grants->create(
        user_identity: [
            "full_name" => "Jane Doe",
            "email_address" => "jane@example.com",
        ],
        device_ids: ["6ba7b811-9dad-11d1-80b4-00c04fd430c8"],
        requested_access_methods: [
            ["mode" => "code"],
        ],
        starts_at: "2025-07-13T15:00:00.000Z",
        ends_at: "2025-07-16T11:00:00.000Z",
    );
    ```
  </Tab>

  <Tab title="C#">
    ```csharp theme={null}
    // Coming Soon!
    ```
  </Tab>

  <Tab title="cURL">
    ```bash theme={null}
    curl --include --request POST "https://connect.getseam.com/access_grants/create" \
      --header "Authorization: Bearer $SEAM_API_KEY" \
      --json @- <<EOF
    {
      "user_identity": {
        "full_name": "Jane Doe",
        "email_address": "jane@example.com"
      },
      "device_ids": ["6ba7b811-9dad-11d1-80b4-00c04fd430c8"],
      "requested_access_methods": [{"mode": "code"}],
      "starts_at": "2025-07-13T15:00:00.000Z",
      "ends_at": "2025-07-16T11:00:00.000Z"
    }
    EOF
    ```
  </Tab>
</Tabs>

You specify *where* to grant access using `device_ids` (smart locks), `acs_entrance_ids` (ACS entrances), or `space_ids` (groups of access points). You can combine them in a single grant.

***

## Access Methods

Each Access Grant can issue one or more **access methods** — the credentials your user actually uses to get through a door. Request them via the `requested_access_methods` parameter.

| Mode         | What it is                                                                                                           | Best for                                                         |
| ------------ | -------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- |
| `code`       | A PIN code programmed on the lock.                                                                                   | Simple keypad entry — share a code via text, email, or your app. |
| `mobile_key` | A BLE credential delivered through the [Seam mobile SDK](/capability-guides/mobile-access/mobile-device-sdks/index). | Building a custom app with native mobile unlock.                 |
| `card`       | A credential on a physical plastic card — either encoded fresh or assigned from an existing card.                    | Hotels and offices with existing card infrastructure.            |
| `cloud_key`  | An API endpoint for unlocking the door on behalf of a user, with access logs.                                        | Building a web app that unlocks doors for users.                 |

When you request `mobile_key`, Seam also generates an **Instant Key** — a shareable URL that gives your user mobile access without downloading an app. Useful for quick delivery via text or email.

You can request multiple modes in one call — for example, a PIN code *and* a mobile key — and Seam issues all of them under the same Access Grant.

***

## Hotel and Offline Lock Systems

Some hotel access systems (Dormakaba Ambiance, Dormakaba Community, Visionline, Salto Space, and Vostio) **require** a `reservation_key` when creating an Access Grant so Seam can coordinate credential sequencing across grants. Without it, credentials can conflict.

See [Reservation Access Grants](/use-cases/granting-access/reservation-access-grants) for the full guide.

***

## Next Steps

* [Creating an Access Grant](/use-cases/granting-access/creating-an-access-grant) — step-by-step guide
* [Access Grants API Reference](/api/access_grants/object)
* [Access Methods API Reference](/api/access_methods/object)


# How Instant Keys Work
Source: https://docs.seam.co/use-cases/granting-access/instant-keys/how-instant-keys-work

Learn the details of how Seam Instant Keys work.

When you issue an Instant Key, Seam creates a secure URL tied to a specific user identity. Seam uses this identity to track and manage access across devices and time windows.

## Tied to a User Identity

An Instant Key is issued to a user identity, not a device or a mobile credential. That means a user can access their Instant Key from any phone or browser session, and the system retrieves and loads their associated mobile credentials.

## Includes All Issued Mobile Credentials

The Instant Key experience fetches all valid mobile credentials that have been issued to the user. If multiple doors or entrance types are assigned—such as hotel room doors, elevators, and amenity areas—they're all available through the same link.

Credentials are scoped to the identity's active access grants.

If the user is reissued access—for example, a new room or an extended stay—the Instant Key reflects the latest set of credentials automatically.

## Seamless Unlocking

Once opened, the Instant Key web app:

1. Initializes Bluetooth scanning using native Web Bluetooth APIs (or App Clip/Instant App wrappers).
2. Detects eligible nearby locks and attempts to unlock using the mobile credentials.
3. Provides visual feedback for successful unlocks, errors, and unsupported devices.

## Sharing Access

Users can forward their Instant Key by text or email if they want to share access with a friend, partner, or teammate. The link still loads all valid credentials for the original user identity. This ability is useful for households, couples, and group stays. You can restrict or track this behavior using the Seam API, if needed.

## Secure by Design

Seam ensures security in the following ways:

* Instant Key links are scoped and time-limited, and they only work for the intended user.
* All credential operations happen on the client side, using cryptographic keys provisioned by the access control provider.
* The Instant Key link can be revoked at any time using the Seam API.


# Setting Up Your Site for Instant Keys
Source: https://docs.seam.co/use-cases/granting-access/instant-keys/setting-up-your-site-for-instant-keys

Learn about the site requirements for using Instant Keys.

Before issuing Instant Keys, make sure that your property meets the following requirements:

* [Bluetooth compatibility for door locks](#bluetooth-compatibility-for-door-locks)
* [License requirements](#license-requirements)

Fulfilling these requirements ensures that guests can unlock doors using mobile credentials over Bluetooth.

Then, [connect your access system to Seam](#connect-your-access-system-to-seam).

***

## Bluetooth Compatibility for Door Locks

Your door lock hardware must support Bluetooth Low Energy (BLE) keys. Seam Instant Key uses BLE to unlock doors offline, without relying on Wi-Fi or cellular.

The following table describes the BLE requirements for the access systems for which Seam supports Instant Keys:

<table>
  <thead>
    <tr>
      <th>Access System</th>
      <th>BLE Requirements and Support</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Salto KS</td>
      <td>All locks support BLE mobile keys right out of the box.</td>
    </tr>

    <tr>
      <td>Salto Space</td>
      <td>All locks support BLE mobile keys right out of the box.</td>
    </tr>

    <tr>
      <td>ASSA ABLOY Visionline and Vostio (Vingcard locks)</td>

      <td>
        Requires specific hardware and licensing. See

        <a href="#vingcard-lock-requirements">
          Vingcard Lock Requirements
        </a>

        .
      </td>
    </tr>
  </tbody>
</table>

### Vingcard Lock Requirements

Note the following requirements for Vingcard locks:

#### RFID Readers for Magstripe Locks

For magstripe locks, you must attach an RFID reader to the escutcheon.

1. Detach the magstripe escutcheon and battery cover.
2. Replace the original reader with an RFID module.
3. Activate mobile access for the lock.

For detailed instructions, see the Vingcard [Upgrading Your Vingcard Door Locks to RFID and Mobile Access](https://www.vingcard.com/en/solutions/mobile-access-and-wallet-solutions/mobile-access/rfid-upgrade) guide.

#### LCU Compatibility

To support mobile (BLE) keys, your lock must have the correct Lock Control Unit (LCU). You can identify the LCU by the label on the back, as follows:

| LCU Model                      | Compatibility                                                                                                                                              |
| ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| LCU 6351 (white label)         | <ul><li>BLE built in.</li><li>Mobile key ready.</li></ul>                                                                                                  |
| LCU 6333 or 6334 (green label) | <ul><li>No BLE support.</li><li>Needs an additional <a href="https://estore.vingcard.com/ca/ble-module-pcba-7001.html">BLE module</a> installed.</li></ul> |

<img alt="LCU examples" />

***

## License Requirements

To use mobile keys with your access system, you may need to purchase licenses or subscriptions to activate certain software features. These features vary by access system.

### **ASSA ABLOY Visionline**

To use Instant Keys with Visionline, please reach out to your local installer to purchase the following from Assa Abloy:

* A mobile key license linked to Seam's Assa Abloy tenant account: `SeamLabs-tenant`. Provide this account username when completing your purchase.
* A web services option code.

After you have purchased the items above from Assa Abloy, please reach out to Seam at [support@seam.co](mailto:support@seam.co). Include the Seam workspace ID you'll be using, so we can help finish setting up your workspace for Visionline Instant Keys.

### **ASSA ABLOY Vostio**

To use mobile keys with Vostio, you will need to purchase the following from Assa Abloy:

* A mobile Key license for Seam's Assa Abloy tenant account called `SeamLabs-tenant` — please provide this account name to Assa Abloy when completing your purchase

After you have purchased the items above from Assa Abloy, please reach out to Seam at [support@seam.co](mailto:support@seam.co). Include the Seam workspace ID you'll be using, so we can help finish setting up your workspace for Visionline Instant Keys.

### **Salto KS**

To use mobile keys with Salto KS, you need the following subscription:

* [Lite package subscription](https://support.saltosystems.com/ks/account/subscription-and-vouchers/)

  Purchase this subscription with a sufficient user subscription that exceeds the maximum number of users that you have on your system at any moment in time.

### **Salto Space**

To use mobile keys with Salto Space, you need to add the following features when purchasing your [Space license](https://saltopro.com/product/salto-space-basic-license-spabasic/):

* 0016-1 – Mobile Access (BLE)
* 0018 – SHIP Interface

***

## Connect Your Access System to Seam

To connect your access system to Seam, we recommend embedding a [Connect Webview](/core-concepts/connect-webviews/index) in your application. The Connect Webview flow guides the property manager through each step of the connection process.

<img alt="Example: Connect Webview for Salto systems" />

For on-premises access systems, such as Salto Space and Visionline, Seam offers the lightweight [Seam Bridge](/capability-guides/seam-bridge) app, at no extra cost. This software-only component runs on a computer within the same local network and creates a secure tunnel between Seam Cloud and the access system. Seam Bridge manages encryption, handles authentication, and removes the need to expose local ports to the internet.

<img alt="Seam Bridge" />

For detailed connection instructions, see the [system integration guide](/device-and-system-integration-guides#access-control-systems) for your access system.


# Using Seam Console to Issue Instant Keys
Source: https://docs.seam.co/use-cases/granting-access/instant-keys/using-seam-console-to-issue-instant-keys

Learn how to issue an Instant Key through Seam Console.

You can use Seam Console to issue Instant Keys. This process assumes that you have already [connected your access system to Seam](/use-cases/granting-access/instant-keys/setting-up-your-site-for-instant-keys#connect-your-access-system-to-seam) and includes the following steps:

1. Create an access system user and corresponding user identity.

2. If your access system supports access groups, assign the user to one or more access groups.

3. Create a mobile key credential.

   If your access system supports direct entrance assignment, during this step, also select the entrances to which you want to grant the user access.

4. Issue an Instant Key for the user identity.

***

## Create a User Identity and Access System User

1. Log in to [Seam Console](https://console.seam.co/).

2. In the upper-left corner, click the workspace switcher and select the production workspace in which your access system is connected.

   <img alt="Use the Seam Console workspace switcher to switch between workspaces and create new workspaces." />

3. In the top navigation pane, click **ACS Systems**.

4. On the **Access Systems** page, click the access system in which you want to grant access to a user.

5. At the upper-left of the access system page, click **Add user**.

   <img
     alt="Click Add user to add the user to whom you want to
   grant access."
   />

6. In the **Add New User** dialog:

   1. Type the full name of the user, as well as a unique email address or phone number.
   2. Specify the start and end dates for the user's access.
   3. Click **Continue**.

   Seam creates the new access system user.

7. On the **Users** table, click the access system user that you created.

   <img alt="Click the new access system user that you created." />

8. At the left of the user page, click **User identity** to expand the **User identity** area.

   <img
     alt="Expand the User identity area to link the access
   system user to a user identity."
   />

9. Click **Link to user identity**.

10. In the **Choose a Seam user identity** dialog, click **New user identity**.

    <img alt="Click <strong>New user identity</strong>." />

11. In the **Add New User Identity** dialog:

    1. Type the full name of the user, as well as a unique email address, phone number, or user identity key.
    2. Click **Save**.

    Seam creates the new user identity and links it to the access system user.

12. If your access system supports access groups:
    1. At the top of the user page, click **Access Groups**.

    2. In the upper-right corner of the user page, click <img alt="" />and select **Manage Access**.

       <img
         alt="Click Manage Access to assign the user to an
       access group."
       />

    3. In the **Manage Access for \[User]** dialog, select the checkbox next to each access group to which you want to add the user and then click **Save**.

13. At the left side of the user page, click **Add Credential**.

    <img
      alt="Click Add Credential to create a mobile key for the
    access system user."
    />

14. In the **Choose type of credential** dialog, click **Seam mobile key**.

15. If your access system supports direct entrance assignment:
    1. In the **Select entrances for \[user]** dialog, select the checkbox next to each entrance to which you want to grant the user access and then click **Next**.
    2. In the **Enter start & end time** dialog, specify the schedule for the user's access and then click **Next**.

16. Click **Done** to confirm the successful credential creation.

17. In the **User identity** area at the left of the user page, click the user identity linked to the access system user.

    <img alt="Click the linked user identity." />

18. In the **Instant Key** area at the left of the user identity page, click **Generate Instant Key**.

    <img
      alt="Click Generate Instant Key. This key contains all the
    mobile credentials for the user identity."
    />

Seam generates an Instant Key and displays the **Instant Key Link** dialog. This dialog displays the following information:

* An Instant Key link that you can copy and share with your user.
* A QR code that you can scan with a mobile device to open the Seam Instant Key App Clip.

<img
  alt="Share the Instant Key link with your user. With no app install required,
your user just taps to unlock."
/>

For more information about sharing Instant Keys with your users, see [Using Instant Keys](/use-cases/granting-access/using-instant-keys).


# Managing Access Grants
Source: https://docs.seam.co/use-cases/granting-access/managing-access-grants

Update the schedule or resources on an Access Grant, or delete a grant entirely when access should end.

After you've [created an Access Grant](/use-cases/granting-access/creating-an-access-grant), circumstances change — a guest extends their stay, a contractor's scope expands to a new building, or a reservation is cancelled. This page covers how to update or delete an Access Grant to handle these situations.

***

## Updating an Access Grant

Use `access_grants.update` when you need to change *when* or *where* a person has access. Common scenarios include:

* **Extended stay:** A hotel guest extends their checkout from Friday to Sunday — update `ends_at`.
* **Early access:** A contractor needs to start a day earlier — update `starts_at`.
* **Scope change:** A resident moves from Unit 101 to Unit 205 — update `device_ids`, `space_ids`, or `acs_entrance_ids`.

### Updating the Schedule

Pass `starts_at` and/or `ends_at` to change the access window. The new schedule applies to all access methods under the grant.

<CodeGroup>
  ```python Python theme={null}
  # Guest extended their stay — push checkout to Sunday
  seam.access_grants.update(
      access_grant_id="ef83cca9-5fdf-4ac2-93f3-c21c5a8be54b",
      ends_at="2025-07-18T11:00:00.000Z",
  )
  ```

  ```javascript JavaScript theme={null}
  // Guest extended their stay — push checkout to Sunday
  await seam.accessGrants.update({
    access_grant_id: "ef83cca9-5fdf-4ac2-93f3-c21c5a8be54b",
    ends_at: "2025-07-18T11:00:00.000Z",
  });
  ```

  ```ruby Ruby theme={null}
  # Guest extended their stay — push checkout to Sunday
  seam.access_grants.update(
    access_grant_id: "ef83cca9-5fdf-4ac2-93f3-c21c5a8be54b",
    ends_at: "2025-07-18T11:00:00.000Z"
  )
  ```

  ```php PHP theme={null}
  // Guest extended their stay — push checkout to Sunday
  $seam->access_grants->update(
      access_grant_id: "ef83cca9-5fdf-4ac2-93f3-c21c5a8be54b",
      ends_at: "2025-07-18T11:00:00.000Z"
  );
  ```

  ```csharp C# theme={null}
  // Coming soon!
  ```

  ```java Java theme={null}
  // Coming soon!
  ```

  ```bash cURL (bash) theme={null}
  # Guest extended their stay — push checkout to Sunday
  curl -X 'POST' \
    'https://connect.getseam.com/access_grants/update' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d '{
      "access_grant_id": "ef83cca9-5fdf-4ac2-93f3-c21c5a8be54b",
      "ends_at": "2025-07-18T11:00:00.000Z"
    }'
  ```
</CodeGroup>

### Updating Resources

Pass `device_ids`, `space_ids`, or `acs_entrance_ids` to change *where* the person has access. For example, if a resident moves units, update the grant to point to the new space instead of deleting and recreating it.

<CodeGroup>
  ```python Python theme={null}
  # Resident moved from Unit 101 to Unit 205
  seam.access_grants.update(
      access_grant_id="ef83cca9-5fdf-4ac2-93f3-c21c5a8be54b",
      space_ids=["b0c5d5e0-7f0a-4f1b-8e3d-unit-205-space"],
  )
  ```

  ```javascript JavaScript theme={null}
  // Resident moved from Unit 101 to Unit 205
  await seam.accessGrants.update({
    access_grant_id: "ef83cca9-5fdf-4ac2-93f3-c21c5a8be54b",
    space_ids: ["b0c5d5e0-7f0a-4f1b-8e3d-unit-205-space"],
  });
  ```

  ```ruby Ruby theme={null}
  # Resident moved from Unit 101 to Unit 205
  seam.access_grants.update(
    access_grant_id: "ef83cca9-5fdf-4ac2-93f3-c21c5a8be54b",
    space_ids: ["b0c5d5e0-7f0a-4f1b-8e3d-unit-205-space"]
  )
  ```

  ```php PHP theme={null}
  // Resident moved from Unit 101 to Unit 205
  $seam->access_grants->update(
      access_grant_id: "ef83cca9-5fdf-4ac2-93f3-c21c5a8be54b",
      space_ids: ["b0c5d5e0-7f0a-4f1b-8e3d-unit-205-space"]
  );
  ```

  ```csharp C# theme={null}
  // Coming soon!
  ```

  ```java Java theme={null}
  // Coming soon!
  ```

  ```bash cURL (bash) theme={null}
  # Resident moved from Unit 101 to Unit 205
  curl -X 'POST' \
    'https://connect.getseam.com/access_grants/update' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d '{
      "access_grant_id": "ef83cca9-5fdf-4ac2-93f3-c21c5a8be54b",
      "space_ids": ["b0c5d5e0-7f0a-4f1b-8e3d-unit-205-space"]
    }'
  ```
</CodeGroup>

***

## Re-issuance After an Update

When you update an Access Grant, Seam needs to re-program the credentials on the affected devices. During this process, each access method temporarily becomes invalid.

### What happens to each access method

1. Seam emits an `access_method.revoked` event and sets `is_issued` to `false`. The credential is no longer valid on the device.
2. Seam re-programs the credential with the updated schedule or resources.
3. Once the credential is active again, the next step depends on the mode:

| Mode           | What happens                                                                                 | Event                                                                                |
| -------------- | -------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
| **PIN code**   | The code value stays the same. Seam updates the valid time window on the lock automatically. | `access_method.reissued`                                                             |
| **Mobile key** | Seam updates the credential automatically.                                                   | `access_method.reissued`                                                             |
| **Cloud key**  | Seam updates the credential automatically.                                                   | `access_method.reissued`                                                             |
| **Card**       | The physical card must be re-encoded with the new credential.                                | `access_method.card_encoding_required`, then `access_method.reissued` after encoding |

<Info>
  For cards, you'll need to [re-encode the card](/low-level-apis/access-systems/working-with-card-encoders-and-scanners/creating-and-encoding-card-access-methods) before the updated credential takes effect. Plan for this if your workflow relies on physical cards — the guest will need to visit the front desk.
</Info>

### Listening for re-issuance events

Use [webhooks](/developer-tools/webhooks) or poll `access_methods.list` to track when access methods become valid again after an update:

* **`access_method.revoked`** — The credential has been invalidated and is being re-programmed. The access method's `is_issued` is `false`.
* **`access_method.card_encoding_required`** — (Cards only) The new credential is ready but needs to be encoded onto the physical card.
* **`access_method.reissued`** — The credential is active again. The access method's `is_issued` is `true`.

***

## Deleting an Access Grant

Delete an Access Grant when a person's access should end entirely — for example, when a guest checks out, an employee is offboarded, or a contractor's engagement ends. Deleting the grant removes **all** access methods under it at once.

<CodeGroup>
  ```python Python theme={null}
  # Guest checked out — revoke all access
  seam.access_grants.delete(
      access_grant_id="ef83cca9-5fdf-4ac2-93f3-c21c5a8be54b"
  )
  ```

  ```javascript JavaScript theme={null}
  // Guest checked out — revoke all access
  await seam.accessGrants.delete({
    access_grant_id: "ef83cca9-5fdf-4ac2-93f3-c21c5a8be54b",
  });
  ```

  ```ruby Ruby theme={null}
  # Guest checked out — revoke all access
  seam.access_grants.delete(
    access_grant_id: "ef83cca9-5fdf-4ac2-93f3-c21c5a8be54b"
  )
  ```

  ```php PHP theme={null}
  // Guest checked out — revoke all access
  $seam->access_grants->delete(
      access_grant_id: "ef83cca9-5fdf-4ac2-93f3-c21c5a8be54b"
  );
  ```

  ```csharp C# theme={null}
  // Coming soon!
  ```

  ```java Java theme={null}
  // Coming soon!
  ```

  ```bash cURL (bash) theme={null}
  # Guest checked out — revoke all access
  curl -X 'POST' \
    'https://connect.getseam.com/access_grants/delete' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d '{"access_grant_id": "ef83cca9-5fdf-4ac2-93f3-c21c5a8be54b"}'
  ```
</CodeGroup>

Seam emits an `access_grant.deleted` event and an `access_method.deleted` event for each access method that was removed.

<Info>
  To revoke a single access method while keeping the rest active (for example, disabling a lost key card but keeping the guest's PIN code), use [`access_methods.delete`](/use-cases/granting-access/managing-access-methods#revoking-an-access-method) instead.
</Info>

### Delete vs. Update

| Scenario                                                     | Action                                                                                                                      |
| ------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------- |
| Guest checks out, employee offboards — all access should end | **Delete** the Access Grant                                                                                                 |
| Guest extends stay, schedule changes                         | **Update** `starts_at` / `ends_at`                                                                                          |
| Person moves to a different unit or building                 | **Update** `device_ids`, `space_ids`, or `acs_entrance_ids`                                                                 |
| One credential is lost but the person still needs access     | [**Delete** the access method](/use-cases/granting-access/managing-access-methods#revoking-an-access-method), not the grant |


# Managing Access Methods
Source: https://docs.seam.co/use-cases/granting-access/managing-access-methods

Add new access methods to an existing Access Grant or revoke individual credentials.

After you've [created an Access Grant](/use-cases/granting-access/creating-an-access-grant) and delivered the initial credentials, you may need to add new access methods or revoke existing ones — without changing the grant itself.

This page covers operations on **individual access methods**. To update the schedule, resources, or delete the entire grant, see [Managing Access Grants](/use-cases/granting-access/managing-access-grants).

***

## Adding an Access Method

A single Access Grant can have multiple access methods. You can add new ones at any time — for example:

* A guest originally received a PIN code but now also wants a **mobile key** for hands-free entry.
* A building manager needs to issue a **key card** for a contractor who doesn't have a smartphone.
* An office tenant wants to add a **cloud key** so their front desk app can trigger remote unlocks for visitors.

The new access method inherits the schedule and resources from the existing Access Grant automatically.

<CodeGroup>
  ```python Python theme={null}
  # Guest wants a mobile key in addition to their PIN code
  access_method = seam.access_methods.create(
      access_grant_id="ef83cca9-5fdf-4ac2-93f3-c21c5a8be54b",
      mode="mobile_key",
  )
  ```

  ```javascript JavaScript theme={null}
  // Guest wants a mobile key in addition to their PIN code
  const accessMethod = await seam.accessMethods.create({
    access_grant_id: "ef83cca9-5fdf-4ac2-93f3-c21c5a8be54b",
    mode: "mobile_key",
  });
  ```

  ```ruby Ruby theme={null}
  # Guest wants a mobile key in addition to their PIN code
  access_method = seam.access_methods.create(
    access_grant_id: "ef83cca9-5fdf-4ac2-93f3-c21c5a8be54b",
    mode: "mobile_key"
  )
  ```

  ```php PHP theme={null}
  // Guest wants a mobile key in addition to their PIN code
  $access_method = $seam->access_methods->create(
      access_grant_id: "ef83cca9-5fdf-4ac2-93f3-c21c5a8be54b",
      mode: "mobile_key"
  );
  ```

  ```csharp C# theme={null}
  // Coming soon!
  ```

  ```java Java theme={null}
  // Coming soon!
  ```

  ```bash cURL (bash) theme={null}
  # Guest wants a mobile key in addition to their PIN code
  curl -X 'POST' \
    'https://connect.getseam.com/access_methods/create' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d '{
      "access_grant_id": "ef83cca9-5fdf-4ac2-93f3-c21c5a8be54b",
      "mode": "mobile_key"
    }'
  ```
</CodeGroup>

Once created, deliver the new access method the same way as any other — see the delivery guides for [PIN codes](/use-cases/granting-access/using-pin-codes), [mobile keys](/use-cases/granting-access/using-mobile-keys), [key cards](/use-cases/granting-access/using-key-cards), [instant keys](/use-cases/granting-access/using-instant-keys), or [cloud keys](/use-cases/granting-access/using-cloud-keys).

***

## Revoking an Access Method

Revoke a single access method when you need to disable one credential while keeping the rest active. Common scenarios include:

* A guest **lost their key card** — revoke the card but keep their PIN code working so they're not locked out.
* A tenant's **phone was stolen** — revoke the mobile key immediately while a replacement is set up.
* A temporary **cloud key** was issued for a one-time visitor and is no longer needed.

<CodeGroup>
  ```python Python theme={null}
  # Guest lost their key card — revoke it, keep PIN active
  seam.access_methods.delete(
      access_method_id="f47ac10b-58cc-4372-a567-0e02b2c3d479"
  )
  ```

  ```javascript JavaScript theme={null}
  // Guest lost their key card — revoke it, keep PIN active
  await seam.accessMethods.delete({
    access_method_id: "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  });
  ```

  ```ruby Ruby theme={null}
  # Guest lost their key card — revoke it, keep PIN active
  seam.access_methods.delete(
    access_method_id: "f47ac10b-58cc-4372-a567-0e02b2c3d479"
  )
  ```

  ```php PHP theme={null}
  // Guest lost their key card — revoke it, keep PIN active
  $seam->access_methods->delete(
      access_method_id: "f47ac10b-58cc-4372-a567-0e02b2c3d479"
  );
  ```

  ```csharp C# theme={null}
  // Coming soon!
  ```

  ```java Java theme={null}
  // Coming soon!
  ```

  ```bash cURL (bash) theme={null}
  # Guest lost their key card — revoke it, keep PIN active
  curl -X 'POST' \
    'https://connect.getseam.com/access_methods/delete' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d '{"access_method_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479"}'
  ```
</CodeGroup>

Seam removes the credential from the device or access system and emits an `access_method.deleted` event. Other access methods under the same Access Grant are unaffected.

<Info>
  To revoke **all** access for a person at once — for example, on checkout or offboarding — [delete the entire Access Grant](/use-cases/granting-access/managing-access-grants#deleting-an-access-grant) instead.
</Info>

### Revoke and Replace

A common pattern is to revoke a compromised credential and immediately issue a replacement:

<CodeGroup>
  ```python Python theme={null}
  # Revoke the lost card
  seam.access_methods.delete(
      access_method_id="f47ac10b-58cc-4372-a567-0e02b2c3d479"
  )

  # Issue a replacement card under the same grant
  new_card = seam.access_methods.create(
      access_grant_id="ef83cca9-5fdf-4ac2-93f3-c21c5a8be54b",
      mode="card",
  )
  ```

  ```javascript JavaScript theme={null}
  // Revoke the lost card
  await seam.accessMethods.delete({
    access_method_id: "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  });

  // Issue a replacement card under the same grant
  const newCard = await seam.accessMethods.create({
    access_grant_id: "ef83cca9-5fdf-4ac2-93f3-c21c5a8be54b",
    mode: "card",
  });
  ```

  ```ruby Ruby theme={null}
  # Revoke the lost card
  seam.access_methods.delete(
    access_method_id: "f47ac10b-58cc-4372-a567-0e02b2c3d479"
  )

  # Issue a replacement card under the same grant
  new_card = seam.access_methods.create(
    access_grant_id: "ef83cca9-5fdf-4ac2-93f3-c21c5a8be54b",
    mode: "card"
  )
  ```

  ```php PHP theme={null}
  // Revoke the lost card
  $seam->access_methods->delete(
      access_method_id: "f47ac10b-58cc-4372-a567-0e02b2c3d479"
  );

  // Issue a replacement card under the same grant
  $new_card = $seam->access_methods->create(
      access_grant_id: "ef83cca9-5fdf-4ac2-93f3-c21c5a8be54b",
      mode: "card"
  );
  ```

  ```csharp C# theme={null}
  // Coming soon!
  ```

  ```java Java theme={null}
  // Coming soon!
  ```

  ```bash cURL (bash) theme={null}
  # Revoke the lost card
  curl -X 'POST' \
    'https://connect.getseam.com/access_methods/delete' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d '{"access_method_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479"}'

  # Issue a replacement card under the same grant
  curl -X 'POST' \
    'https://connect.getseam.com/access_methods/create' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d '{
      "access_grant_id": "ef83cca9-5fdf-4ac2-93f3-c21c5a8be54b",
      "mode": "card"
    }'
  ```
</CodeGroup>

The replacement card will need to be [encoded](/use-cases/granting-access/using-key-cards) before it's ready for the guest.


# Reservation Access Grants
Source: https://docs.seam.co/use-cases/granting-access/reservation-access-grants

Learn how to use reservation_key with Access Grants to handle guest and resident credentials on offline access systems.

## Overview

In hotel or multifamily buildings, many locks aren’t always connected to the internet. Instead, they make decisions locally using information stored on cards, fobs, or mobile keys. When someone issues a new credential for a room or unit, the lock uses an override model, where the new credential replaces or invalidates previous ones, like from a past guest or tenant.

For these systems, you need to use the **reservation** model to manage override behavior. This scope includes Dormakaba Community and Ambiance, Visionline, and Vostio. This differs from fully online systems like Brivo or Avigilon Alta, where access decisions happen in real time through the cloud.

***

### When to use reservations

#### **Guest vs. Staff Credentials**

Not all credentials behave the same way, and this determines when you need to use the reservation model.

* **Guest or resident credentials** usually follow an override model: issuing a new credential overrides previous ones for that space. For these credentials, using the reservation model is **required** on these override-based access systems.
* **Staff credentials** typically use separate credential types and lifecycles. They don’t override guest credentials, and guest credentials don’t override them. You can issue these as standard Access Grants without setting a `reservation_key`.

Use reservations when issuing guest or resident credentials on systems that rely on offline override behavior. For staff or persistent shared access, reservations usually aren’t needed.

***

### Override and Joiner Behavior

In these systems, locks don’t receive live updates from the cloud. Instead, access changes happen through credentials (cards, fobs, or mobile keys) that carry data to the lock.

* **Override behavior:** When a new credential is issued for a room or unit, the new credential contains data that causes the lock to replace or invalidate previous ones. For example, when a new guest checks in, their credential overrides the previous guest’s access without requiring the lock to be online.
* **Joiner behavior:** These systems also support joiner behavior, where multiple valid credentials can coexist for a stay. This happens, for example, when multiple guests need access under the same reservation. In these cases, the lock grants access to all valid credentials simultaneously.

This behavior applies only to **guest and resident credentials**. Staff credentials follow a separate path and aren’t subject to override or joiner rules.

***

### **How `reservation_key` works**

A **reservation** groups related Access Grants under a shared `reservation_key`, letting Seam apply the override and joiner behavior consistently across providers. When you create the first Access Grant with a new `reservation_key` for a space, Seam issues credentials that start a new reservation and override any previous reservation. Additional Access Grants with the same key join that reservation, so multiple guests or residents can share access during the same stay. Creating an Access Grant with a different key for the same space starts a new reservation and overrides access for the existing one. Entrances that don’t support reservation behavior are provisioned as standard access, such as common area doors where overrides aren’t needed.

***

## Issuing Access Grants with Reservations

### **1. Identify the user and entrances to grant access to.**

Create a user identity for the user to whom you want to grant access.

Identify the entrances (or spaces) the user should have access to.

***

### **2. Check entrance capabilities**

If you’re looking to issue a guest or resident credential, use the [Entrances API](/api/acs/entrances/object) to confirm which entrances support reservation semantics.

```text theme={null}
const entrances = await seam.acs.entrances.list({ space_id: "room-101" })
const entrances_that_support_reservations = entrances.filter(e => e.can_belong_to_reservation)
```

* If at least one entrance supports reservations → include a `reservation_key`.
* If none do → issue a standard access grant (omit `reservation_key`).

#### **For mixed grants: Reservation-capable + non-capable entrances**

When a single Access Grant includes a mix of entrances, Seam applies reservation behavior per entrance.

* Entrances with `can_belong_to_reservation: true` join or override based on `reservation_key`.
* Entrances without the `can_belong_to_reservation` capability ignore `reservation_key` and do not override credentials.

```tsx theme={null}
await seam.accessGrants.create({
  user_identity_id: 'guest-1',
  acs_entrance_ids: ['room-101-id', 'gym-id', 'lobby-id'],
  starts_at: '2025-05-10T15:00:00Z',
  ends_at: '2025-05-14T11:00:00Z',
  requested_access_methods: [{ mode: 'card' }],
  reservation_key: 'stay-1', // applied only to room-101
})
```

#### **What to expect**

* Room 101 (capable): credentials participate in override / join for `stay-1`.
* Gym/Lobby (non-capable): credentials are provisioned normally and never override credentials based on `reservation_key`.

***

### **3. Create the access grant with `reservation_key`**

Pass the `reservation_key` to group related grants and let Seam apply override/joiner behavior consistently.

```text theme={null}
await seam.accessGrants.create({
  user_identity_id: "guest-1",
  acs_entrance_ids: ["room-101-id"],
  starts_at: "2025-05-10T15:00:00Z",
  ends_at: "2025-05-14T11:00:00Z",
  requested_access_methods: [{ mode: "card" }],
  reservation_key: "stay-1",
})
```

***

### **4. Seam provisions credentials**

Seam chooses the correct credential type (e.g., guest vs. staff) and applies provider-native behavior. When the new credential is used at the lock:

* If it’s a new reservation, it overrides previous guest credentials.
* If it’s the same reservation, it joins.
* Staff credentials remain unaffected.

After provisioning, Seam exposes the issued credentials as **access methods**, which represent the actual, deliverable means of entry (e.g., encoded cards, mobile keys, PINs). You can fetch these via the Access Methods API, display them in your app, or encode them onto physical cards for delivery to the user.

[See the Access Methods guide for details on retrieving and delivering credentials.](/use-cases/granting-access/creating-an-access-grant)

***

## **Rules and Validation**

### **Rule 1: `reservation_key` requires at least one capable entrance**

If **none** of the targeted entrances support reservations, creation fails.

```tsx theme={null}
await seam.accessGrants.create({
  user_identity_id: 'guest-1',
  acs_entrance_ids: ['gym-id', 'pool-id'],
  starts_at,
  ends_at,
  requested_access_methods: [{ mode: 'card' }],
  reservation_key: 'stay-1',
})
/*
HTTP 400 VALIDATION_ERROR
title: "reservation_key not supported."
message: "No targeted entrances support reservation behavior. Remove reservation_key or include at least one reservation-capable entrance."
*/
```

### Rule 2: **The reservation door set is fixed once established**

For reservation-capable entrances, the **first access grant** with a new `reservation_key` establishes the **reservation door set**.

You can’t issue concurrent grants that change this set (e.g., switch rooms) without clearing the existing grants first.

```tsx theme={null}
// existing: stay-1 on room-101

// creating a new access grant with different doors
await seam.accessGrants.create({
  user_identity_id: 'guest-1',
  space_ids: ['room-203'], // different door
  starts_at,
  ends_at,
  requested_access_methods: [{ mode: 'card' }],
  reservation_key: 'stay-1',
})
/*
HTTP 409 CONFLICT
title: "Reservation entrance change requires cleanup."
message: "To change the doors for this reservation, delete the existing access
grants first."
*/

const access_grants = await seam.accessGrants.list({
  reservation_key: 'stay-1',
})
for (const { access_grant_id } of access_grants) {
  await seam.accessGrants.delete({ access_grant_id })
}
await seam.accessGrants.create({
  user_identity_id: 'guest-1',
  space_ids: ['room-203'], // different door
  starts_at,
  ends_at,
  requested_access_methods: [{ mode: 'card' }],
  reservation_key: 'stay-1',
})
```

### Rule 3: **Joiners can target subsets of reservation-capable doors**

For **reservation-capable entrances**, additional access grants with the same `reservation_key` can target **subsets** of the established reservation door set.

This allows, for example, giving one guest full access and another guest limited access within the same stay.

Issuing a **superset** of reservation-capable doors isn’t allowed. If you need to expand the set (e.g., adding a new unit), clear the existing grants first and reissue with the new set.

\<aside> 💡

Entrances that don’t support reservations are not included in the subset/superset check. You can include any combination of non-capable entrances without triggering this rule.

\</aside>

```tsx theme={null}
// Reservation has room-101 (reservation-capable door)

// ✅ Valid: subset joiner
await seam.accessGrants.create({
  user_identity_id: 'guest-2',
  space_ids: ['room-101'], // subset
  starts_at,
  ends_at,
  reservation_key: 'stay-1',
})

// ❌ Invalid: superset joiner (adds 102)
await seam.accessGrants.create({
  user_identity_id: 'guest-3',
  space_ids: ['room-101', 'room-102'], // superset of reservation-capable set
  starts_at,
  ends_at,
  reservation_key: 'stay-1',
})
/*
HTTP 409 CONFLICT
title: "Reservation joiner entrance set conflict."
message: "Joiner access grants must use the same or a subset of the
reservation-capable doors."
*/
```

### **Rule 4: Time frames must overlap**

All access grants within the same `reservation_key` must have **overlapping time frames** for their reservation-capable entrances.

This ensures the underlying system treats the credentials as part of the same stay or lease and applies proper joiner behavior.

* If the time frames **overlap**, the new grant joins the existing reservation.
* If the time frames **don’t overlap**, the new grant is treated as a separate stay and must use a different reservation\_key.

```tsx theme={null}
// ✅ Valid: overlapping time frames
await seam.accessGrants.create({
  user_identity_id: 'guest-1',
  space_ids: ['room-101'],
  starts_at: '2025-05-10T15:00:00Z',
  ends_at: '2025-05-14T11:00:00Z',
  reservation_key: 'stay-1',
})

// joiner with overlapping window
await seam.accessGrants.create({
  user_identity_id: 'guest-2',
  space_ids: ['room-101'],
  starts_at: '2025-05-11T11:00:00Z', // overlaps with guest-1
  ends_at: '2025-05-14T11:00:00Z',
  reservation_key: 'stay-1',
})

// ❌ Invalid: non-overlapping time frames
await seam.accessGrants.create({
  user_identity_id: 'guest-3',
  space_ids: ['room-101'],
  starts_at: '2025-05-15T15:00:00Z', // no overlap with guest-1
  ends_at: '2025-05-18T11:00:00Z',
  reservation_key: 'stay-1',
})
/*
HTTP 409 CONFLICT
title: "Reservation time frames must overlap."
message: "Access grants in the same reservation must have overlapping time
frames."
*/
```

***

## Common scenarios

This section walks through common hospitality and multifamily scenarios to illustrate how `reservation_key` drives override and joiner behavior in Seam. Each example shows how Access Grants interact with locks under real operational conditions.

### 1. Back-to-back reservations

Two reservations for the same unit are scheduled back-to-back, with one guest checking out at 11 AM and the next checking in at 3 PM. When you issue the second Access Grant with a different `reservation_key`, Seam provisions it to override the previous stay. Once the new guest uses their credential at the door, the prior guest’s credential is invalidated automatically.

```jsx theme={null}
// guest 1 (sat → wed)
await seam.accessGrants.create({
  user_identity_id: 'guest-1',
  space_ids: ['room-101'],
  starts_at: '2025-05-10T15:00:00Z',
  ends_at: '2025-05-14T11:00:00Z',
  requested_access_methods: [{ mode: 'card' }],
  reservation_key: 'stay-1',
})

// guest 2 (wed → fri) — different key → overrides guest 1 on first use
await seam.accessGrants.create({
  user_identity_id: 'guest-2',
  space_ids: ['room-101'],
  starts_at: '2025-05-14T15:00:00Z',
  ends_at: '2025-05-16T11:00:00Z',
  requested_access_methods: [{ mode: 'card' }],
  reservation_key: 'stay-2',
})
```

***

### 2. **Multiple guests on the same reservation**

A single reservation includes multiple guests who all need access during the same stay. By issuing Access Grants with the same `reservation_key`, Seam provisions the credentials as joiners. All guests’ credentials remain valid for the duration of the reservation, and the lock treats them as part of the same lease.

```jsx theme={null}
// guest 1
await seam.accessGrants.create({
  user_identity_id: 'g1',
  space_ids: ['room-101'],
  starts_at,
  ends_at,
  requested_access_methods: [{ mode: 'card' }],
  reservation_key: 'stay-1',
})

// guest 2 joins the same lease
await seam.accessGrants.create({
  user_identity_id: 'g2',
  space_ids: ['room-101'],
  starts_at,
  ends_at,
  requested_access_methods: [{ mode: 'card' }],
  reservation_key: 'stay-1',
})
```

***

### 3. Relocate a reservation to new room

When a guest switches rooms mid-stay, the existing Access Grants for the original room must be fully cleared before creating new ones. Seam doesn’t allow issuing Access Grants with different door assignments for the same `reservation_key` at the same time. This reflects how underlying systems work—they require the previous access to be overridden before new room assignments can take effect.

```jsx theme={null}
// original room
const oldGrant = await seam.accessGrants.create({
  user_identity_id: 'guest-1',
  space_ids: ['room-101'],
  starts_at: '2025-05-10T15:00:00Z',
  ends_at: '2025-05-14T11:00:00Z',
  requested_access_methods: [{ mode: 'card' }],
  reservation_key: 'stay-1',
})

// move to new room with same reservation identity
await seam.accessGrants.delete({ access_grant_id: oldGrant.access_grant_id })
// seam may surface warnings if physical cards still exist (collect/cancel)

await seam.accessGrants.create({
  user_identity_id: 'guest-1',
  space_ids: ['room-203'],
  starts_at: '2025-05-10T15:30:00Z',
  ends_at: '2025-05-14T11:00:00Z',
  requested_access_methods: [{ mode: 'card' }],
  reservation_key: 'stay-1',
})
```

***

### 4. **Reservation time frame changes**

When you change `starts_at` / `ends_at`, Seam updates the **Access Grant**, but already-issued physical credentials on offline systems don’t automatically change. Seam will flag what you need to do next.

```jsx theme={null}
// extend the reservation window
await seam.accessGrants.update({
  access_grant_id: 'ag_123',
  ends_at: '2025-05-16T11:00:00Z',
})

// fetch current status and next steps
const grant = await seam.accessGrants.get({ access_grant_id: 'ag_123' })

/*
grant.warnings might include:
- "encoding_required": re-encode a plastic card for the new dates
*/
```

The warning can be resolved by re-encoding the card.

```jsx theme={null}
const cards = await seam.access_methods.list({
	access_grant_id
})

// (example) re-encode the plastic card for the new reservation window
await seam.acs.encoders.encode_card({
	cards[0].access_method_id,
	acs_encoder_id: "encoder-1"
})
```

***

## Error codes & troubleshooting

This section lists common validation and conflict errors you may encounter when creating Access Grants with `reservation_key`, along with what they mean and how to resolve them.

|                                                                                                |                                                                                                                                                                                                                                                                                                                                                         |                                                               |
| ---------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- |
| not supported.                                                                                 | You passed a  but none of the targeted entrances support reservations.                                                                                                                                                                                                                                                                                  | Remove  or include at least one reservation-capable entrance. |
| required for guest cards.                                                                      | The targeted provider requires a reservation for guest credentials (e.g., Visionline) but none was provided.                                                                                                                                                                                                                                            | Add a  when issuing guest credentials for these entrances.    |
| You tried to issue an access grant with a different door set for an existing reservation.      | List and delete existing access grants for that , then reissue with the new door set. List and delete existing access grants for that , then reissue with the new door set. List and delete existing access grants for that , then reissue with the new door set. List and delete existing access grants for that , then reissue with the new door set. |                                                               |
| A joiner grant includes a superset of the reservation-capable doors.                           | Joiners must use the same or a subset of the reservation-capable doors. Adjust the door set or clear/reissue.                                                                                                                                                                                                                                           |                                                               |
| A new access grant’s time frame doesn’t overlap with existing grants for the same reservation. | Either adjust the time frame to overlap or use a new  for the separate stay. Either adjust the time frame to overlap or use a new  for the separate stay. Either adjust the time frame to overlap or use a new  for the separate stay. Either adjust the time frame to overlap or use a new  for the separate stay.                                     |                                                               |


# Using Cloud Keys
Source: https://docs.seam.co/use-cases/granting-access/using-cloud-keys

Learn how to use cloud keys to trigger web-based unlocks attributed to specific user identities in the ACS audit trail.

Cloud keys are a web-based unlock access method. When you use a cloud key, the door unlocks over the internet through the ACS cloud connection. Each unlock is attributed to the specific user identity in the ACS audit trail, rather than being recorded as a generic system action.

Cloud keys are ideal for:

* **Web pass shared via link:** Send your user a URL that triggers a remote unlock when tapped.
* **Embedded unlock in your app:** Add an unlock button to your web or mobile app that calls the Seam API to unlock the door.

## Before You Begin

To use cloud keys, you need:

* A [Seam API key](https://console.seam.co)
* A connected ACS that supports cloud key unlocks
* A [user identity](/capability-guides/mobile-access/managing-mobile-app-user-accounts-with-user-identities) representing the person who will unlock the door
* An entrance that supports cloud key unlocks (`can_unlock_with_cloud_key` is `true`)

## Step 1: Verify Entrance Support

List the entrances for your ACS and confirm that `can_unlock_with_cloud_key` is `true` for the entrance you want to unlock.

<CodeGroup>
  ```javascript JavaScript theme={null}
  const entrances = await seam.acs.entrances.list({
    acs_system_id: 'c359cba2-8ef2-47fc-bee0-1c7c2a886339',
  })

  const cloudKeyEntrances = entrances.filter(
    (e) => e.can_unlock_with_cloud_key
  )
  ```

  ```python Python theme={null}
  entrances = seam.acs.entrances.list(
      acs_system_id="c359cba2-8ef2-47fc-bee0-1c7c2a886339"
  )

  cloud_key_entrances = [
      e for e in entrances if e.can_unlock_with_cloud_key
  ]
  ```

  ```ruby Ruby theme={null}
  entrances = seam.acs.entrances.list(
    acs_system_id: "c359cba2-8ef2-47fc-bee0-1c7c2a886339"
  )

  cloud_key_entrances = entrances.select do |e|
    e.can_unlock_with_cloud_key
  end
  ```

  ```php PHP theme={null}
  $entrances = $seam->acs->entrances->list(
    acs_system_id: "c359cba2-8ef2-47fc-bee0-1c7c2a886339"
  );

  $cloudKeyEntrances = array_filter(
    $entrances,
    fn($e) => $e->can_unlock_with_cloud_key
  );
  ```

  ```csharp C# theme={null}
  var entrances = seam.Acs.Entrances.List(
    acsSystemId: "c359cba2-8ef2-47fc-bee0-1c7c2a886339"
  );

  var cloudKeyEntrances = entrances
    .Where(e => e.CanUnlockWithCloudKey)
    .ToList();
  ```

  ```java Java theme={null}
  var entrances = seam.acs().entrances().list(
    AcsEntrancesListRequest.builder()
      .acsSystemId("c359cba2-8ef2-47fc-bee0-1c7c2a886339")
      .build()
  );
  ```

  ```bash cURL theme={null}
  curl -X 'POST' \
    'https://connect.getseam.com/acs/entrances/list' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d '{
    "acs_system_id": "c359cba2-8ef2-47fc-bee0-1c7c2a886339"
  }'
  ```
</CodeGroup>

**Output:**

```json theme={null}
[
  {
    "acs_entrance_id": "f74e4879-5991-4e2f-a368-888983dcfbfc",
    "display_name": "Main Entrance",
    "can_unlock_with_cloud_key": true,
    ...
  }
]
```

## Step 2: Create an Access Grant with a Cloud Key

Create an [Access Grant](/use-cases/granting-access/index) for the user identity, specifying `cloud_key` as the requested access method mode. Include the entrance IDs that the user should be able to unlock.

<CodeGroup>
  ```javascript JavaScript theme={null}
  const accessGrant = await seam.accessGrants.create({
    user_identity_id: '22222222-2222-2222-2222-222222222222',
    acs_entrance_ids: ['f74e4879-5991-4e2f-a368-888983dcfbfc'],
    requested_access_methods: [
      { mode: 'cloud_key' }
    ],
  })
  ```

  ```python Python theme={null}
  access_grant = seam.access_grants.create(
      user_identity_id="22222222-2222-2222-2222-222222222222",
      acs_entrance_ids=["f74e4879-5991-4e2f-a368-888983dcfbfc"],
      requested_access_methods=[{"mode": "cloud_key"}],
  )
  ```

  ```ruby Ruby theme={null}
  access_grant = seam.access_grants.create(
    user_identity_id: "22222222-2222-2222-2222-222222222222",
    acs_entrance_ids: ["f74e4879-5991-4e2f-a368-888983dcfbfc"],
    requested_access_methods: [{ mode: "cloud_key" }]
  )
  ```

  ```php PHP theme={null}
  $accessGrant = $seam->access_grants->create(
    user_identity_id: "22222222-2222-2222-2222-222222222222",
    acs_entrance_ids: ["f74e4879-5991-4e2f-a368-888983dcfbfc"],
    requested_access_methods: [["mode" => "cloud_key"]]
  );
  ```

  ```csharp C# theme={null}
  var accessGrant = seam.AccessGrants.Create(
    userIdentityId: "22222222-2222-2222-2222-222222222222",
    acsEntranceIds: new List<string>
    {
      "f74e4879-5991-4e2f-a368-888983dcfbfc"
    },
    requestedAccessMethods: new List<RequestedAccessMethod>
    {
      new RequestedAccessMethod { Mode = "cloud_key" }
    }
  );
  ```

  ```java Java theme={null}
  var accessGrant = seam.accessGrants().create(
    AccessGrantsCreateRequest.builder()
      .userIdentityId("22222222-2222-2222-2222-222222222222")
      .acsEntranceIds(List.of(
        "f74e4879-5991-4e2f-a368-888983dcfbfc"
      ))
      .requestedAccessMethods(List.of(
        RequestedAccessMethod.builder()
          .mode("cloud_key")
          .build()
      ))
      .build()
  );
  ```

  ```bash cURL theme={null}
  curl -X 'POST' \
    'https://connect.getseam.com/access_grants/create' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d '{
    "user_identity_id": "22222222-2222-2222-2222-222222222222",
    "acs_entrance_ids": ["f74e4879-5991-4e2f-a368-888983dcfbfc"],
    "requested_access_methods": [{ "mode": "cloud_key" }]
  }'
  ```
</CodeGroup>

**Output:**

```json theme={null}
{
  "access_grant_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "user_identity_id": "22222222-2222-2222-2222-222222222222",
  "access_method_ids": ["99887766-5544-3322-1100-aabbccddeeff"],
  "requested_access_methods": [
    { "mode": "cloud_key" }
  ],
  ...
}
```

## Step 3: See Which Doors an Access Method Covers

An access method can cover multiple doors — for example, if the Access Grant includes several entrances or spaces. To see which doors a cloud key can unlock, call `/access_methods/get_related`.

<CodeGroup>
  ```javascript JavaScript theme={null}
  const related = await seam.accessMethods.getRelated({
    access_method_ids: [accessMethod.access_method_id],
  })

  console.log(related.acs_entrances) // entrances this cloud key can unlock
  ```

  ```python Python theme={null}
  related = seam.access_methods.get_related(
      access_method_ids=[access_method.access_method_id]
  )

  print(related.acs_entrances)  # entrances this cloud key can unlock
  ```

  ```ruby Ruby theme={null}
  related = seam.access_methods.get_related(
    access_method_ids: [access_method.access_method_id]
  )

  puts related.acs_entrances  # entrances this cloud key can unlock
  ```

  ```php PHP theme={null}
  $related = $seam->access_methods->get_related(
    access_method_ids: [$accessMethod->access_method_id]
  );

  echo json_encode($related->acs_entrances);  // entrances this cloud key can unlock
  ```

  ```csharp C# theme={null}
  var related = seam.AccessMethods.GetRelated(
    accessMethodIds: new List<string> { accessMethod.AccessMethodId }
  );

  // related.AcsEntrances — entrances this cloud key can unlock
  ```

  ```java Java theme={null}
  var related = seam.accessMethods().getRelated(
    AccessMethodsGetRelatedRequest.builder()
      .accessMethodIds(List.of(accessMethod.getAccessMethodId()))
      .build()
  );
  ```

  ```bash cURL theme={null}
  curl -X 'POST' \
    'https://connect.getseam.com/access_methods/get_related' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d '{
    "access_method_ids": ["99887766-5544-3322-1100-aabbccddeeff"]
  }'
  ```
</CodeGroup>

## Step 4: Unlock the Entrance

Once the access grant is active, unlock the entrance on behalf of the user by calling `/access_methods/unlock_door` with the cloud key `access_method_id` and the `acs_entrance_id`. The endpoint resolves the credential internally and attributes the unlock to the user identity in the ACS audit trail.

<CodeGroup>
  ```javascript JavaScript theme={null}
  const actionAttempt = await seam.accessMethods.unlockDoor({
    access_method_id: '99887766-5544-3322-1100-aabbccddeeff',
    acs_entrance_id: 'f74e4879-5991-4e2f-a368-888983dcfbfc',
  })
  ```

  ```python Python theme={null}
  action_attempt = seam.access_methods.unlock_door(
      access_method_id="99887766-5544-3322-1100-aabbccddeeff",
      acs_entrance_id="f74e4879-5991-4e2f-a368-888983dcfbfc",
  )
  ```

  ```ruby Ruby theme={null}
  action_attempt = seam.access_methods.unlock_door(
    access_method_id: "99887766-5544-3322-1100-aabbccddeeff",
    acs_entrance_id: "f74e4879-5991-4e2f-a368-888983dcfbfc"
  )
  ```

  ```php PHP theme={null}
  $actionAttempt = $seam->access_methods->unlock_door(
    access_method_id: "99887766-5544-3322-1100-aabbccddeeff",
    acs_entrance_id: "f74e4879-5991-4e2f-a368-888983dcfbfc"
  );
  ```

  ```csharp C# theme={null}
  var actionAttempt = seam.AccessMethods.UnlockDoor(
    accessMethodId: "99887766-5544-3322-1100-aabbccddeeff",
    acsEntranceId: "f74e4879-5991-4e2f-a368-888983dcfbfc"
  );
  ```

  ```java Java theme={null}
  var actionAttempt = seam.accessMethods().unlockDoor(
    AccessMethodsUnlockDoorRequest.builder()
      .accessMethodId("99887766-5544-3322-1100-aabbccddeeff")
      .acsEntranceId("f74e4879-5991-4e2f-a368-888983dcfbfc")
      .build()
  );
  ```

  ```bash cURL theme={null}
  curl -X 'POST' \
    'https://connect.getseam.com/access_methods/unlock_door' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d '{
    "access_method_id": "99887766-5544-3322-1100-aabbccddeeff",
    "acs_entrance_id": "f74e4879-5991-4e2f-a368-888983dcfbfc"
  }'
  ```
</CodeGroup>

**Output:**

```json theme={null}
{
  "action_attempt_id": "5f4e3d2c-1b0a-9f8e-7d6c-5b4a3c2d1e0f",
  "action_type": "UNLOCK_DOOR",
  "status": "success",
  "result": { "was_confirmed_by_device": false },
  "error": null
}
```

The unlock event appears in the ACS audit trail attributed to the specific user identity, not as a generic system action.

## Next Steps

* [Access Grants](/use-cases/granting-access/index) — Learn more about creating and managing Access Grants.
* [Access Methods API Reference](/api/access_methods/object) — See all access method properties and endpoints.


# Using Instant Keys
Source: https://docs.seam.co/use-cases/granting-access/using-instant-keys

Learn how to deliver Instant Keys — shareable unlock links that work without an app download — through Access Grants.

<img alt="Seam Instant Keys — no app, no account, just tap to unlock." />

Instant Keys are the fastest way to give someone mobile access. When you create an Access Grant with a `mobile_key` access method, Seam automatically generates an Instant Key URL. Share this URL with your user through text, email, or your app. When they tap the link, they can unlock the door immediately — no app download required.

Instant Keys use iOS App Clips and Android Instant Apps to provide a native unlock experience without requiring your user to install anything.

<img alt="Your user opens the App Clip from the link, views their key, and unlocks the door — no app download required." />

Instant Keys are ideal for:

* **Guest access** — Send a link to a short-term guest (hotel, vacation rental, coworking space).
* **Backup access** — Provide a fallback unlock method alongside a native mobile key in your app.
* **Quick onboarding** — Let users unlock immediately while they set up your full mobile app.
* **Offline environments** — Instant Keys use Bluetooth, so they keep working in areas with poor cellular or Wi-Fi coverage, like elevator banks or concrete-walled hallways.

## Example Use Cases

### Hotel Guests

Delight hotel guests with a smooth, modern check-in—no lines and no kiosks. Send keys directly to guests once their reservation is confirmed or check-in is completed.

* Compatible with major hotel access control systems.
* Works alongside plastic key cards.
* Great for both full-service hotels and contactless check-in setups.
* Keys can be sent automatically after check-in using text or email.
* Works across hotel room and common area doors.

### Self-Touring

Enable potential renters, buyers, and customers to access spaces without needing an on-site agent. With a tap, they can unlock the front door, tour the space, and leave when ready.

* Share secure access links for scheduled visits.
* Great for real estate, rentals, and coworking tours.

***

## Before You Begin

To use Instant Keys, you need:

* A [Seam API key](https://console.seam.co)
* A connected ACS with BLE-capable lock hardware that supports mobile keys
* Mobile key licenses activated for your ACS (see [Setting Up Your Site for Instant Keys](/use-cases/granting-access/instant-keys/setting-up-your-site-for-instant-keys))
* A [user identity](/capability-guides/mobile-access/managing-mobile-app-user-accounts-with-user-identities) representing the person who will receive the Instant Key
* An entrance that supports mobile keys (`can_unlock_with_mobile_key` is `true`)

<Info>
  Instant Keys are generated automatically when you create a mobile key access
  method. You do not need to request them separately.
</Info>

***

## Step 1: Create an Access Grant with a Mobile Key

Create an [Access Grant](/use-cases/granting-access/index) specifying `mobile_key` as the requested access method mode. The response includes an `instant_key_url` on the Access Grant itself — you can share it immediately without waiting for the access method to be issued.

<CodeGroup>
  ```javascript JavaScript theme={null}
  const accessGrant = await seam.accessGrants.create({
    user_identity_id: '22222222-2222-2222-2222-222222222222',
    acs_entrance_ids: ['f74e4879-5991-4e2f-a368-888983dcfbfc'],
    requested_access_methods: [{ mode: 'mobile_key' }],
    starts_at: '2025-07-13T15:00:00.000Z',
    ends_at: '2025-07-16T11:00:00.000Z',
  })

  console.log(accessGrant.instant_key_url)
  // => "https://ik.seam.co/ABCXYZ"
  ```

  ```python Python theme={null}
  access_grant = seam.access_grants.create(
      user_identity_id="22222222-2222-2222-2222-222222222222",
      acs_entrance_ids=["f74e4879-5991-4e2f-a368-888983dcfbfc"],
      requested_access_methods=[{"mode": "mobile_key"}],
      starts_at="2025-07-13T15:00:00.000Z",
      ends_at="2025-07-16T11:00:00.000Z",
  )

  print(access_grant.instant_key_url)
  # => "https://ik.seam.co/ABCXYZ"
  ```

  ```ruby Ruby theme={null}
  access_grant = seam.access_grants.create(
    user_identity_id: "22222222-2222-2222-2222-222222222222",
    acs_entrance_ids: ["f74e4879-5991-4e2f-a368-888983dcfbfc"],
    requested_access_methods: [{ mode: "mobile_key" }],
    starts_at: "2025-07-13T15:00:00.000Z",
    ends_at: "2025-07-16T11:00:00.000Z"
  )

  puts access_grant.instant_key_url
  # => "https://ik.seam.co/ABCXYZ"
  ```

  ```php PHP theme={null}
  $accessGrant = $seam->access_grants->create(
    user_identity_id: "22222222-2222-2222-2222-222222222222",
    acs_entrance_ids: ["f74e4879-5991-4e2f-a368-888983dcfbfc"],
    requested_access_methods: [["mode" => "mobile_key"]],
    starts_at: "2025-07-13T15:00:00.000Z",
    ends_at: "2025-07-16T11:00:00.000Z"
  );

  echo $accessGrant->instant_key_url;
  // => "https://ik.seam.co/ABCXYZ"
  ```

  ```csharp C# theme={null}
  var accessGrant = seam.AccessGrants.Create(
    userIdentityId: "22222222-2222-2222-2222-222222222222",
    acsEntranceIds: new List<string>
    {
      "f74e4879-5991-4e2f-a368-888983dcfbfc"
    },
    requestedAccessMethods: new List<RequestedAccessMethod>
    {
      new RequestedAccessMethod { Mode = "mobile_key" }
    },
    startsAt: "2025-07-13T15:00:00.000Z",
    endsAt: "2025-07-16T11:00:00.000Z"
  );

  Console.WriteLine(accessGrant.InstantKeyUrl);
  // => "https://ik.seam.co/ABCXYZ"
  ```

  ```java Java theme={null}
  var accessGrant = seam.accessGrants().create(
    AccessGrantsCreateRequest.builder()
      .userIdentityId("22222222-2222-2222-2222-222222222222")
      .acsEntranceIds(List.of(
        "f74e4879-5991-4e2f-a368-888983dcfbfc"
      ))
      .requestedAccessMethods(List.of(
        RequestedAccessMethod.builder()
          .mode("mobile_key")
          .build()
      ))
      .startsAt("2025-07-13T15:00:00.000Z")
      .endsAt("2025-07-16T11:00:00.000Z")
      .build()
  );
  ```

  ```bash cURL theme={null}
  curl -X 'POST' \
    'https://connect.getseam.com/access_grants/create' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d '{
    "user_identity_id": "22222222-2222-2222-2222-222222222222",
    "acs_entrance_ids": ["f74e4879-5991-4e2f-a368-888983dcfbfc"],
    "requested_access_methods": [{ "mode": "mobile_key" }],
    "starts_at": "2025-07-13T15:00:00.000Z",
    "ends_at": "2025-07-16T11:00:00.000Z"
  }'
  ```
</CodeGroup>

**Output:**

```json theme={null}
{
  "access_grant_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "user_identity_id": "22222222-2222-2222-2222-222222222222",
  "instant_key_url": "https://ik.seam.co/ABCXYZ",
  "requested_access_methods": [
    {
      "mode": "mobile_key",
      "created_access_method_ids": ["6ba7b810-9dad-11d1-80b4-00c04fd430c8"]
    }
  ],
  ...
}
```

***

## Step 2: Share the Instant Key URL

Once the access method is created, list the access methods for the Access Grant to get the `instant_key_url`.

Deliver the `instant_key_url` to your user. Common delivery methods include:

* **Text message (SMS)** — Send the URL directly to your user's phone. Works well if you already collect the guest's phone number at booking.
* **Email** — Include the URL in a welcome or check-in email.
* **In-app link** — Embed the URL in your web or mobile app.
* **QR code** — Generate a QR code from the URL for physical signage.

<img alt="Share an Instant Key with just a link — the App Clip opens right from the text message." />

When your user taps the link on their phone, the Instant Key opens as an iOS App Clip or Android Instant App. They can unlock the door immediately — no app store download needed.

If you have a guest-facing web app or booking portal, you can also embed the Instant Key directly in your interface—for example, in a reservation detail page or check-in flow with a **Mobile Key** or **Unlock Door** button.

<img alt="Embed the Instant Key link in a button in your own app for a native mobile key experience." />

<CodeGroup>
  ```javascript JavaScript theme={null}
  const accessMethods = await seam.accessMethods.list({
    access_grant_id: accessGrant.access_grant_id,
  })

  const instantKey = accessMethods[0]
  console.log(instantKey.instant_key_url)
  ```

  ```python Python theme={null}
  access_methods = seam.access_methods.list(
      access_grant_id=access_grant.access_grant_id
  )

  instant_key = access_methods[0]
  print(instant_key.instant_key_url)
  ```

  ```ruby Ruby theme={null}
  access_methods = seam.access_methods.list(
    access_grant_id: access_grant.access_grant_id
  )

  instant_key = access_methods[0]
  puts instant_key.instant_key_url
  ```

  ```php PHP theme={null}
  $accessMethods = $seam->access_methods->list(
    access_grant_id: $accessGrant->access_grant_id
  );

  $instantKey = $accessMethods[0];
  echo $instantKey->instant_key_url;
  ```

  ```csharp C# theme={null}
  var accessMethods = seam.AccessMethods.List(
    accessGrantId: accessGrant.AccessGrantId
  );

  var instantKey = accessMethods[0];
  Console.WriteLine(instantKey.InstantKeyUrl);
  ```

  ```java Java theme={null}
  var accessMethods = seam.accessMethods().list(
    AccessMethodsListRequest.builder()
      .accessGrantId(accessGrant.getAccessGrantId())
      .build()
  );
  ```

  ```bash cURL theme={null}
  curl -X 'POST' \
    'https://connect.getseam.com/access_methods/list' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d '{
    "access_grant_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }'
  ```
</CodeGroup>

**Output:**

```json theme={null}
{
  "access_method_id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
  "display_name": "Mobile Key",
  "mode": "mobile_key",
  "is_issued": true,
  "issued_at": "2025-06-16T16:55:03.924353Z",
  "instant_key_url": "https://ik.seam.co/ABCXYZ",
  ...
}
```

Use the `client_session_id` to look up the client session token, then pass it to the Seam mobile SDK to initialize your user's mobile app. For the complete mobile SDK integration guide, see [Mobile Access](/capability-guides/mobile-access/index).

***

## Step 3: See Which Doors an Access Method Covers

An access method can cover multiple doors — for example, if the Access Grant includes several entrances or spaces. To see which doors an Instant Key unlocks, call `/access_methods/get_related` with the underlying mobile key's access method ID.

<CodeGroup>
  ```javascript JavaScript theme={null}
  const related = await seam.accessMethods.getRelated({
    access_method_ids: [accessMethod.access_method_id],
  })

  console.log(related.acs_entrances) // ACS entrances this Instant Key unlocks
  ```

  ```python Python theme={null}
  related = seam.access_methods.get_related(
      access_method_ids=[access_method.access_method_id]
  )

  print(related.acs_entrances)  # ACS entrances this Instant Key unlocks
  ```

  ```ruby Ruby theme={null}
  related = seam.access_methods.get_related(
    access_method_ids: [access_method.access_method_id]
  )

  puts related.acs_entrances  # ACS entrances this Instant Key unlocks
  ```

  ```php PHP theme={null}
  $related = $seam->access_methods->get_related(
    access_method_ids: [$accessMethod->access_method_id]
  );

  echo json_encode($related->acs_entrances);  // ACS entrances this Instant Key unlocks
  ```

  ```csharp C# theme={null}
  var related = seam.AccessMethods.GetRelated(
    accessMethodIds: new List<string> { accessMethod.AccessMethodId }
  );

  // related.AcsEntrances — ACS entrances this Instant Key unlocks
  ```

  ```java Java theme={null}
  var related = seam.accessMethods().getRelated(
    AccessMethodsGetRelatedRequest.builder()
      .accessMethodIds(List.of(accessMethod.getAccessMethodId()))
      .build()
  );
  ```

  ```bash cURL theme={null}
  curl -X 'POST' \
    'https://connect.getseam.com/access_methods/get_related' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d '{
    "access_method_ids": ["f47ac10b-58cc-4372-a567-0e02b2c3d479"]
  }'
  ```
</CodeGroup>

***

## Next Steps

* [How Instant Keys Work](/use-cases/granting-access/instant-keys/how-instant-keys-work) — Learn how Instant Keys are tied to a user identity and how they resolve credentials.
* [Setting Up Your Site for Instant Keys](/use-cases/granting-access/instant-keys/setting-up-your-site-for-instant-keys) — BLE hardware requirements and access-system licensing.
* [Using Seam Console to Issue Instant Keys](/use-cases/granting-access/instant-keys/using-seam-console-to-issue-instant-keys) — Issue an Instant Key without writing code.
* [Using Mobile Keys](/use-cases/granting-access/using-mobile-keys) — Build a native mobile app experience with the Seam mobile SDKs.


# Using Key Cards
Source: https://docs.seam.co/use-cases/granting-access/using-key-cards

Learn how to create an Access Grant with a key card access method, then encode or assign the card to your user.

Key cards are plastic cards that unlock doors when presented to a card reader. When you request a `card` access method in an Access Grant, Seam creates a card credential. Depending on your access control system, you either encode the credential onto a physical card using a card encoder or the system assigns the credential to a pre-registered card automatically.

Key cards work with:

* **Access control systems** — Salto KS, Salto Space, ASSA ABLOY Visionline and Vostio, dormakaba, Brivo, and other ACS platforms that support card-based credentials. Specify entrances with `acs_entrance_ids` or use `space_ids`.

***

## Before You Begin

To use key cards, you need:

* A [Seam API key](https://console.seam.co)
* A connected ACS that supports card-based credentials
* A [user identity](/capability-guides/mobile-access/managing-mobile-app-user-accounts-with-user-identities) representing the person who will receive the card
* An entrance that supports card access (`can_unlock_with_card` is `true`)
* For encoding: a compatible card encoder connected to Seam (see [Working with Card Encoders and Scanners](/low-level-apis/access-systems/working-with-card-encoders-and-scanners/index))

***

## Step 1: Verify Entrance Support

List the entrances for your ACS and confirm that `can_unlock_with_card` is `true`.

<CodeGroup>
  ```javascript JavaScript theme={null}
  const entrances = await seam.acs.entrances.list({
    acs_system_id: 'c359cba2-8ef2-47fc-bee0-1c7c2a886339',
  })

  const cardEntrances = entrances.filter(
    (e) => e.can_unlock_with_card
  )
  ```

  ```python Python theme={null}
  entrances = seam.acs.entrances.list(
      acs_system_id="c359cba2-8ef2-47fc-bee0-1c7c2a886339"
  )

  card_entrances = [
      e for e in entrances if e.can_unlock_with_card
  ]
  ```

  ```ruby Ruby theme={null}
  entrances = seam.acs.entrances.list(
    acs_system_id: "c359cba2-8ef2-47fc-bee0-1c7c2a886339"
  )

  card_entrances = entrances.select do |e|
    e.can_unlock_with_card
  end
  ```

  ```php PHP theme={null}
  $entrances = $seam->acs->entrances->list(
    acs_system_id: "c359cba2-8ef2-47fc-bee0-1c7c2a886339"
  );

  $cardEntrances = array_filter(
    $entrances,
    fn($e) => $e->can_unlock_with_card
  );
  ```

  ```csharp C# theme={null}
  var entrances = seam.Acs.Entrances.List(
    acsSystemId: "c359cba2-8ef2-47fc-bee0-1c7c2a886339"
  );

  var cardEntrances = entrances
    .Where(e => e.CanUnlockWithCard)
    .ToList();
  ```

  ```java Java theme={null}
  var entrances = seam.acs().entrances().list(
    AcsEntrancesListRequest.builder()
      .acsSystemId("c359cba2-8ef2-47fc-bee0-1c7c2a886339")
      .build()
  );
  ```

  ```bash cURL theme={null}
  curl -X 'POST' \
    'https://connect.getseam.com/acs/entrances/list' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d '{
    "acs_system_id": "c359cba2-8ef2-47fc-bee0-1c7c2a886339"
  }'
  ```
</CodeGroup>

***

## Step 2: Create an Access Grant with a Key Card

Create an [Access Grant](/use-cases/granting-access/index) specifying `card` as the requested access method mode.

<CodeGroup>
  ```javascript JavaScript theme={null}
  const accessGrant = await seam.accessGrants.create({
    user_identity_id: '22222222-2222-2222-2222-222222222222',
    acs_entrance_ids: ['f74e4879-5991-4e2f-a368-888983dcfbfc'],
    requested_access_methods: [
      { mode: 'card' }
    ],
    starts_at: '2025-07-13T15:00:00.000Z',
    ends_at: '2025-07-16T11:00:00.000Z',
  })
  ```

  ```python Python theme={null}
  access_grant = seam.access_grants.create(
      user_identity_id="22222222-2222-2222-2222-222222222222",
      acs_entrance_ids=["f74e4879-5991-4e2f-a368-888983dcfbfc"],
      requested_access_methods=[{"mode": "card"}],
      starts_at="2025-07-13T15:00:00.000Z",
      ends_at="2025-07-16T11:00:00.000Z",
  )
  ```

  ```ruby Ruby theme={null}
  access_grant = seam.access_grants.create(
    user_identity_id: "22222222-2222-2222-2222-222222222222",
    acs_entrance_ids: ["f74e4879-5991-4e2f-a368-888983dcfbfc"],
    requested_access_methods: [{ mode: "card" }],
    starts_at: "2025-07-13T15:00:00.000Z",
    ends_at: "2025-07-16T11:00:00.000Z"
  )
  ```

  ```php PHP theme={null}
  $accessGrant = $seam->access_grants->create(
    user_identity_id: "22222222-2222-2222-2222-222222222222",
    acs_entrance_ids: ["f74e4879-5991-4e2f-a368-888983dcfbfc"],
    requested_access_methods: [["mode" => "card"]],
    starts_at: "2025-07-13T15:00:00.000Z",
    ends_at: "2025-07-16T11:00:00.000Z"
  );
  ```

  ```csharp C# theme={null}
  var accessGrant = seam.AccessGrants.Create(
    userIdentityId: "22222222-2222-2222-2222-222222222222",
    acsEntranceIds: new List<string>
    {
      "f74e4879-5991-4e2f-a368-888983dcfbfc"
    },
    requestedAccessMethods: new List<RequestedAccessMethod>
    {
      new RequestedAccessMethod { Mode = "card" }
    },
    startsAt: "2025-07-13T15:00:00.000Z",
    endsAt: "2025-07-16T11:00:00.000Z"
  );
  ```

  ```java Java theme={null}
  var accessGrant = seam.accessGrants().create(
    AccessGrantsCreateRequest.builder()
      .userIdentityId("22222222-2222-2222-2222-222222222222")
      .acsEntranceIds(List.of(
        "f74e4879-5991-4e2f-a368-888983dcfbfc"
      ))
      .requestedAccessMethods(List.of(
        RequestedAccessMethod.builder()
          .mode("card")
          .build()
      ))
      .startsAt("2025-07-13T15:00:00.000Z")
      .endsAt("2025-07-16T11:00:00.000Z")
      .build()
  );
  ```

  ```bash cURL theme={null}
  curl -X 'POST' \
    'https://connect.getseam.com/access_grants/create' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d '{
    "user_identity_id": "22222222-2222-2222-2222-222222222222",
    "acs_entrance_ids": ["f74e4879-5991-4e2f-a368-888983dcfbfc"],
    "requested_access_methods": [{ "mode": "card" }],
    "starts_at": "2025-07-13T15:00:00.000Z",
    "ends_at": "2025-07-16T11:00:00.000Z"
  }'
  ```
</CodeGroup>

***

## Step 3: Deliver the Key Card

List the access methods for the Access Grant and check the `is_encoding_required` property to determine whether you need to encode the card or whether the system assigns it automatically.

<CodeGroup>
  ```javascript JavaScript theme={null}
  const accessMethods = await seam.accessMethods.list({
    access_grant_id: accessGrant.access_grant_id,
  })

  const card = accessMethods[0]
  console.log(card.is_encoding_required)
  ```

  ```python Python theme={null}
  access_methods = seam.access_methods.list(
      access_grant_id=access_grant.access_grant_id
  )

  card = access_methods[0]
  print(card.is_encoding_required)
  ```

  ```ruby Ruby theme={null}
  access_methods = seam.access_methods.list(
    access_grant_id: access_grant.access_grant_id
  )

  card = access_methods[0]
  puts card.is_encoding_required
  ```

  ```php PHP theme={null}
  $accessMethods = $seam->access_methods->list(
    access_grant_id: $accessGrant->access_grant_id
  );

  $card = $accessMethods[0];
  echo $card->is_encoding_required;
  ```

  ```csharp C# theme={null}
  var accessMethods = seam.AccessMethods.List(
    accessGrantId: accessGrant.AccessGrantId
  );

  var card = accessMethods[0];
  Console.WriteLine(card.IsEncodingRequired);
  ```

  ```java Java theme={null}
  var accessMethods = seam.accessMethods().list(
    AccessMethodsListRequest.builder()
      .accessGrantId(accessGrant.getAccessGrantId())
      .build()
  );
  ```

  ```bash cURL theme={null}
  curl -X 'POST' \
    'https://connect.getseam.com/access_methods/list' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d '{
    "access_grant_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }'
  ```
</CodeGroup>

**Output:**

```json theme={null}
{
  "access_method_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "display_name": "Key Card",
  "mode": "card",
  "is_issued": false,
  "is_encoding_required": true,
  ...
}
```

***

### Encoding Cards

If `is_encoding_required` is `true`, you must encode the credential onto a physical card using a card encoder before handing the card to your user.

Use the Seam API to encode the card:

<CodeGroup>
  ```javascript JavaScript theme={null}
  const actionAttempt = await seam.accessMethods.encode({
    access_method_id: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
    acs_encoder_id: 'encoder-001',
  })
  ```

  ```python Python theme={null}
  action_attempt = seam.access_methods.encode(
      access_method_id="a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      acs_encoder_id="encoder-001",
  )
  ```

  ```ruby Ruby theme={null}
  action_attempt = seam.access_methods.encode(
    access_method_id: "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    acs_encoder_id: "encoder-001"
  )
  ```

  ```php PHP theme={null}
  $actionAttempt = $seam->access_methods->encode(
    access_method_id: "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    acs_encoder_id: "encoder-001"
  );
  ```

  ```csharp C# theme={null}
  var actionAttempt = seam.AccessMethods.Encode(
    accessMethodId: "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    acsEncoderId: "encoder-001"
  );
  ```

  ```java Java theme={null}
  var actionAttempt = seam.accessMethods().encode(
    AccessMethodsEncodeRequest.builder()
      .accessMethodId("a1b2c3d4-e5f6-7890-abcd-ef1234567890")
      .acsEncoderId("encoder-001")
      .build()
  );
  ```

  ```bash cURL theme={null}
  curl -X 'POST' \
    'https://connect.getseam.com/access_methods/encode' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d '{
    "access_method_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "acs_encoder_id": "encoder-001"
  }'
  ```
</CodeGroup>

Once encoding is complete, the access method's `is_encoding_required` property changes to `false` and `is_issued` changes to `true`. Hand the encoded card to your user.

For the complete card encoding workflow, including listing encoders and scanning cards, see [Working with Card Encoders and Scanners](/low-level-apis/access-systems/working-with-card-encoders-and-scanners/index).

***

### Assigning Cards

If `is_assigning_required` is `true`, you can assign an existing credential to the access method by providing the card number. This is common with systems that use pre-registered cards.

Use the Seam API to input the `card_number` for the access method:

<CodeGroup>
  ```javascript JavaScript theme={null}
  const actionAttempt = await seam.accessMethods.assignCard({
    access_method_id: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
    card_number: 'ABCD1234',
  })
  ```

  ```python Python theme={null}
  action_attempt = seam.access_methods.assign_card(
      access_method_id="a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      card_number="ABCD1234",
  )
  ```

  ```ruby Ruby theme={null}
  action_attempt = seam.access_methods.assign_card(
    access_method_id: "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    card_number: "ABCD1234"
  )
  ```

  ```php PHP theme={null}
  $actionAttempt = $seam->access_methods->assign_card(
    access_method_id: "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    card_number: "ABCD1234"
  );
  ```

  ```csharp C# theme={null}
  var actionAttempt = seam.AccessMethods.AssignCard(
    accessMethodId: "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    cardNumber: "ABCD1234"
  );
  ```

  ```java Java theme={null}
  var actionAttempt = seam.accessMethods().assignCard(
    AccessMethodsAssignCardRequest.builder()
      .accessMethodId("a1b2c3d4-e5f6-7890-abcd-ef1234567890")
      .cardNumber("ABCD1234")
      .build()
  );
  ```

  ```bash cURL theme={null}
  curl -X 'POST' \
    'https://connect.getseam.com/access_methods/assign_card' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d '{
    "access_method_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "card_number": "ABCD1234"
  }'
  ```
</CodeGroup>

Once a card is assigned, the access method's `is_assignment_required` property changes to `false` and `is_issued` changes to `true`. Hand the assigned card to your user.

***

## Step 4: See Which Doors the Key Card Covers

An access method can cover multiple doors — for example, if the Access Grant includes several entrances or spaces. To see which doors a key card unlocks, call `/access_methods/get_related`.

<CodeGroup>
  ```javascript JavaScript theme={null}
  const related = await seam.accessMethods.getRelated({
    access_method_ids: [accessMethod.access_method_id],
  })

  console.log(related.acs_entrances) // entrances this card unlocks
  ```

  ```python Python theme={null}
  related = seam.access_methods.get_related(
      access_method_ids=[access_method.access_method_id]
  )

  print(related.acs_entrances)  # entrances this card unlocks
  ```

  ```ruby Ruby theme={null}
  related = seam.access_methods.get_related(
    access_method_ids: [access_method.access_method_id]
  )

  puts related.acs_entrances  # entrances this card unlocks
  ```

  ```php PHP theme={null}
  $related = $seam->access_methods->get_related(
    access_method_ids: [$accessMethod->access_method_id]
  );

  echo json_encode($related->acs_entrances);  // entrances this card unlocks
  ```

  ```csharp C# theme={null}
  var related = seam.AccessMethods.GetRelated(
    accessMethodIds: new List<string> { accessMethod.AccessMethodId }
  );

  // related.AcsEntrances — entrances this card unlocks
  ```

  ```java Java theme={null}
  var related = seam.accessMethods().getRelated(
    AccessMethodsGetRelatedRequest.builder()
      .accessMethodIds(List.of(accessMethod.getAccessMethodId()))
      .build()
  );
  ```

  ```bash cURL theme={null}
  curl -X 'POST' \
    'https://connect.getseam.com/access_methods/get_related' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d '{
    "access_method_ids": ["f47ac10b-58cc-4372-a567-0e02b2c3d479"]
  }'
  ```
</CodeGroup>

***

## Next Steps

* [Working with Card Encoders and Scanners](/low-level-apis/access-systems/working-with-card-encoders-and-scanners/index) — Complete guide to encoding and scanning cards.
* [Creating an Access Grant](/use-cases/granting-access/creating-an-access-grant) — Learn more about specifying devices, entrances, and spaces.
* [Access Methods API Reference](/api/access_methods/object) — See all access method properties and endpoints.


# Using Mobile Keys
Source: https://docs.seam.co/use-cases/granting-access/using-mobile-keys

Learn how to create an Access Grant with a mobile key access method and deliver it through your mobile app using the Seam mobile SDKs.

Mobile keys let your users unlock doors by tapping a button in your mobile app. When you request a `mobile_key` access method in an Access Grant, Seam issues a mobile credential that you deliver through your own app using the Seam mobile SDKs. Each mobile key also includes an [Instant Key](/use-cases/granting-access/using-instant-keys) URL for immediate access without an app download.

Mobile keys work with:

* **Access control systems** — Salto KS, Salto Space, ASSA ABLOY Visionline and Vostio, dormakaba, Brivo, and other ACS platforms that support BLE-based mobile credentials. Specify entrances with `acs_entrance_ids` or use `space_ids`.

***

## Before You Begin

To use mobile keys, you need:

* A [Seam API key](https://console.seam.co)
* A connected ACS with BLE-capable lock hardware
* Mobile key licenses or subscriptions activated for your ACS (requirements vary by system — see your [system integration guide](/device-and-system-integration-guides#access-control-systems))
* A [user identity](/capability-guides/mobile-access/managing-mobile-app-user-accounts-with-user-identities) representing the person who will receive the mobile key
* An entrance that supports mobile keys (`can_unlock_with_mobile_key` is `true`)

<Info>
  If you plan to build a mobile app that delivers mobile keys, see [Mobile Access](/capability-guides/mobile-access/index) for the complete SDK integration guide. If you just want to share a link for instant access, see [Using Instant Keys](/use-cases/granting-access/using-instant-keys) instead.
</Info>

***

## Step 1: Verify Entrance Support

List the entrances for your ACS and confirm that `can_unlock_with_mobile_key` is `true`.

<CodeGroup>
  ```javascript JavaScript theme={null}
  const entrances = await seam.acs.entrances.list({
    acs_system_id: 'c359cba2-8ef2-47fc-bee0-1c7c2a886339',
  })

  const mobileKeyEntrances = entrances.filter(
    (e) => e.can_unlock_with_mobile_key
  )
  ```

  ```python Python theme={null}
  entrances = seam.acs.entrances.list(
      acs_system_id="c359cba2-8ef2-47fc-bee0-1c7c2a886339"
  )

  mobile_key_entrances = [
      e for e in entrances if e.can_unlock_with_mobile_key
  ]
  ```

  ```ruby Ruby theme={null}
  entrances = seam.acs.entrances.list(
    acs_system_id: "c359cba2-8ef2-47fc-bee0-1c7c2a886339"
  )

  mobile_key_entrances = entrances.select do |e|
    e.can_unlock_with_mobile_key
  end
  ```

  ```php PHP theme={null}
  $entrances = $seam->acs->entrances->list(
    acs_system_id: "c359cba2-8ef2-47fc-bee0-1c7c2a886339"
  );

  $mobileKeyEntrances = array_filter(
    $entrances,
    fn($e) => $e->can_unlock_with_mobile_key
  );
  ```

  ```csharp C# theme={null}
  var entrances = seam.Acs.Entrances.List(
    acsSystemId: "c359cba2-8ef2-47fc-bee0-1c7c2a886339"
  );

  var mobileKeyEntrances = entrances
    .Where(e => e.CanUnlockWithMobileKey)
    .ToList();
  ```

  ```java Java theme={null}
  var entrances = seam.acs().entrances().list(
    AcsEntrancesListRequest.builder()
      .acsSystemId("c359cba2-8ef2-47fc-bee0-1c7c2a886339")
      .build()
  );
  ```

  ```bash cURL theme={null}
  curl -X 'POST' \
    'https://connect.getseam.com/acs/entrances/list' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d '{
    "acs_system_id": "c359cba2-8ef2-47fc-bee0-1c7c2a886339"
  }'
  ```
</CodeGroup>

***

## Step 2: Create an Access Grant with a Mobile Key

Create an [Access Grant](/use-cases/granting-access/index) specifying `mobile_key` as the requested access method mode.

<CodeGroup>
  ```javascript JavaScript theme={null}
  const accessGrant = await seam.accessGrants.create({
    user_identity_id: '22222222-2222-2222-2222-222222222222',
    acs_entrance_ids: ['f74e4879-5991-4e2f-a368-888983dcfbfc'],
    requested_access_methods: [
      { mode: 'mobile_key' }
    ],
    starts_at: '2025-07-13T15:00:00.000Z',
    ends_at: '2025-07-16T11:00:00.000Z',
  })
  ```

  ```python Python theme={null}
  access_grant = seam.access_grants.create(
      user_identity_id="22222222-2222-2222-2222-222222222222",
      acs_entrance_ids=["f74e4879-5991-4e2f-a368-888983dcfbfc"],
      requested_access_methods=[{"mode": "mobile_key"}],
      starts_at="2025-07-13T15:00:00.000Z",
      ends_at="2025-07-16T11:00:00.000Z",
  )
  ```

  ```ruby Ruby theme={null}
  access_grant = seam.access_grants.create(
    user_identity_id: "22222222-2222-2222-2222-222222222222",
    acs_entrance_ids: ["f74e4879-5991-4e2f-a368-888983dcfbfc"],
    requested_access_methods: [{ mode: "mobile_key" }],
    starts_at: "2025-07-13T15:00:00.000Z",
    ends_at: "2025-07-16T11:00:00.000Z"
  )
  ```

  ```php PHP theme={null}
  $accessGrant = $seam->access_grants->create(
    user_identity_id: "22222222-2222-2222-2222-222222222222",
    acs_entrance_ids: ["f74e4879-5991-4e2f-a368-888983dcfbfc"],
    requested_access_methods: [["mode" => "mobile_key"]],
    starts_at: "2025-07-13T15:00:00.000Z",
    ends_at: "2025-07-16T11:00:00.000Z"
  );
  ```

  ```csharp C# theme={null}
  var accessGrant = seam.AccessGrants.Create(
    userIdentityId: "22222222-2222-2222-2222-222222222222",
    acsEntranceIds: new List<string>
    {
      "f74e4879-5991-4e2f-a368-888983dcfbfc"
    },
    requestedAccessMethods: new List<RequestedAccessMethod>
    {
      new RequestedAccessMethod { Mode = "mobile_key" }
    },
    startsAt: "2025-07-13T15:00:00.000Z",
    endsAt: "2025-07-16T11:00:00.000Z"
  );
  ```

  ```java Java theme={null}
  var accessGrant = seam.accessGrants().create(
    AccessGrantsCreateRequest.builder()
      .userIdentityId("22222222-2222-2222-2222-222222222222")
      .acsEntranceIds(List.of(
        "f74e4879-5991-4e2f-a368-888983dcfbfc"
      ))
      .requestedAccessMethods(List.of(
        RequestedAccessMethod.builder()
          .mode("mobile_key")
          .build()
      ))
      .startsAt("2025-07-13T15:00:00.000Z")
      .endsAt("2025-07-16T11:00:00.000Z")
      .build()
  );
  ```

  ```bash cURL theme={null}
  curl -X 'POST' \
    'https://connect.getseam.com/access_grants/create' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d '{
    "user_identity_id": "22222222-2222-2222-2222-222222222222",
    "acs_entrance_ids": ["f74e4879-5991-4e2f-a368-888983dcfbfc"],
    "requested_access_methods": [{ "mode": "mobile_key" }],
    "starts_at": "2025-07-13T15:00:00.000Z",
    "ends_at": "2025-07-16T11:00:00.000Z"
  }'
  ```
</CodeGroup>

***

## Step 3: Deliver the Mobile Key

Once the access method is issued, list the access methods for the Access Grant to get the `client_session_id`. Use this value to initialize the Seam mobile SDK on your user's device so they can unlock doors from your app.

<CodeGroup>
  ```javascript JavaScript theme={null}
  const accessMethods = await seam.accessMethods.list({
    access_grant_id: accessGrant.access_grant_id,
  })

  const mobileKey = accessMethods[0]
  console.log(mobileKey.client_session_id)
  console.log(mobileKey.instant_key_url)
  ```

  ```python Python theme={null}
  access_methods = seam.access_methods.list(
      access_grant_id=access_grant.access_grant_id
  )

  mobile_key = access_methods[0]
  print(mobile_key.client_session_id)
  print(mobile_key.instant_key_url)
  ```

  ```ruby Ruby theme={null}
  access_methods = seam.access_methods.list(
    access_grant_id: access_grant.access_grant_id
  )

  mobile_key = access_methods[0]
  puts mobile_key.client_session_id
  puts mobile_key.instant_key_url
  ```

  ```php PHP theme={null}
  $accessMethods = $seam->access_methods->list(
    access_grant_id: $accessGrant->access_grant_id
  );

  $mobileKey = $accessMethods[0];
  echo $mobileKey->client_session_id;
  echo $mobileKey->instant_key_url;
  ```

  ```csharp C# theme={null}
  var accessMethods = seam.AccessMethods.List(
    accessGrantId: accessGrant.AccessGrantId
  );

  var mobileKey = accessMethods[0];
  Console.WriteLine(mobileKey.ClientSessionId);
  Console.WriteLine(mobileKey.InstantKeyUrl);
  ```

  ```java Java theme={null}
  var accessMethods = seam.accessMethods().list(
    AccessMethodsListRequest.builder()
      .accessGrantId(accessGrant.getAccessGrantId())
      .build()
  );
  ```

  ```bash cURL theme={null}
  curl -X 'POST' \
    'https://connect.getseam.com/access_methods/list' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d '{
    "access_grant_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }'
  ```
</CodeGroup>

**Output:**

```json theme={null}
{
  "access_method_id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
  "display_name": "Mobile Key",
  "mode": "mobile_key",
  "is_issued": true,
  "issued_at": "2025-06-16T16:55:03.924353Z",
  "client_session_id": "3f2504e0-4f89-11d3-9a0c-0305e82c3301",
  "instant_key_url": "https://ik.seam.co/ABCXYZ",
  ...
}
```

Use the `client_session_id` to look up the client session token, then pass it to the Seam mobile SDK to initialize your user's mobile app. For the complete mobile SDK integration guide, see [Mobile Access](/capability-guides/mobile-access/index).

<Info>
  Every mobile key also includes an `instant_key_url`. You can share this URL with your user as an alternative or backup access method — no app download required. See [Using Instant Keys](/use-cases/granting-access/using-instant-keys).
</Info>

***

## Step 4: See Which Doors the Mobile Key Covers

An access method can cover multiple doors — for example, if the Access Grant includes several entrances or spaces. To see which doors a mobile key unlocks, call `/access_methods/get_related`.

<CodeGroup>
  ```javascript JavaScript theme={null}
  const related = await seam.accessMethods.getRelated({
    access_method_ids: [accessMethod.access_method_id],
  })

  console.log(related.acs_entrances) // ACS entrances this mobile key unlocks
  ```

  ```python Python theme={null}
  related = seam.access_methods.get_related(
      access_method_ids=[access_method.access_method_id]
  )

  print(related.acs_entrances)  # ACS entrances this mobile key unlocks
  ```

  ```ruby Ruby theme={null}
  related = seam.access_methods.get_related(
    access_method_ids: [access_method.access_method_id]
  )

  puts related.acs_entrances  # ACS entrances this mobile key unlocks
  ```

  ```php PHP theme={null}
  $related = $seam->access_methods->get_related(
    access_method_ids: [$accessMethod->access_method_id]
  );

  echo json_encode($related->acs_entrances);  // ACS entrances this mobile key unlocks
  ```

  ```csharp C# theme={null}
  var related = seam.AccessMethods.GetRelated(
    accessMethodIds: new List<string> { accessMethod.AccessMethodId }
  );

  // related.AcsEntrances — ACS entrances this mobile key unlocks
  ```

  ```java Java theme={null}
  var related = seam.accessMethods().getRelated(
    AccessMethodsGetRelatedRequest.builder()
      .accessMethodIds(List.of(accessMethod.getAccessMethodId()))
      .build()
  );
  ```

  ```bash cURL theme={null}
  curl -X 'POST' \
    'https://connect.getseam.com/access_methods/get_related' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d '{
    "access_method_ids": ["f47ac10b-58cc-4372-a567-0e02b2c3d479"]
  }'
  ```
</CodeGroup>

***

## Next Steps

* [Mobile Access](/capability-guides/mobile-access/index) — Complete guide to building a mobile app with the Seam mobile SDKs.
* [Using Instant Keys](/use-cases/granting-access/using-instant-keys) — Share the Instant Key URL included with every mobile key.
* [Access Methods API Reference](/api/access_methods/object) — See all access method properties and endpoints.


# Using PIN Codes
Source: https://docs.seam.co/use-cases/granting-access/using-pin-codes

Learn how to create an Access Grant with a PIN code access method and deliver the code to your user.

PIN codes are the simplest access method. When you request a `code` access method in an Access Grant, Seam programs a PIN code onto the lock. Your user enters the code on the lock's keypad to unlock the door.

PIN codes work with:

* **Standalone smart locks** — August, Yale, Schlage, Lockly, TTLock, Tedee, igloohome, and other connected locks. Specify the locks with `device_ids`.
* **Access control systems** — Salto KS, Salto Space, Brivo, dormakaba, and other ACS platforms that support PIN-based credentials. Specify entrances with `acs_entrance_ids` or group access points into spaces and use `space_ids`.

***

## Before You Begin

To use PIN codes, you need:

* A [Seam API key](https://console.seam.co)
* One or more connected devices or ACS entrances that support PIN codes
* For standalone smart locks: confirm that `can_program_online_access_codes` is `true` on the device
* For ACS entrances: confirm that `can_unlock_with_code` is `true` on the entrance

***

## Step 1: Verify Device or Entrance Support

### Standalone Smart Locks

List your devices and confirm that `can_program_online_access_codes` is `true`.

<CodeGroup>
  ```javascript JavaScript theme={null}
  const devices = await seam.devices.list()

  const pinCapableDevices = devices.filter(
    (d) => d.can_program_online_access_codes
  )
  ```

  ```python Python theme={null}
  devices = seam.devices.list()

  pin_capable_devices = [
      d for d in devices if d.can_program_online_access_codes
  ]
  ```

  ```ruby Ruby theme={null}
  devices = seam.devices.list

  pin_capable_devices = devices.select do |d|
    d.can_program_online_access_codes
  end
  ```

  ```php PHP theme={null}
  $devices = $seam->devices->list();

  $pinCapableDevices = array_filter(
    $devices,
    fn($d) => $d->can_program_online_access_codes
  );
  ```

  ```csharp C# theme={null}
  var devices = seam.Devices.List();

  var pinCapableDevices = devices
    .Where(d => d.CanProgramOnlineAccessCodes)
    .ToList();
  ```

  ```java Java theme={null}
  var devices = seam.devices().list(
    DevicesListRequest.builder().build()
  );
  ```

  ```bash cURL theme={null}
  curl -X 'POST' \
    'https://connect.getseam.com/devices/list' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d '{}'
  ```
</CodeGroup>

### ACS Entrances

List the entrances for your ACS and confirm that `can_unlock_with_code` is `true`.

<CodeGroup>
  ```javascript JavaScript theme={null}
  const entrances = await seam.acs.entrances.list({
    acs_system_id: 'c359cba2-8ef2-47fc-bee0-1c7c2a886339',
  })

  const codeEntrances = entrances.filter(
    (e) => e.can_unlock_with_code
  )
  ```

  ```python Python theme={null}
  entrances = seam.acs.entrances.list(
      acs_system_id="c359cba2-8ef2-47fc-bee0-1c7c2a886339"
  )

  code_entrances = [
      e for e in entrances if e.can_unlock_with_code
  ]
  ```

  ```ruby Ruby theme={null}
  entrances = seam.acs.entrances.list(
    acs_system_id: "c359cba2-8ef2-47fc-bee0-1c7c2a886339"
  )

  code_entrances = entrances.select do |e|
    e.can_unlock_with_code
  end
  ```

  ```php PHP theme={null}
  $entrances = $seam->acs->entrances->list(
    acs_system_id: "c359cba2-8ef2-47fc-bee0-1c7c2a886339"
  );

  $codeEntrances = array_filter(
    $entrances,
    fn($e) => $e->can_unlock_with_code
  );
  ```

  ```csharp C# theme={null}
  var entrances = seam.Acs.Entrances.List(
    acsSystemId: "c359cba2-8ef2-47fc-bee0-1c7c2a886339"
  );

  var codeEntrances = entrances
    .Where(e => e.CanUnlockWithCode)
    .ToList();
  ```

  ```java Java theme={null}
  var entrances = seam.acs().entrances().list(
    AcsEntrancesListRequest.builder()
      .acsSystemId("c359cba2-8ef2-47fc-bee0-1c7c2a886339")
      .build()
  );
  ```

  ```bash cURL theme={null}
  curl -X 'POST' \
    'https://connect.getseam.com/acs/entrances/list' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d '{
    "acs_system_id": "c359cba2-8ef2-47fc-bee0-1c7c2a886339"
  }'
  ```
</CodeGroup>

***

## Step 2: Create an Access Grant with a PIN Code

Create an [Access Grant](/use-cases/granting-access/index) specifying `code` as the requested access method mode. You can target devices, entrances, or spaces.

<Info>
  On a standalone lock, some devices only accept certain access schedules — for example, a minimum or maximum duration, or fixed check-in and check-out times. Before setting `starts_at` and `ends_at`, review the device's time frame options so that your schedule is valid. See [Understanding Time Frame Options](/low-level-apis/smart-locks/access-codes/creating-access-codes/understanding-time-frame-options).
</Info>

<CodeGroup>
  ```javascript JavaScript theme={null}
  const accessGrant = await seam.accessGrants.create({
    user_identity_id: '22222222-2222-2222-2222-222222222222',
    device_ids: ['6ba7b811-9dad-11d1-80b4-00c04fd430c8'],
    requested_access_methods: [
      { mode: 'code' }
    ],
    starts_at: '2025-07-13T15:00:00.000Z',
    ends_at: '2025-07-16T11:00:00.000Z',
  })
  ```

  ```python Python theme={null}
  access_grant = seam.access_grants.create(
      user_identity_id="22222222-2222-2222-2222-222222222222",
      device_ids=["6ba7b811-9dad-11d1-80b4-00c04fd430c8"],
      requested_access_methods=[{"mode": "code"}],
      starts_at="2025-07-13T15:00:00.000Z",
      ends_at="2025-07-16T11:00:00.000Z",
  )
  ```

  ```ruby Ruby theme={null}
  access_grant = seam.access_grants.create(
    user_identity_id: "22222222-2222-2222-2222-222222222222",
    device_ids: ["6ba7b811-9dad-11d1-80b4-00c04fd430c8"],
    requested_access_methods: [{ mode: "code" }],
    starts_at: "2025-07-13T15:00:00.000Z",
    ends_at: "2025-07-16T11:00:00.000Z"
  )
  ```

  ```php PHP theme={null}
  $accessGrant = $seam->access_grants->create(
    user_identity_id: "22222222-2222-2222-2222-222222222222",
    device_ids: ["6ba7b811-9dad-11d1-80b4-00c04fd430c8"],
    requested_access_methods: [["mode" => "code"]],
    starts_at: "2025-07-13T15:00:00.000Z",
    ends_at: "2025-07-16T11:00:00.000Z"
  );
  ```

  ```csharp C# theme={null}
  var accessGrant = seam.AccessGrants.Create(
    userIdentityId: "22222222-2222-2222-2222-222222222222",
    deviceIds: new List<string>
    {
      "6ba7b811-9dad-11d1-80b4-00c04fd430c8"
    },
    requestedAccessMethods: new List<RequestedAccessMethod>
    {
      new RequestedAccessMethod { Mode = "code" }
    },
    startsAt: "2025-07-13T15:00:00.000Z",
    endsAt: "2025-07-16T11:00:00.000Z"
  );
  ```

  ```java Java theme={null}
  var accessGrant = seam.accessGrants().create(
    AccessGrantsCreateRequest.builder()
      .userIdentityId("22222222-2222-2222-2222-222222222222")
      .deviceIds(List.of(
        "6ba7b811-9dad-11d1-80b4-00c04fd430c8"
      ))
      .requestedAccessMethods(List.of(
        RequestedAccessMethod.builder()
          .mode("code")
          .build()
      ))
      .startsAt("2025-07-13T15:00:00.000Z")
      .endsAt("2025-07-16T11:00:00.000Z")
      .build()
  );
  ```

  ```bash cURL theme={null}
  curl -X 'POST' \
    'https://connect.getseam.com/access_grants/create' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d '{
    "user_identity_id": "22222222-2222-2222-2222-222222222222",
    "device_ids": ["6ba7b811-9dad-11d1-80b4-00c04fd430c8"],
    "requested_access_methods": [{ "mode": "code" }],
    "starts_at": "2025-07-13T15:00:00.000Z",
    "ends_at": "2025-07-16T11:00:00.000Z"
  }'
  ```
</CodeGroup>

<Info>
  In a sandbox workspace, PIN codes are issued almost instantly. On real devices, issuance can take a few moments. Poll the access method until `is_issued` is `true` or watch for the `access_method.issued` event.
</Info>

***

## Step 3: Retrieve the PIN Code

Once the access method is issued, list the access methods for the Access Granlist the access methods for the Access Grant to get the code. Share the code with your user through text, email, or your application.

<CodeGroup>
  ```javascript JavaScript theme={null}
  const accessMethods = await seam.accessMethods.list({
    access_grant_id: accessGrant.access_grant_id,
  })

  const pinCode = accessMethods[0]
  console.log(pinCodes = await seam.accessMethods.list({
    access_grant_id: accessGrant.access_grant_id,
  })

  const pinCode = accessMethods[0]
  console.log(pinCode.code) // => "1234"
  ```

  ```python Python theme={null}
  access_methods = seam.access_methods.list(
      access_grant_id=access_grant.access_grant_id
  )

  pin_code = access_methods[0]
  print(pin_codes = seam.access_methods.list(
      access_grant_id=access_grant.access_grant_id
  )

  pin_code = access_methods[0]
  print(pin_code.code)  # => "1234"
  ```

  ```ruby Ruby theme={null}
  access_methods = seam.access_methods.list(
    access_grant_id: access_grant.access_grant_id
  )

  pin_code = access_methods[0]
  puts pin_codes = seam.access_methods.list(
    access_grant_id: access_grant.access_grant_id
  )

  pin_code = access_methods[0]
  puts pin_code.code  # => "1234"
  ```

  ```php PHP theme={null}
  $accessMethods = $seam->access_methods->list(
    access_grant_id: $accessGrant->access_grant_id
  );

  $pinCode = $accessMethods[0];
  echo $pinCodes = $seam->access_methods->list(
    access_grant_id: $accessGrant->access_grant_id
  );

  $pinCode = $accessMethods[0];
  echo $pinCode->code;  // => "1234"
  ```

  ```csharp C# theme={null}
  var accessMethods = seam.AccessMethods.List(
    accessGrantId: accessGrant.AccessGrantId
  );

  var pinCode = accessMethods[0];
  Console.WriteLine(pinCodes = seam.AccessMethods.List(
    accessGrantId: accessGrant.AccessGrantId
  );

  var pinCode = accessMethods[0];
  Console.WriteLine(pinCode.Code);  // => "1234"
  ```

  ```java Java theme={null}
  var accessMethods = seam.accessMethods().list(
    AccessMethodsListRequest.builder()
      .accessGrantId(accessGrant.getAccessGrantId()s = seam.accessMethods().list(
    AccessMethodsListRequest.builder()
      .accessGrantId(accessGrant.getAccessGrantId())
      .build()
  );
  ```

  ```bash cURL theme={null}
  curl -X 'POST' \
    'https://connect.getseam.com/access_methods/list' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d '{
    "access_grant_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890list' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d '{
    "access_grant_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }'
  ```
</CodeGroup>

**Output:**

```json theme={null}
{
  "access_method_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "display_name": "PIN Code",
  "mode": "code",
  "is_issued": true,
  "issued_at": "2025-06-16T16:55:03.924353Z",
  "code": "1234",
  ...
}
```

***

## Step 4: See Which Doors an Access Method Covers

An access method can cover multiple doors — for example, if the Access Grant includes several devices or entrances. To see which doors a PIN code is programmed on, call `/access_methods/get_related`.

<CodeGroup>
  ```javascript JavaScript theme={null}
  const related = await seam.accessMethods.getRelated({
    access_method_ids: [accessMethod.access_method_id],
  })

  console.log(related.devices) // devices this PIN code is programmed on
  console.log(related.acs_entrances) // ACS entrances this PIN code unlocks
  ```

  ```python Python theme={null}
  related = seam.access_methods.get_related(
      access_method_ids=[access_method.access_method_id]
  )

  print(related.devices)        # devices this PIN code is programmed on
  print(related.acs_entrances)  # ACS entrances this PIN code unlocks
  ```

  ```ruby Ruby theme={null}
  related = seam.access_methods.get_related(
    access_method_ids: [access_method.access_method_id]
  )

  puts related.devices        # devices this PIN code is programmed on
  puts related.acs_entrances  # ACS entrances this PIN code unlocks
  ```

  ```php PHP theme={null}
  $related = $seam->access_methods->get_related(
    access_method_ids: [$accessMethod->access_method_id]
  );

  echo json_encode($related->devices);        // devices this PIN code is programmed on
  echo json_encode($related->acs_entrances);  // ACS entrances this PIN code unlocks
  ```

  ```csharp C# theme={null}
  var related = seam.AccessMethods.GetRelated(
    accessMethodIds: new List<string> { accessMethod.AccessMethodId }
  );

  // related.Devices — devices this PIN code is programmed on
  // related.AcsEntrances — ACS entrances this PIN code unlocks
  ```

  ```java Java theme={null}
  var related = seam.accessMethods().getRelated(
    AccessMethodsGetRelatedRequest.builder()
      .accessMethodIds(List.of(accessMethod.getAccessMethodId()))
      .build()
  );
  ```

  ```bash cURL theme={null}
  curl -X 'POST' \
    'https://connect.getseam.com/access_methods/get_related' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d '{
    "access_method_ids": ["f47ac10b-58cc-4372-a567-0e02b2c3d479"]
  }'
  ```
</CodeGroup>

***

## Next Steps

* [Creating an Access Grant](/use-cases/granting-access/creating-an-access-grant) — Learn more about specifying devices, entrances, and spaces.
* [Access Methods API Reference](/api/access_methods/object) — See all access method properties and endpoints.