Sign-Up Supported Devices

Create an Access Code

Create an access code for a device by ID

/access_codes/create

POSThttps://connect.getseam.com/access_codes/create
Authorization
Body
device_id*string (uuid)
namestring
starts_atstring
ends_atstring
codestring
syncboolean
attempt_for_offline_deviceboolean
common_code_keystring
prefer_native_schedulingboolean
use_backup_access_code_poolboolean
allow_external_modificationboolean
is_external_modification_allowedboolean
preferred_code_lengthnumber (float)
use_offline_access_codeboolean
is_offline_access_codeboolean
is_one_time_useboolean
max_time_roundingenum
1hour1day1h1d
Response

OK

Body
action_attempt*action_attempt (one of)
access_code*access_code (object)
ok*boolean
Request
const response = await fetch('https://connect.getseam.com/access_codes/create', {
    method: 'POST',
    headers: {
      "Authorization": "Bearer Client Session Token",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "device_id": "123e4567-e89b-12d3-a456-426614174000"
    }),
});
const data = await response.json();
Response
{
  "action_attempt": {
    "action_attempt_id": "123e4567-e89b-12d3-a456-426614174000",
    "status": "pending",
    "action_type": "LOCK_DOOR"
  },
  "access_code": {
    "common_code_key": "text",
    "is_scheduled_on_device": false,
    "type": "time_bound",
    "is_waiting_for_code_assignment": false,
    "access_code_id": "123e4567-e89b-12d3-a456-426614174000",
    "device_id": "123e4567-e89b-12d3-a456-426614174000",
    "name": "text",
    "code": "text",
    "created_at": "2024-09-16T19:17:51.648Z",
    "errors": [
      {
        "message": "text",
        "is_access_code_error": true,
        "error_code": "text"
      }
    ],
    "warnings": [
      {
        "message": "text",
        "warning_code": "text"
      }
    ],
    "is_managed": true,
    "starts_at": "2024-09-16T19:17:51.648Z",
    "ends_at": "2024-09-16T19:17:51.648Z",
    "status": "setting",
    "is_backup_access_code_available": false,
    "is_backup": false,
    "pulled_backup_access_code_id": "123e4567-e89b-12d3-a456-426614174000",
    "is_external_modification_allowed": false,
    "is_one_time_use": false,
    "is_offline_access_code": false
  },
  "ok": false
}

Code Examples

Creating an Ongoing Access Code

Request:

device_id = "6aae9d08-fed6-4ca5-8328-e36849ab48fe"

created_access_code = seam.access_codes.create(
  device = device_id,
  name = "my ongoing code",
  code = "1234"
)

pprint(created_access_code)

Response:

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='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=False,
           is_offline_access_code=False,
           is_one_time_use=False)

Creating a Time-Bound Access Code

Request:

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",
  code = "2345"
)

pprint(created_access_code)

Response:

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)

Creating an Access Code with a Preferred Code Length

Request:

seam.access_codes.create(
  device = "6aae9d08-fed6-4ca5-8328-e36849ab48fe",
  name = "my access code",
  starts_at = "2025-01-01T16:00:00Z",
  ends_at = "2025-01-22T12:00:00Z",
  preferred_code_length = 4
)

Response:

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 access 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)

Creating an Hourly-Bound Offline Access Code

Request:

device_id = "9689dc30-77d8-4728-9968-b3abd0835f47"

created_access_code = seam.access_codes.create(
  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
)

pprint(created_access_code)

Response:

AccessCode(access_code_id='f078dce8-3c5e-4bc4-bd08-3ad013ee8be6',
           device_id='9689dc30-77d8-4728-9968-b3abd0835f47',
           type='time_bound',
           code=None,
           created_at='2023-11-07T03:51:56.096Z',
           errors=[],
           warnings=[],
           starts_at='2023-11-10T00:00:00.000Z',
           ends_at='2023-11-15T18:00:00.000Z',
           name='my hourly-bound offline code5',
           status='unset',
           common_code_key=None,
           is_managed=True,
           is_waiting_for_code_assignment=True,
           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,
           is_offline_access_code=True,
           is_one_time_use=False)

Creating a Daily-Bound Offline Access Code

Request:

device_id = "9689dc30-77d8-4728-9968-b3abd0835f47"

created_access_code = seam.access_codes.create(
  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
)

pprint(created_access_code)

Response:

AccessCode(access_code_id='7cac9c2c-4313-4a94-a034-ceee2a4bd9ef',
           device_id='9689dc30-77d8-4728-9968-b3abd0835f47',
           type='time_bound',
           code=None,
           created_at='2023-11-07T04:38:45.865Z',
           errors=[],
           warnings=[],
           starts_at='2023-11-17T00:00:00.000Z',
           ends_at='2023-12-18T00:00:00.000Z',
           name='my daily-bound offline code',
           status='unset',
           common_code_key=None,
           is_managed=True,
           is_waiting_for_code_assignment=True,
           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,
           is_offline_access_code=True,
           is_one_time_use=False)

Creating a One-Time-Use Offline Access Code

Request:

device_id = "9689dc30-77d8-4728-9968-b3abd0835f47"

created_access_code = seam.access_codes.create(
  device = device_id,
  name = "my one-time-use offline code",
  starts_at = "2023-11-12T00:00:00-00:00",
  is_offline_access_code = True,
  is_one_time_use = True
)

pprint(created_access_code)

Response:

AccessCode(access_code_id='995957b0-5db5-43f2-ac64-e8ad076c09cf',
           device_id='9689dc30-77d8-4728-9968-b3abd0835f47',
           type='time_bound',
           code=None,
           created_at='2023-11-07T05:03:31.469Z',
           errors=[],
           warnings=[],
           starts_at='2023-11-12T00:00:00.000Z',
           ends_at=None,
           name='my one-time-use offline code',
           status='unset',
           common_code_key=None,
           is_managed=True,
           is_waiting_for_code_assignment=True,
           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,
           is_offline_access_code=True,
           is_one_time_use=True)

Parameters

ParameterTypeDescription

device_id

String

ID of the device.

name

String Optional

Name of the access code.

starts_at

String Optional

Timestamp to indicate from when is the access code is valid.

ends_at

String Optional

Timestamp to indicate the code expiry time.

Must be a timestamp in the future and after starts_at.

code

String Optional

Access code.

use_backup_access_code_pool

Boolean Optional

Indicated whether to use a backup access code pool provided by Seam.

This enables you to use /access_codes/pull_backup_access_code

common_code_key

String Optional

Key to identify access codes that should have the same code. Any two access codes with the same common_code_key are guaranteed to have the same code.

prefer_native_scheduling

Boolean Optional

Indicates whether native scheduling should be used for time-bound codes when supported by the provider. Default: true.

allow_external_modification

Boolean Optional

Indicates whether external modification of the codes is allowed. Default: false.

is_offline_access_code

Boolean Optional

Indicates whether the access code is an offline access code.

is_one_time_use

Boolean Optional

Indicates whether the offline access code is a single-use access code.

preferred_code_length

Number Optional

Preferred code length. Only applicable if you do not specify a code.

If the affected device does not support the preferred code length, Seam reverts to using the shortest supported code length.

Response

This section shows the JSON response returned by the API. Since each language encapsulates this response inside objects specific to that language and/or implementation, the actual type in your language might differ from what’s written here.

JSON format

{
  "action_attempt": {
    "status": "pending",
    "action_type": "CREATE_ACCESS_CODE",
    "action_attempt_id": "c10e3db5-a5a2-47f2-a76f-48379ed9cd22",
    "result": null,
    "error": null
  },
  "access_code": {
    "access_code_id": "12525e70-9474-4bb6-a7f6-12bbe4166f36",
    "device_id": "1c459b4c-0008-4752-befc-bc18521247d4",
    "name": "My code",
    "code": "1988",
    "common_code_key": null,
    "type": "ongoing",
    "status": "setting",
    "created_at": "2023-05-11T11:16:10.359Z",
    "errors": [],
    "warnings": [],
    "is_managed": true,
    "is_external_modification_allowed": false,
    "is_offline_access_code": false,
    "is_one_time_use": false
  },
  "ok": true
}
PreviousAccess CodesNextCreate Many Access Codes

Last updated

Logo

Resources

Sign-UpBlogAboutSupported Devices

© Seam Labs, Inc. All rights reserved.