diff --git a/docs/api-clients/access_codes/README.md b/docs/api-clients/access_codes/README.md deleted file mode 100644 index 182cfc52f..000000000 --- a/docs/api-clients/access_codes/README.md +++ /dev/null @@ -1,124 +0,0 @@ ---- -description: Key codes to be programmed on a door lock ---- - -# Access Codes - -### `access_code` Properties - -The `access_code` object has the following properties: - -
PropertyTypeDescription
access_code_idString (UUID)Unique identifier for the access code.
device_idString (UUID)Unique identifier for the device associated with the access code.
codeStringCode used for access. Typically, a numeric or alphanumeric string.
nameStringName of the access code. Enables administrators and users to identify the access code easily, especially when there are numerous access codes.
common_code_keyStringUnique identifier for a group of access codes that share the same code.
appearanceObjectName as it appears on the lock provider app or on the device. This is an object with a name property, and first_name and last_name properties if the provider breaks down names into components.
statusString

Current status of the access code within the operational lifecycle. Values are: unset: Indicates a deactivated or unused state, either before activation or after deliberate deactivation.


setting: A transitional phase that indicates that the code is being configured or activated.


set: Indicates that the code is active and operational.


removing: Indicates a transitional period in which the code is being deleted or made inactive.

unknown: Indicates an indeterminate state, due to reasons such as system errors or incomplete data, that highlights a potential need for system review or troubleshooting.

is_scheduled_on_deviceBooleanIndicates whether the code is set on the device according to a preconfigured schedule.
is_managedBooleanIndicates whether Seam manages the access code.
typeEnum

Nature of the access code. Values are:

ongoing: Access codes that are active continuously until deactivated manually.

time_bound: Access codes that have a specific duration.

is_backup_access_code_availableBooleanIndicates whether a backup access code is available for use if the primary access code is lost or compromised.
is_backupBooleanIndicates whether the access code is a backup access code.
pulled_backup_access_code_idString (UUID)Identifier of the pulled backup access code. Used to associate the pulled backup access code with the original access code.
is_waiting_for_code_assignmentBooleanIndicates whether the access code is waiting for a code assignment.
is_external_modification_allowedBooleanIndicates whether changes to the access code from external sources are permitted.
is_one_time_useBooleanIndicates whether the access code can only be used once. If true, the code becomes invalid after the first use.
is_offline_access_codeBooleanIndicates 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.
starts_atDatetime (ISO 8601)Date and time at which the time-bound access code becomes active (only relevant for time_bound codes).
ends_atDatetime (ISO 8601)Date and time after which the time-bound access code becomes inactive (only relevant for time_bound codes).
created_atDatetime (ISO 8601)Date and time at which the access code was created.
errorsSee Access Code Error Types.

Collection of errors associated with the access code, structured in a dictionary format.

A unique error_code keys each error. Each error entry is an object containing two fields: message and created_at.

message is a string that describes the error.

created_at is a date that indicates when the error was generated.

This structure enables detailed tracking and timely response to critical issues.

warningsSee Access Code Warning Types.

Collection of warnings associated with the access code, structured in a dictionary format.

A unique warning_code keys each warning. Each warning entry is an object containing two fields: message and created_at.

message is a string that describes the warning.

created_at is a date that indicates when the warning was generated.

This structure enables detailed tracking and timely response to potential issues that are not critical but that may require attention.

- -{% hint style="info" %} -An **Ongoing** Access Code will be active until it has been removed from the Device. Be sure to leave both the **`starts_at`** and **`ends_at`** fields empty to specify an ongoing Access Code. - -A **Time Bound** Access Code will be programmed at the \*\*`starts_at`\*\*time, and removed at the **`ends_at`** time. -{% endhint %} - -### 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 will appear 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 down names into components such as `first_name` and `last_name`. - -In order to provide a consistent experience, Seam will identify 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 in order to meet provider constraints. - -In order to help end 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). - -## External Modification - -Seam will attempt to keep the access code on the 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 will be set to match the declared state of the access code on Seam. Any updates to the access code timings on Seam will be reflected on the device. In general, if the access code is modified external to Seam (through the lock provider's app for example), Seam will attempt 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 will attempt 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 will send an `access_code.modified_external_to_seam` event and add a `code_modified_external_to_seam` error on the access code. - -This behavior can sometimes be surprising to end users, so we recommend that you inform your users that Seam will attempt to re-set access codes on the device if they are modified or removed externally. If you would like to disable this behavior, you can set the `allow_external_modification` flag to true when an access code. When this flag is set to true, Seam will set `code_modified_external_to_seam` as a warning on the code instead of an error. - -### Access Code Error Types - -Errors are returned in a list: - -``` -"errors": [ - { - "is_access_code_error": true, - "error_code": "device_disconnected", - "message": "Device Disconnected, you may need to reconnect the device.", - "created_at": "2023-06-27T22:50:19.440Z - } -] -``` - -#### Generic Errors - -Seam recommends adding error handling logic to you application for each generic error below. Seam may add more generic errors in the future, so your application should include a fallback case if it encounters an unknown generic error code. - -See our [troubleshooting tips for access codes](../../products/smart-locks/access-codes/troubleshooting-access-code-issues.md) for our recommended responses to these error codes. - -| 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. | - -#### Specific Errors - -When Seam is able to provide more specific information beyond one of the generic errors above, one or more errors from the list of specific errors may appear. This gives your application the option to display additional context or suggest provider specific resolutions. - -{% hint style="info" %} -If the device or connected account associated with an access code has an error, it will be attached to the access code alongside any other access code errors. Treat these errors as Specific Errors. See [Device Error Types](../devices/#device-error-types) and [Connected Account Error Types](../connected_accounts/#connected-account-error-types). -{% endhint %} - -See our [troubleshooting tips for access codes](../../products/smart-locks/access-codes/troubleshooting-access-code-issues.md) for our recommended responses to these error codes. - -| Error Type | Description | -| -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `august_device_programming_delay` | August 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. | -| `august_lock_bad_access_code_format` | The access code format is not correct | -| `august_lock_missing_keypad` | August lock is missing a keypad | -| `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 | -| `duplicate_code_on_device` | An access code with the same pin already exists on the device. | -| `salto_site_user_not_subscribed` | Salto site user is not subscribed. This usually means your Salto site has reached its subscription limit. | -| `smartthings_failed_to_set_after_multiple_retries` | Failed to set code on device after multiple retries. This may be due to a conflict with an existing code on the device, or other software that may be used to manage the device. Please make sure that other applications like like Rboy or Operto are disabled. | -| `smartthings_no_free_slots_available` | There are no free slots available on the device. You will need to delete existing codes before more codes can be added to the device. | -| `kwikset_unable_to_confirm_code` | Unable to confirm that the access code is set on the Kwikset device. This is likely due to a duplicate pin code on the device that was set outside of Seam. Please update this access code's 'code' value through Seam Console or by using our [access\_codes/update endpoint](https://docs.seam.co/latest/api-clients/access_codes/update) | -| `kwikset_unable_to_confirm_deletion` | Unable to confirm deletion of the access code from the Kwikset device. It's possible that this access code was deleted from a source other than Seam. Please check the list of access codes on your Kwikset app from a device that is connected to the lock via Bluetooth or contact us for further assistance | - -### Access Code Warnings - -{% hint style="info" %} -An access code can have more than one error or warning. -{% endhint %} - -Warnings are returned in a list: - -``` -"warnings": [ - { - "warning_code": "delay_in_removing_from_device ", - "message": "We expected the device to report that the access code has been removed but it still has not.", - "created_at": "2023-06-27T22:50:19.440Z - } -] -``` - -| Warning Type | Description | -| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `delay_in_removing_from_device` | We expected the device to report that the access code has been removed but it still has not. We will continue to try and remove the code from the device. | -| `delay_in_setting_on_device` | There was an unusually long delay in programming the code onto the device. For time bound codes, this is sent when the code enters its active time. Note that this is a temporary warning and might be removed if the code is successfully set. | -| `code_modified_external_to_seam` | When we detect that a code was modified or removed externally after Seam successfully set it on the device, and the `allow_external_modification` flag is set for the code, we will set this warning instead of an error. | - -## `access_code` Methods - -* [Create an access code](create.md) -* [Create multiple linked access codes](create_multiple.md) -* [List access codes](list.md) -* [Get an access code](get.md) -* [Update an access code](update.md) -* [Update multiple linked access codes](update-multiple-linked-access-codes.md) -* [Report device access code constraints](../../api-clients/access_codes/report-device-access-code-constraints.md) -* [Delete an access code](delete.md) -* [List unmanaged access codes](unmanaged/list.md) -* [Convert an unmanaged access code](unmanaged/convert_to_managed.md) -* [Delete an unmanaged access code](unmanaged/delete.md) -* [Pull a backup access code](pull_backup_access_code.md) diff --git a/docs/api-clients/access_codes/create.md b/docs/api-clients/access_codes/create.md deleted file mode 100644 index fea0b03bf..000000000 --- a/docs/api-clients/access_codes/create.md +++ /dev/null @@ -1,1304 +0,0 @@ ---- -description: Create an access code for a device by ID ---- - -# Create an Access Code - -Creates an [access code](../../products/smart-locks/access-codes/) for a device. - -## Code Examples - -### Creating an Ongoing Access Code - -{% tabs %} -{% tab title="Python" %} -**Request:** - -```python -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) -``` -{% endtab %} - -{% tab title="cURL (bash)" %} -**Request:** - -```bash -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", - "code": "1234" -}' -``` - -**Response:** - -```json -{ - "action_attempt": { - "status": "pending", - "action_type": "CREATE_ACCESS_CODE", - "action_attempt_id": "e8efa128-c06d-40c3-8def-dbb25e5231df", - "result": null, - "error": null - }, - "access_code": { - "access_code_id": "d2047ba8-8849-467f-a07a-efab6c3673bc", - "device_id": "6aae9d08-fed6-4ca5-8328-e36849ab48fe", - "name": "my ongoing code", - "appearance": null, - "code": "1234", - "common_code_key": null, - "type": "ongoing", - "status": "setting", - "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, - "is_offline_access_code": false, - "is_one_time_use": false - }, - "ok": true -} -``` -{% endtab %} - -{% tab title="Javascript" %} -**Request:** - -```javascript -const deviceId = "6aae9d08-fed6-4ca5-8328-e36849ab48fe" - -const createdAccessCode = await seam.accessCodes.create({ - device_id: deviceId, - name: "my ongoing code", - code: "1234" -}) - -console.log(createdAccessCode) -``` - -**Response:** - -```json -{ - access_code_id: 'f4780806-076e-4cec-8081-df0ea2139d5a', - device_id: '6aae9d08-fed6-4ca5-8328-e36849ab48fe', - name: 'my ongoing code', - appearance: null, - code: '1234', - common_code_key: null, - type: 'ongoing', - status: 'setting', - 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, - is_offline_access_code: false, - is_one_time_use: false -} -``` -{% endtab %} - -{% tab title="Ruby" %} -**Request:** - -```ruby -device_id = "6aae9d08-fed6-4ca5-8328-e36849ab48fe" - -created_access_code = client.access_codes.create( - device_id: device_id, - name: "my ongoing code", - code: "1234" -) - -puts created_access_code.inspect -``` - -**Response:** - -``` - -``` -{% endtab %} - -{% tab title="PHP" %} -```php -$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', -); - -# 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 -// } -``` -{% endtab %} - -{% tab title="C#" %} -**Request:** - -```csharp -var deviceId = "6aae9d08-fed6-4ca5-8328-e36849ab48fe"; -var createdAccessCode = seam.AccessCodes.Create( - deviceId: deviceId, - name: "my ongoing code", - code: "1234" -); - -Console.WriteLine("Created access code ID: " + createdAccessCode.AccessCodeId); -``` - -**Response:** - -``` -Created access code ID: fe372cb9-1fa5-492f-9494-ea01c5558333 -``` -{% endtab %} - -{% tab title="Java" %} -**Request:** - -```java -var deviceId = "6aae9d08-fed6-4ca5-8328-e36849ab48fe"; - -AccessCode CreatedAccessCode = seam.accessCodes().create(AccessCodesCreateRequest.builder() - .deviceId(deviceId) - .name("my ongoing code") - .code("1234") - .build()); -System.out.println(CreatedAccessCode); -``` - -**Response:** - -```json -{ - "type" : "ongoing", - "access_code_id" : "aff0c858-22f6-4587-9aac-1f5d550be560", - "device_id" : "6aae9d08-fed6-4ca5-8328-e36849ab48fe", - "name" : "my ongoing code", - "code" : "1234", - "created_at" : "2023-10-30T03:43:13.403Z", - "errors" : [ ], - "warnings" : [ ], - "is_managed" : "true", - "status" : "setting", - "is_backup_access_code_available" : false, - "is_offline_access_code" : false, - "is_one_time_use" : false -} -``` -{% endtab %} -{% endtabs %} - -### Creating a Time-Bound Access Code - -{% tabs %} -{% tab title="Python" %} -**Request:** - -```python -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) -``` -{% endtab %} - -{% tab title="cURL (bash)" %} -**Request:** - -```sh -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", - "code": "2345" -}' -``` - -**Response:** - -```json -{ - "action_attempt": { - "status": "pending", - "action_type": "CREATE_ACCESS_CODE", - "action_attempt_id": "2fa34934-883b-496c-8ec1-ac023de55f5a", - "result": null, - "error": null - }, - "access_code": { - "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 - }, - "ok": true -} -``` -{% endtab %} - -{% tab title="Javascript" %} -**Request:** - -```javascript -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", - code: "2345" -}) - -console.log(createdAccessCode) -``` - -**Response:** - -```json -{ - 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 -} -``` -{% endtab %} - -{% tab title="Ruby" %} -**Request:** - -```ruby -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", - code: "2345" -) - -puts created_access_code.inspect -``` - -**Response:** - -``` - -``` -{% endtab %} - -{% tab title="PHP" %} -```php -$seam = new SeamClient("seam_test2ek7_2sq2ExLasPDwa9foJ8PyQ2zH"); - -$device_id = "0e2e6262-7f91-4970-a58d-47ef30b41e2e"; - -$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" -); - -# Inspect this timebound code -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 -// } -``` -{% endtab %} - -{% tab title="C#" %} -**Request:** - -```csharp -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", - code: "2345" -); - -Console.WriteLine("Created access code ID: " + createdAccessCode.AccessCodeId); -``` - -**Response:** - -``` -Created access code ID: 2928083e-4377-4467-ab33-c600ec48cdec -``` -{% endtab %} - -{% tab title="Java" %} -**Request:** - -```java -var deviceId = "6aae9d08-fed6-4ca5-8328-e36849ab48fe"; - -AccessCode CreatedAccessCode = seam.accessCodes().create(AccessCodesCreateRequest.builder() - .deviceId(deviceId) - .name("my time-bound code") - .startsAt("2025-01-01T16:00:00Z") - .endsAt("2025-01-22T12:00:00Z") - .code("2345") - .build()); -System.out.println(CreatedAccessCode); -``` - -**Response:** - -```json -{ - "is_scheduled_on_device" : false, - "type" : "time_bound", - "access_code_id" : "48e8f0e3-11a4-49a4-b589-27a1baf7aee4", - "device_id" : "6aae9d08-fed6-4ca5-8328-e36849ab48fe", - "name" : "my time-bound code", - "code" : "2345", - "created_at" : "2023-10-30T03:50:17.802Z", - "errors" : [ ], - "warnings" : [ ], - "is_managed" : "true", - "starts_at" : "2025-01-01T16:00:00Z", - "ends_at" : "2025-01-22T12:00:00Z", - "status" : "unset", - "is_backup_access_code_available" : false -} -``` -{% endtab %} -{% endtabs %} - -### Creating an Access Code with a Preferred Code Length - -{% tabs %} -{% tab title="Python" %} -**Request:** - -```python -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) -``` -{% endtab %} - -{% tab title="cURL (bash)" %} -**Request:** - -```sh -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": "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:** - -```json -{ - "action_attempt": { - "status": "pending", - "action_type": "CREATE_ACCESS_CODE", - "action_attempt_id": "2fa34934-883b-496c-8ec1-ac023de55f5a", - "result": null, - "error": null - }, - "access_code": { - "access_code_id": "27afb24f-c0ae-4ea9-81af-f06fd08de09f", - "device_id": "6aae9d08-fed6-4ca5-8328-e36849ab48fe", - "name": "my access 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 - }, - "ok": true -} -``` -{% endtab %} - -{% tab title="JavaScript" %} -**Request:** - -```javascript -await seam.accessCodes.create({ - device_id: "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:** - -```json -{ - access_code_id: '80aa1afa-f0e5-43c2-96ea-6ab141112f9c', - device_id: '6aae9d08-fed6-4ca5-8328-e36849ab48fe', - name: 'my access 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 -} -``` -{% endtab %} - -{% tab title="Ruby" %} -**Request:** - -```ruby -created_access_code = client.access_codes.create( - device_id: "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:** - -``` - -``` -{% endtab %} - -{% tab title="PHP" %} -**Request:** - -```php -$access_code = $seam->access_codes->create( - device_id: "0e2e6262-7f91-4970-a58d-47ef30b41e2e", - name: 'my access code', - starts_at: "2025-01-01T16:00:00Z", - ends_at: "2025-01-22T12:00:00Z", - preferred_code_length: 4 -); -``` - -**Response:** - -```json -{ - "access_code_id": "e3d6cf81-6dd4-490c-b81f-8478054c2003", - "device_id": "0e2e6262-7f91-4970-a58d-47ef30b41e2e", - "name": "my access code", - "type": "time_bound", - "status": "unset", - "starts_at": "2025-01-01T16:00:00.000Z", - "ends_at": "2025-01-22T12:00:00.000Z", - "code": "2345", - "created_at": "2023-09-04T05:32:32.085Z", - "errors": [], - "warnings": [], - "is_managed": true, - "common_code_key": null, - "is_waiting_for_code_assignment": null -} -``` -{% endtab %} - -{% tab title="C#" %} -**Request:** - -```csharp -var createdAccessCode = seam.AccessCodes.Create( - deviceId: "6aae9d08-fed6-4ca5-8328-e36849ab48fe", - name: "my access code", - startsAt: "2025-01-01T16:00:00Z", - endsAt: "2025-01-22T12:00:00Z", - preferredCodeLength: 4 -); -``` - -**Response:** - -``` -{ - "access_code_id": "27afb24f-c0ae-4ea9-81af-f06fd08de09f", - "device_id": "6aae9d08-fed6-4ca5-8328-e36849ab48fe", - "name": "my access 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 -} -``` -{% endtab %} - -{% tab title="Java" %} -**Request:** - -```java -seam.accessCodes().create(AccessCodesCreateRequest.builder() - .deviceId("6aae9d08-fed6-4ca5-8328-e36849ab48fe") - .name("my access code") - .startsAt("2025-01-01T16:00:00Z") - .endsAt("2025-01-22T12:00:00Z") - .preferredCodeLength(4) - .build()); -``` - -**Response:** - -```json -{ - "is_scheduled_on_device" : false, - "type" : "time_bound", - "access_code_id" : "48e8f0e3-11a4-49a4-b589-27a1baf7aee4", - "device_id" : "6aae9d08-fed6-4ca5-8328-e36849ab48fe", - "name" : "my access code", - "code" : "2345", - "created_at" : "2023-10-30T03:50:17.802Z", - "errors" : [ ], - "warnings" : [ ], - "is_managed" : "true", - "starts_at" : "2025-01-01T16:00:00Z", - "ends_at" : "2025-01-22T12:00:00Z", - "status" : "unset", - "is_backup_access_code_available" : false -} -``` -{% endtab %} -{% endtabs %} - -### Creating an Time-Bound Offline Access Code - -{% tabs %} -{% tab title="Python" %} -**Request:** - -```python -device_id = "9689dc30-77d8-4728-9968-b3abd0835f47" - -created_access_code = seam.access_codes.create( - 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", - 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 time-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) -``` -{% endtab %} - -{% tab title="cURL (bash)" %} -**Request:** - -```sh -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": "9689dc30-77d8-4728-9968-b3abd0835f47", - "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 -}' -``` - -**Response:** - -```json -{ - "action_attempt": { - "status": "pending", - "action_type": "CREATE_ACCESS_CODE", - "action_attempt_id": "83f1eebf-7a1b-4487-bc90-cf342e1d10d7", - "result": null, - "error": null - }, - "access_code": { - "access_code_id": "a4960c38-fe15-4766-8647-c93e8f05f84a", - "device_id": "9689dc30-77d8-4728-9968-b3abd0835f47", - "name": "my time-bound offline code", - "appearance": null, - "code": null, - "is_waiting_for_code_assignment": true, - "common_code_key": null, - "type": "time_bound", - "status": "unset", - "is_scheduled_on_device": false, - "starts_at": "2023-11-10T00:00:00.000Z", - "ends_at": "2023-11-15T18:00:00.000Z", - "is_backup_access_code_available": false, - "created_at": "2023-11-07T03:53:41.971Z", - "errors": [], - "warnings": [], - "is_managed": true, - "is_external_modification_allowed": false, - "is_offline_access_code": true, - "is_one_time_use": false - }, - "ok": true -} -``` -{% endtab %} - -{% tab title="JavaScript" %} -**Request:** - -```javascript -const deviceId = "ea12f6c6-e63e-447d-856b-ec9e92981000" - -const createdAccessCode = await seam.accessCodes.create({ - device_id: deviceId, - name: "my time-bound offline code", - starts_at: "2023-12-22T06:00:00-00:00", - ends_at: "2023-12-22T18:00:00-00:00", - max_time_rounding: "1h", - is_offline_access_code: true -}) - -console.log(createdAccessCode) -``` - -**Response:** - -```json -{ - access_code_id: 'b4977781-7108-478a-a5ec-764b51ba2647', - device_id: 'ea12f6c6-e63e-447d-856b-ec9e92981000', - name: 'my time-bound offline code', - appearance: null, - code: null, - is_waiting_for_code_assignment: true, - common_code_key: null, - type: 'time_bound', - status: 'unset', - starts_at: '2023-12-22T06:00:00.000Z', - ends_at: '2023-12-22T18:00:00.000Z', - is_backup_access_code_available: false, - created_at: '2023-12-11T21:46:32.914Z', - errors: [], - warnings: [], - is_managed: true, - is_external_modification_allowed: false, - is_offline_access_code: true, - is_one_time_use: false -} -``` -{% endtab %} -{% endtabs %} - -### Creating a Daily-Bound Offline Access Code - -{% tabs %} -{% tab title="Python" %} -**Request:** - -```python -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) -``` -{% endtab %} - -{% tab title="cURL (bash)" %} -**Request:** - -```sh -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": "9689dc30-77d8-4728-9968-b3abd0835f47", - "name": "my daily-bound offline code", - "type": "time_bound", - "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 -}' -``` - -**Response:** - -```json -{ - "action_attempt": { - "status": "pending", - "action_type": "CREATE_ACCESS_CODE", - "action_attempt_id": "487a8bcc-00f0-45ff-be80-3f0e9d6fdfe5", - "result": null, - "error": null - }, - "access_code": { - "access_code_id": "08d4a763-f2a5-4544-8c90-bce5217fe7b2", - "device_id": "9689dc30-77d8-4728-9968-b3abd0835f47", - "name": "my daily-bound offline code", - "appearance": null, - "code": null, - "is_waiting_for_code_assignment": true, - "common_code_key": null, - "type": "time_bound", - "status": "unset", - "is_scheduled_on_device": false, - "starts_at": "2023-11-17T00:00:00.000Z", - "ends_at": "2023-12-18T00:00:00.000Z", - "is_backup_access_code_available": false, - "created_at": "2023-11-07T04:41:15.797Z", - "errors": [], - "warnings": [], - "is_managed": true, - "is_external_modification_allowed": false, - "is_offline_access_code": true, - "is_one_time_use": false - }, - "ok": true -} -``` -{% endtab %} - -{% tab title="JavaScript" %} -**Request:** - -```javascript -const deviceId = "ea12f6c6-e63e-447d-856b-ec9e92981000" - -const createdAccessCode = await seam.accessCodes.create({ - device_id: deviceId, - name: "my daily-bound offline code", - starts_at: "2023-12-22T23:00:00-00:00", - ends_at: "2023-12-27T22:59:00-00:00", - max_time_rounding: "1d", - is_offline_access_code: true -}) - -console.log(createdAccessCode) -``` - -**Response:** - -```json -{ - access_code_id: 'fb044bde-df9b-4130-bc1a-c0254ab919aa', - device_id: 'ea12f6c6-e63e-447d-856b-ec9e92981000', - name: 'my daily-bound offline code', - appearance: null, - code: null, - is_waiting_for_code_assignment: true, - common_code_key: null, - type: 'time_bound', - status: 'unset', - starts_at: '2023-12-22T23:00:00.000Z', - ends_at: '2023-12-27T22:59:00.000Z', - is_backup_access_code_available: false, - created_at: '2023-12-11T22:06:27.366Z', - errors: [], - warnings: [], - is_managed: true, - is_external_modification_allowed: false, - is_offline_access_code: true, - is_one_time_use: false -} -``` -{% endtab %} -{% endtabs %} - -### Creating a One-Time-Use Offline Access Code - -{% tabs %} -{% tab title="Python" %} -**Request:** - -```python -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) -``` -{% endtab %} - -{% tab title="cURL (bash)" %} -**Request:** - -```sh -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": "9689dc30-77d8-4728-9968-b3abd0835f47", - "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 -}' -``` - -**Response:** - -```json -{ - "action_attempt": { - "status": "pending", - "action_type": "CREATE_ACCESS_CODE", - "action_attempt_id": "67562d28-1e54-4faa-b5f8-057bbc6de91d", - "result": null, - "error": null - }, - "access_code": { - "access_code_id": "27000544-20d8-45ea-ba47-267480a3aaf4", - "device_id": "9689dc30-77d8-4728-9968-b3abd0835f47", - "name": "my one-time-use offline code", - "appearance": null, - "code": null, - "is_waiting_for_code_assignment": true, - "common_code_key": null, - "type": "time_bound", - "status": "unset", - "is_scheduled_on_device": false, - "starts_at": "2023-11-12T00:00:00.000Z", - "is_backup_access_code_available": false, - "created_at": "2023-11-07T05:08:03.467Z", - "errors": [], - "warnings": [], - "is_managed": true, - "is_external_modification_allowed": false, - "is_offline_access_code": true, - "is_one_time_use": true - }, - "ok": true -} -``` -{% endtab %} -{% endtabs %} - -*** - -### Parameters - -| Parameter | Type | Description | -| ----------------------------- | ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `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](../../products/smart-locks/access-codes/offline-access-codes.md). | -| `is_one_time_use` |

Boolean
Optional

| Indicates whether the [offline access code](../../products/smart-locks/access-codes/offline-access-codes.md) 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 - -{% tabs %} -{% tab title="JSON" %} -```json -{ - "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 -} -``` -{% endtab %} -{% endtabs %} diff --git a/docs/api-clients/access_codes/create_multiple.md b/docs/api-clients/access_codes/create_multiple.md deleted file mode 100644 index de715b3e2..000000000 --- a/docs/api-clients/access_codes/create_multiple.md +++ /dev/null @@ -1,95 +0,0 @@ ---- -description: Create access codes across multiple devices that share a common code ---- - -# Create Multiple Linked Access Codes - -{% openapi src="../../.gitbook/assets/openapi (2).json" path="/access_codes/create_multiple" method="post" %} -[openapi (2).json](<../../.gitbook/assets/openapi (2).json>) -{% endopenapi %} - -### Code Example - -{% tabs %} -{% tab title="JavaScript" %} -```javascript -await seam.accessCodes.createMultiple({ - device_id: [ - "a83690b2-2b70-409a-9a94-426699b84c97", - "7bfe1838-5e64-432c-adb6-34e971bda001" - ], - preferred_code_length: 4 -}); - -/* -[ - { - code: '9913', - type: 'ongoing', - status: 'setting', - created_at: '2022-08-26T11:08:24.161Z', - access_code_id: 'e0e31756-9385-408b-89f8-9f5ea43f9adf', - device_id: 'a83690b2-2b70-409a-9a94-426699b84c97', - common_code_key: 'auto_set_by_create_multiple_996c8131-34a4-4d58-86c4-7820f2ccdefb', - }, - { - code: '9913', - type: 'ongoing', - status: 'setting', - created_at: '2022-08-26T11:08:24.161Z', - access_code_id: 'f3a89135-1101-4197-b272-4b4c5ed092b5', - device_id: '7bfe1838-5e64-432c-adb6-34e971bda001', - common_code_key: 'auto_set_by_create_multiple_996c8131-34a4-4d58-86c4-7820f2ccdefb', - } -] -*/ -``` -{% endtab %} -{% endtabs %} - -### Parameters - -| `device_ids` | type: string\[] |


ID of the Device

| -| ------------------------------------- | --------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `name` |

type: string
Optional

| Name of Access Codes | -| `starts_at` |

type: string
Optional

| From when is the code valid | -| `ends_at` |

type: string
Optional

| Code expiry | -| `behavior_when_code_cannot_be_shared` |

type: enum
Optional, default throw

| If `throw`, no access codes will be created if any device cannot share a code. If `create_random_code`, a random code will be created on devices that cannot share a code. | -| `preferred_code_length` |

type: number
Optional

|

Preferred code length
If the affected devices do not support the preferred code length, Seam reverts to using the shortest supported code length.

| -| `code` |

type: string
Optional

|

Code (PIN) to assign to each created access code.

If you specify a code, Seam does not link the created access codes with a common_code_key, so you cannot then update these access codes using /access_codes/update_multiple. You can, however, update each access code individually using /access_codes/update.

| - -### 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 - -{% tabs %} -{% tab title="JSON" %} -```json -{ - "access_codes": [ - { - "code": "9913", - "type": "ongoing", - "status": "setting", - "created_at": "2022-08-26T11:08:24.161Z", - "access_code_id": "e0e31756-9385-408b-89f8-9f5ea43f9adf", - "device_id": "a83690b2-2b70-409a-9a94-426699b84c97", - "common_code_key": "auto_set_by_create_multiple_996c8131-34a4-4d58-86c4-7820f2ccdefb", - }, - { - "code": "9913", - "type": "ongoing", - "status": "setting", - "created_at": "2022-08-26T11:08:24.161Z", - "access_code_id": "f3a89135-1101-4197-b272-4b4c5ed092b5", - "device_id": "7bfe1838-5e64-432c-adb6-34e971bda001", - "common_code_key": "auto_set_by_create_multiple_996c8131-34a4-4d58-86c4-7820f2ccdefb", - } - ], - "ok": true -} -``` -{% endtab %} -{% endtabs %} diff --git a/docs/api-clients/access_codes/delete.md b/docs/api-clients/access_codes/delete.md deleted file mode 100644 index 5846b9ba7..000000000 --- a/docs/api-clients/access_codes/delete.md +++ /dev/null @@ -1,59 +0,0 @@ -# Delete an Access Code - -`DELETE` `https://connect.getseam.com/access_codes/delete` - -## Request - -### Request Parameters - -| Name | Type | Description | -| -------------------------------------------------- | ------ | ---------------------- | -| access\_code\_id\* | String | ID of the access code. | - -### Sample Request - -{% tabs %} -{% tab title="Ruby" %} -```ruby -seam.access_codes.delete(access_code_id: "123e4567-e89b-12d3-a456-426614174000") - -# -``` -{% endtab %} - -{% tab title="Python" %} -```python -seam.access_codes.delete("0080cddd-e0ba-407d-b8c7-d0865bd1e3c4") -``` -{% endtab %} - -{% tab title="Javascript" %} -```javascript -await seam.accessCodes.delete({ - access_code_id: "1e9c85c3-77dc-481c-8fc1-3a10121ebe67", -}); - -//{} -``` -{% endtab %} -{% endtabs %} - -## 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. - -### Sample Response - -{% tabs %} -{% tab title="JSON" %} -```json -{ - "ok": true -} -``` -{% endtab %} -{% endtabs %} diff --git a/docs/api-clients/access_codes/get.md b/docs/api-clients/access_codes/get.md deleted file mode 100644 index 255ee1d0c..000000000 --- a/docs/api-clients/access_codes/get.md +++ /dev/null @@ -1,118 +0,0 @@ ---- -description: Get Access Code of a Device by its Access Code ID ---- - -# Get an Access Code - -{% swagger method="get" path="/access_codes/get" baseUrl="https://connect.getseam.com" summary="Get an Access Code" %} -{% swagger-description %} - -{% endswagger-description %} - -{% swagger-parameter in="query" name="access_code_id" required="true" %} - -{% endswagger-parameter %} - -{% swagger-response status="200: OK" description="" %} -```javascript -{ - "access_code": { - "code": "1988", - "type": "ongoing", - "status": "setting", - "created_at": "2022-08-26T12:50:17.858Z", - "access_code_id": "26d6138c-6524-4f3c-ac96-43cc3bea0a8d" - }, - "ok": true -} -``` -{% endswagger-response %} - -{% swagger-response status="400: Bad Request" description="" %} -```javascript -{ - "error": { - "type": "internal_server_error", - "message": "Undefined binding(s) detected when compiling FIRST. Undefined column(s): [device_id] query: select \"device_id\" from \"seam\".\"device\" where \"workspace_id\" = ? and \"device_id\" = ? limit ?", - "request_id": "cd32ef1e-6e14-4bcb-ab34-b88bfb5c1a1b" - }, - "ok": false -} -``` -{% endswagger-response %} - -{% swagger-response status="404: Not Found" description="" %} -```javascript -{ - "error": { - "type": "device_not_found", - "message": "Device not found", - "request_id": "bf6643a3-a102-4f3b-b4c3-bd8cd1119ba2" - }, - "ok": false -} -``` -{% endswagger-response %} -{% endswagger %} - -### Code Example - -{% tabs %} -{% tab title="Ruby" %} -```ruby -seam.access_codes.get(access_code_id: "123e4567-e89b-12d3-a456-426614174000") - -# -``` -{% endtab %} - -{% tab title="Python" %} -```python -seam.access_codes.get("26d6138c-6524-4f3c-ac96-43cc3bea0a8d") - -# AccessCode( -# access_code_id='26d6138c-6524-4f3c-ac96-43cc3bea0a8d', -# type='ongoing', -# code='1988', -# starts_at=None, -# ends_at=None, -# name='', -# status='setting' -# ) -# -``` -{% endtab %} -{% endtabs %} - -### Parameters - -| `access_code_id` | type: string |


ID of the Access Code

| -| ---------------- | ------------ | -------------------------------- | - -### 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 - -{% tabs %} -{% tab title="JSON" %} -```json -{ - "access_code": { - "code": "1988", - "type": "ongoing", - "status": "setting", - "created_at": "2022-08-26T12:50:17.858Z", - "access_code_id": "26d6138c-6524-4f3c-ac96-43cc3bea0a8d" - }, - "ok": true -} -``` -{% endtab %} -{% endtabs %} diff --git a/docs/api-clients/access_codes/list.md b/docs/api-clients/access_codes/list.md deleted file mode 100644 index 11fbc5451..000000000 --- a/docs/api-clients/access_codes/list.md +++ /dev/null @@ -1,257 +0,0 @@ ---- -description: Get all access codes ---- - -# List Access Codes - -Returns a list of all [access codes](../../products/smart-locks/access-codes/). - -{% swagger src="https://connect.getseam.com/openapi.json" path="/access_codes/list" method="post" %} -[https://connect.getseam.com/openapi.json](https://connect.getseam.com/openapi.json) -{% endswagger %} - -*** - -## Request - -Filter the list of returned access codes by device ID or access code IDs. You can also filter by user identifier key. You must include at least `device_id` or `access_code_ids`. - -### Request Body Parameters - -
ParameterTypeDescription
device_idString (UUID)
Optional		ID of the devices for which to retrieve access codes.
access_code_idsArray of strings (UUIDs)
Optional		IDs of the access codes to retrieve.
user_identifier_keyString
Optional		Your own internal user ID for the user by which to filter access codes.
- -### Sample Request - -{% tabs %} -{% tab title="Python" %} -```python -seam.access_codes.list( - device_id="11111111-1111-1111-1111-444444444444" -) -``` -{% endtab %} - -{% tab title="cURL (bash)" %} -```bash -# 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": "11111111-1111-1111-1111-444444444444" - }' -``` -{% endtab %} - -{% tab title="JavaScript" %} -```typescript -await seam.access_codes.list({ - device_id: "11111111-1111-1111-1111-444444444444" -}) -``` -{% endtab %} - -{% tab title="Ruby" %} -```ruby -client.access_codes.list( - device_id: "11111111-1111-1111-1111-444444444444" -) -``` -{% endtab %} - -{% tab title="C#" %} -```csharp -seam.AccessCodes.List( - deviceId: "11111111-1111-1111-1111-444444444444" -); -``` -{% endtab %} - -{% tab title="Java" %} -```java -seam.accessCodes().list(AccessCodesListRequest.builder() - .deviceId("11111111-1111-1111-1111-444444444444") - .build()); -``` -{% endtab %} -{% endtabs %} - -## Response - -Returns an `access_codes` array, in which each returned `access_code` contains the set of applicable access code properties. For details, see [Access Codes](./). - -### Sample Response - -{% tabs %} -{% tab title="Python" %} -``` -[ - AccessCode( - access_code_id='1bbd1eba-e4a2-4f96-b1b9-8498a5405b2b', - device_id='11111111-1111-1111-1111-444444444444', - 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 - ), - ... -] -``` -{% endtab %} - -{% tab title="cURL (bash)" %} -```json -{ - "access_codes": [ - { - "access_code_id": "27afb24f-c0ae-4ea9-81af-f06fd08de09f", - "device_id": "11111111-1111-1111-1111-444444444444", - "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 - }, - ... - ], - "ok": true -} -``` -{% endtab %} - -{% tab title="JavaScript" %} -```json -[ - { - access_code_id: '80aa1afa-f0e5-43c2-96ea-6ab141112f9c', - device_id: '11111111-1111-1111-1111-444444444444', - 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 - }, - ... -] -``` -{% endtab %} - -{% tab title="Ruby" %} -{% code overflow="wrap" %} -``` -[ - , - ... -] -``` -{% endcode %} -{% endtab %} - -{% tab title="C#" %} -```json -[ - { - access_code_id: '80aa1afa-f0e5-43c2-96ea-6ab141112f9c', - device_id: '11111111-1111-1111-1111-444444444444', - 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 - }, - ... -] -``` -{% endtab %} - -{% tab title="Java" %} -```json -[ - { - "is_scheduled_on_device" : false, - "type" : "time_bound", - "access_code_id" : "48e8f0e3-11a4-49a4-b589-27a1baf7aee4", - "device_id" : "11111111-1111-1111-1111-444444444444", - "name" : "my time-bound code", - "code" : "2345", - "created_at" : "2023-10-30T03:50:17.802Z", - "errors" : [ ], - "warnings" : [ ], - "is_managed" : "true", - "starts_at" : "2025-01-01T16:00:00Z", - "ends_at" : "2025-01-22T12:00:00Z", - "status" : "unset", - "is_backup_access_code_available" : false - }, - ... -] -``` -{% endtab %} -{% endtabs %} diff --git a/docs/api-clients/access_codes/pull_backup_access_code.md b/docs/api-clients/access_codes/pull_backup_access_code.md deleted file mode 100644 index d7652ac2b..000000000 --- a/docs/api-clients/access_codes/pull_backup_access_code.md +++ /dev/null @@ -1,165 +0,0 @@ ---- -description: Pull a backup access code from Seam's backup access code pool ---- - -# Pull Backup Access Code - -If you've opted-in to [Seam's backup access code pool](../../products/smart-locks/access-codes/backup-access-codes.md) when [creating an access code](./create.md), 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 the access code ends. - -### Code Examples - -{% swagger method="post" path="/access_codes/pull_backup_access_code" baseUrl="https://connect.getseam.com" summary="Pull a Backup Access Code" %} -{% swagger-description %} -Pull a backup access code from Seam's backup access code pool for this access code. You can only pull backup access codes for `time_bound` codes. The pulled backup access code will be removed at the same time as the original access code. -{% endswagger-description %} - -{% swagger-parameter in="body" name="access_code_id" required="true" %} -Access Code ID -{% endswagger-parameter %} - -{% swagger-parameter in="header" name="Authorization" required="true" %} -Bearer \ -{% endswagger-parameter %} - -{% swagger-response status="201: Created" description="" %} -```javascript -{ - "backup_access_code": { - "access_code_id": "12525e70-9474-4bb6-a7f6-12bbe4166f36", - "device_id": "1c459b4c-0008-4752-befc-bc18521247d4", - "name": "Backup 12525e70 (Seam)", - "code": "1970", - "common_code_key": null, - "type": "time_bound", - "starts_at": "2023-05-11T11:16:10.359Z", - "ends_at": "2022-08-13T19:23:42+0000" - "status": "set", - "created_at": "2023-05-11T11:16:10.359Z", - "errors": [], - "warnings": [], - "is_managed": true, - "is_backup": true - }, - "ok": true -} -``` -{% endswagger-response %} - -{% swagger-response status="400: Bad Request" description="" %} -```javascript -{ - "error": { - "type": "invalid_input", - "message": "Required for provided \"access_code_id\"", - "validation_errors": { - "_errors": [], - "access_code_id": { - "_errors": [ - "Required" - ] - } - }, - "request_id": "9f3e59f1-cfb5-4e48-93df-0a988554eb0b" - }, - "ok": false -} -``` -{% endswagger-response %} -{% endswagger %} - -#### Pulling a Backup Access Code - -{% tabs %} -{% tab title="Ruby" %} -```ruby -seam.access_codes.pull_backup_access_code( - access_code_id: "123e4567-e89b-12d3-a456-426614174000", -) - -# -``` -{% endtab %} - -{% tab title="Python" %} -```python -seam.access_codes.pull_backup_access_code("a83690b2-2b70-409a-9a94-426699b84c97") - -# AccessCode( -# access_code_id='a9f66aa7-44fb-4b91-b7a8-22c0f996bfc1', -# type='time_bound', code='7732', -# starts_at="2022-08-12T19:23:42+0000" -# ends_at="2022-08-13T19:23:42+0000" -# name='Backup 123e4567 (Seam)', -# is_backup=True -# status='set' -# ) -``` -{% endtab %} - -{% tab title="Javascript" %} -```javascript -await seam.accessCodes.pullBackupAccessCode({ - access_code_id: "a83690b2-2b70-409a-9a94-426699b84c97", -}) - -/* -{ - code: '9913', - type: 'time_bound', - status: 'set', - is_backup: true, - starts_at:"2022-08-12T19:23:42+0000", - ends_at:"2022-08-13T19:23:42+0000", - created_at: '2022-08-26T11:08:24.161Z', - access_code_id: 'e0e31756-9385-408b-89f8-9f5ea43f9adf' -} -*/ -``` -{% endtab %} -{% endtabs %} - -### Parameters - -| `access_code_id` | type: string |


ID of the Access Code

| -| ---------------- | ------------ | -------------------------------- | - -### 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 - -{% tabs %} -{% tab title="JSON" %} -```json -{ - "backup_access_code": { - "access_code_id": "12525e70-9474-4bb6-a7f6-12bbe4166f36", - "device_id": "1c459b4c-0008-4752-befc-bc18521247d4", - "name": "Backup 12525e70 (Seam)", - "code": "1988", - "common_code_key": null, - "type": "time_bound", - "status": "set", - "starts_at": "2022-08-12T19:23:42+0000", - "ends_at": "2022-08-13T19:23:42+0000", - "created_at": "2023-05-11T11:16:10.359Z", - "errors": [], - "warnings": [], - "is_managed": true, - "is_backup": true - }, - "ok": true -} -``` -{% endtab %} -{% endtabs %} diff --git a/docs/api-clients/access_codes/report-device-access-code-constraints.md b/docs/api-clients/access_codes/report-device-access-code-constraints.md deleted file mode 100644 index 850bbb2e1..000000000 --- a/docs/api-clients/access_codes/report-device-access-code-constraints.md +++ /dev/null @@ -1,377 +0,0 @@ ---- -description: Report access code-related constraints for a device. ---- - -# Report Device Access Code Constraints - -``` -POST /access_codes/report_device_constraints ⇒ void -``` - -Enables you to report access code-related constraints for a device. - -{% hint style="info" %} -Currently, this endpoint supports reporting supported code length constraints for SmartThings devices. Specify either `supported_code_lengths` or `min_code_length`/`max_code_length`. -{% endhint %} - -## Report Supported Code Lengths - -{% tabs %} -{% tab title="Python" %} -**Request:** - -```python -seam.access_codes.report_device_constraints( - device_id = "11111111-1111-1111-1111-444444444444", - supported_code_lengths = [4, 5, 6] -) -``` - -**Response:** - -``` -None -``` -{% endtab %} - -{% tab title="cURL (bash)" %} -**Request:** - -```sh -curl -X 'POST' \ - 'https://connect.getseam.com/access_codes/report_device_constraints' \ - -H 'accept: application/json' \ - -H "Authorization: Bearer ${SEAM_API_KEY}" \ - -H 'Content-Type: application/json' \ - -d '{ - "device_id": "11111111-1111-1111-1111-444444444444", - "supported_code_lengths": [4, 5, 6] -}' -``` - -**Response:** - -```json -{ - "ok": true -} -``` -{% endtab %} - -{% tab title="JavaScript" %} -**Request:** - -```javascript -await seam.accessCodes.reportDeviceConstraints({ - device_id: "11111111-1111-1111-1111-444444444444", - supported_code_lengths: [4, 5, 6] -}); -``` - -**Response:** - -```json -void -``` -{% endtab %} - -{% tab title="Ruby" %} -**Request:** - -```ruby -client.access_codes.report_device_constraints( - device_id: "11111111-1111-1111-1111-444444444444", - supported_code_lengths: [4, 5, 6] -) -``` - -**Response:** - -``` -void -``` -{% endtab %} - -{% tab title="PHP" %} -**Request:** - -```php -$seam->access_codes->report_device_constraints( - device_id: "11111111-1111-1111-1111-444444444444", - supported_code_lengths: [4, 5, 6] -); -``` - -**Response:** - -```json -void -``` -{% endtab %} - -{% tab title="C#" %} -**Request:** - -```csharp -List codeLengths = new() { 4, 5, 6 }; - -seam.AccessCodes.reportDeviceConstraints( - deviceId: "11111111-1111-1111-1111-444444444444", - supportedCodeLengths: codeLengths -); -``` - -**Response:** - -```json -void -``` -{% endtab %} - -{% tab title="Java" %} -**Request:** - -```java -seam.accessCodes() - .reportDeviceConstraints(AccessCodesReportDeviceConstraintsRequest.builder() - .deviceId("11111111-1111-1111-1111-444444444444") - .supportedCodeLengths(List.of(4, 5, 6)) - .build()); -``` - -**Response:** - -```json -void -``` -{% endtab %} - -{% tab title="Go" %} -**Request:** - -```go -codeLengths := []int { 4, 5, 6 } - -client.AccessCodes.ReportDeviceConstraints( - context.Background(), - &api.AccessCodesReportDeviceConstraintsRequest{ - DeviceId: "11111111-1111-1111-1111-444444444444", - SupportedCodeLengths: codeLengths, - }, -) - -if uErr != nil { - return uErr -} - -return nil -``` - -**Response:** - -```json -void -``` -{% endtab %} -{% endtabs %} - -## Report Minimum and Maximum Supported Code Lengths - -{% tabs %} -{% tab title="Python" %} -**Request:** - -```python -seam.access_codes.report_device_constraints( - device_id = "11111111-1111-1111-1111-444444444444", - min_code_length = 4, - max_code_length = 6 -) -``` - -**Response:** - -``` -None -``` -{% endtab %} - -{% tab title="cURL (bash)" %} -**Request:** - -```sh -curl -X 'POST' \ - 'https://connect.getseam.com/access_codes/report_device_constraints' \ - -H 'accept: application/json' \ - -H "Authorization: Bearer ${SEAM_API_KEY}" \ - -H 'Content-Type: application/json' \ - -d '{ - "device_id": "11111111-1111-1111-1111-444444444444", - "min_code_length": 4, - "max_code_length": 6 -}' -``` - -**Response:** - -```json -{ - "ok": true -} -``` -{% endtab %} - -{% tab title="JavaScript" %} -**Request:** - -```javascript -await seam.accessCodes.reportDeviceConstraints({ - device_id: "11111111-1111-1111-1111-444444444444", - min_code_length: 4, - max_code_length: 6 -}); -``` - -**Response:** - -```json -void -``` -{% endtab %} - -{% tab title="Ruby" %} -**Request:** - -```ruby -client.access_codes.report_device_constraints( - device_id: "11111111-1111-1111-1111-444444444444", - min_code_length: 4, - max_code_length: 6 -) -``` - -**Response:** - -``` -void -``` -{% endtab %} - -{% tab title="PHP" %} -**Request:** - -```php -$seam->access_codes->report_device_constraints( - device_id: "11111111-1111-1111-1111-444444444444", - min_code_length: 4, - max_code_length: 6 -); -``` - -**Response:** - -```json -void -``` -{% endtab %} - -{% tab title="C#" %} -**Request:** - -```csharp -seam.AccessCodes.reportDeviceConstraints( - deviceId: "11111111-1111-1111-1111-444444444444", - minCodeLength: 4, - maxCodeLength: 6 -); -``` - -**Response:** - -```json -void -``` -{% endtab %} - -{% tab title="Java" %} -**Request:** - -```java -seam.accessCodes() - .reportDeviceConstraints(AccessCodesReportDeviceConstraintsRequest.builder() - .deviceId("11111111-1111-1111-1111-444444444444") - .minCodeLength(4) - .maxCodeLength(6) - .build()); -``` - -**Response:** - -```json -void -``` -{% endtab %} - -{% tab title="Go" %} -**Request:** - -```go -client.AccessCodes.ReportDeviceConstraints( - context.Background(), - &api.AccessCodesReportDeviceConstraintsRequest{ - DeviceId: "11111111-1111-1111-1111-444444444444", - MinCodeLength: 4, - MaxCodeLength: 6 - }, -) - -if uErr != nil { - return uErr -} - -return nil -``` - -**Response:** - -```json -void -``` -{% endtab %} -{% endtabs %} - -## Request Parameters - -### `device_id` - -Type: `string` Required: Yes - -ID of the device for which to report constraints. - -*** - -### `supported_code_lengths` - -Type: `string` Required: No - -Array of supported code lengths as integers between 4 and 20, inclusive. You can specify either `supported_code_lengths` or `min_code_length`/`max_code_length`. - -*** - -### `min_code_length` - -Type: `integer` Required: No - -Minimum supported code length as an integer between 4 and 20, inclusive. You can specify either `min_code_length`/`max_code_length` or `supported_code_lengths`. - -*** - -### `max_code_length` - -Type: `integer` Required: No - -Maximum supported code length as an integer between 4 and 20, inclusive. You can specify either `min_code_length`/`max_code_length` or `supported_code_lengths`. - -## Return Type - -void diff --git a/docs/api-clients/access_codes/unmanaged/README.md b/docs/api-clients/access_codes/unmanaged/README.md deleted file mode 100644 index e69de29bb..000000000 diff --git a/docs/api-clients/access_codes/unmanaged/convert_to_managed.md b/docs/api-clients/access_codes/unmanaged/convert_to_managed.md deleted file mode 100644 index 49cda7cbe..000000000 --- a/docs/api-clients/access_codes/unmanaged/convert_to_managed.md +++ /dev/null @@ -1,71 +0,0 @@ ---- -description: Convert an Unmanaged Access Code to Managed ---- - -# Convert an Unmanaged Access Code - -{% hint style="info" %} -Not all providers support unmanaged access codes. The following providers do not support unmanaged access codes: - -**Kwikset** -{% endhint %} - -An unmanaged access code has a limited set of operations that can be performed on it: view, delete, or convert to managed. Converting an unmanaged access code to a managed one allows it to be controlled with Seam, and have the full set of operations and lifecycle events available for it. Note that not all device providers support this operation. - -## Convert Unmanaged Access Code - -## Convert unmanaged access code - -`POST` `https://connect.getseam.com/access_codes/unmanaged/update` - -#### Request Body - -| Name | Type | Description | -| -------------------------------------------------- | ------ | ------------------------------------------------ | -| access\_code\_id\* | String | ID of Unmanaged Access Code | -| is\_managed\* | String | Set to true to manage the access code with Seam. | - -{% tabs %} -{% tab title="200: OK " %} -```javascript -{ - "ok": true -} -``` -{% endtab %} - -{% tab title="400: Bad Request " %} -```javascript -{ - "error": { - "type": "unsupported_device", - "message": "Converting unmanaged access codes to managed is not supported for this device", - "request_id": "32239a33-c0d5-435c-816b-4a9274a5e66d" - }, - "ok": false -} -``` -{% endtab %} -{% endtabs %} - -#### Code Example - -{% tabs %} -{% tab title="Javascript" %} -```typescript -await seam.accessCodes.unmanaged.update({ - access_code_id: "26d6138c-6524-4f3c-ac96-43cc3bea0a8d", - is_managed: true, -}); -``` -{% endtab %} - -{% tab title="PHP" %} -```php -$seam->access_codes->unmanaged->update( - access_code_id: '26d6138c-6524-4f3c-ac96-43cc3bea0a8d', - is_managed: true -); -``` -{% endtab %} -{% endtabs %} diff --git a/docs/api-clients/access_codes/unmanaged/delete.md b/docs/api-clients/access_codes/unmanaged/delete.md deleted file mode 100644 index 42804581b..000000000 --- a/docs/api-clients/access_codes/unmanaged/delete.md +++ /dev/null @@ -1,51 +0,0 @@ ---- -description: Delete an Unmanaged Access Code of a Device using its Access Code ID ---- - -# Delete an Unmanaged Access Code - -`DELETE` `https://connect.getseam.com/access_codes/unmanaged/delete` - -## Request - -### Request Parameters - -| Name | Type | Description | -| -------------------------------------------------- | ------ | ---------------------- | -| access\_code\_id\* | String | ID of the access code. | - -### Sample Request - -{% tabs %} -{% tab title="JavaScript" %} -```javascript -await seam.accessCodes.unmanaged.delete({ - access_code_id: "a9f662a7-44fb-4b91-b7a8-22c0f996bfc1", -}); -``` -{% endtab %} - -{% tab title="PHP" %} -```php -$seam->access_codes->unmanaged->delete( - access_code_id: '26d6138c-6524-4f3c-ac96-43cc3bea0a8d', -); -``` -{% endtab %} -{% endtabs %} - -## 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. - -### **Sample Response** - -{% tabs %} -{% tab title="JSON" %} -```json -{ - "ok": true -} -``` -{% endtab %} -{% endtabs %} diff --git a/docs/api-clients/access_codes/unmanaged/get.md b/docs/api-clients/access_codes/unmanaged/get.md deleted file mode 100644 index b8bc15823..000000000 --- a/docs/api-clients/access_codes/unmanaged/get.md +++ /dev/null @@ -1,121 +0,0 @@ ---- -description: Get an Unmanaged Access Code of a Device by its Access Code ID ---- - -{% hint style="info" %} -Not all providers support unmanaged access codes. The following providers do not support unmanaged access codes: - -**Kwikset** -{% endhint %} - -# Get an Access Code - -{% swagger method="get" path="/access_codes/unmanaged/get" baseUrl="https://connect.getseam.com" summary="Get an Unmanaged Access Code" %} -{% swagger-description %} - -{% endswagger-description %} - -{% swagger-parameter in="query" name="access_code_id" required="true" %} - -{% endswagger-parameter %} - -{% swagger-response status="200: OK" description="" %} - -```javascript -{ - "access_code": { - "code": "1988", - "type": "ongoing", - "status": "set", - "created_at": "2022-08-26T12:50:17.858Z", - "access_code_id": "26d6138c-6524-4f3c-ac96-43cc3bea0a8d", - }, - "ok": true -} -``` - -{% endswagger-response %} - -{% swagger-response status="404: Not Found" description="" %} - -```javascript -{ - "error": { - "type": "access_code_not_found", - "message": "Could not find an access_code with device_id or access_code_id", - "request_id": "bf6643a3-a102-4f3b-b4c3-bd8cd1119ba2" - }, - "ok": false -} -``` - -{% endswagger-response %} -{% endswagger %} - -### Code Example - -{% tabs %} -{% tab title="Ruby" %} - -```ruby -seam.access_codes.unmanaged.get(access_code_id: "123e4567-e89b-12d3-a456-426614174000") - -# -``` - -{% endtab %} - -{% tab title="Python" %} - -```python -seam.access_codes.unmanaged.get("26d6138c-6524-4f3c-ac96-43cc3bea0a8d") - -# AccessCode( -# access_code_id='26d6138c-6524-4f3c-ac96-43cc3bea0a8d', -# type='ongoing', -# code='1988', -# starts_at=None, -# ends_at=None, -# name='', -# status='setting' -# ) -# -``` - -{% endtab %} -{% endtabs %} - -### Parameters - -| `access_code_id` | type: string |


ID of the Access Code

| -| ---------------- | ------------ | -------------------------------- | - -### 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 - -{% tabs %} -{% tab title="JSON" %} - -```json -{ - "access_code": { - "code": "1988", - "type": "ongoing", - "status": "set", - "created_at": "2022-08-26T12:50:17.858Z", - "access_code_id": "26d6138c-6524-4f3c-ac96-43cc3bea0a8d" - }, - "ok": true -} -``` - -{% endtab %} -{% endtabs %} diff --git a/docs/api-clients/access_codes/unmanaged/list.md b/docs/api-clients/access_codes/unmanaged/list.md deleted file mode 100644 index 8144fc341..000000000 --- a/docs/api-clients/access_codes/unmanaged/list.md +++ /dev/null @@ -1,134 +0,0 @@ ---- -description: Get all unmanaged access codes ---- - -# List Unmanaged Access Codes - -Returns a list of all [unmanaged access codes](../../../products/smart-locks/access-codes/migrating-existing-access-codes.md#unmanaged-access-codes) for a device. - -The [guide to migrating existing access codes](../../../products/smart-locks/access-codes/migrating-existing-access-codes.md) provides an overview of the difference between managed and unmanaged access codes. - -{% hint style="info" %} -Not all providers support unmanaged access codes. The following providers do not support unmanaged access codes: - -[Kwikset](../../../device-guides/kwikset-locks.md) -{% endhint %} - -{% swagger src="https://connect.getseam.com/openapi.json" path="/access_codes/unmanaged/list" method="post" %} -[https://connect.getseam.com/openapi.json](https://connect.getseam.com/openapi.json) -{% endswagger %} - -*** - -## Request - -Filter the list of returned unmanaged access codes by device ID. You can also filter by user identifier key. - -### Request Body Parameters - -
ParameterTypeDescription
device_idString (UUID)
Required		ID of the devices for which to retrieve unmanaged access codes.
user_identifier_keyString
Optional		Your own internal user ID for the user by which to filter unmanaged access codes.
- -## Sample Request - -{% tabs %} -{% tab title="Python" %} -```python -seam.access_codes.unmanaged.list( - device_id="11111111-1111-1111-1111-444444444444" -) - -# [AccessCode( -# access_code_id='26d6138c-6524-4f3c-ac96-43cc3bea0a8d', -# type='ongoing', -# code='1988', -# name='Code 1', -# status='set' -# ) -# ] -``` -{% endtab %} - -{% tab title="cURL (bash)" %} -```bash -# Use GET or POST. -curl -X 'GET' \ - 'https://connect.getseam.com/access_codes/unmanaged/list' \ - -H 'accept: application/json' \ - -H 'Authorization: Bearer ${API_KEY}' \ - -H 'Content-Type: application/json' \ - -d '{ - "device_id": "11111111-1111-1111-1111-444444444444" - }' -``` -{% endtab %} - -{% tab title="JavaScript" %} -```javascript -await seam.accessCodes.unmanaged.list({ - device_id: "11111111-1111-1111-1111-444444444444" -}); - -/* -[ - { - code: '1988', - name: 'Code 1', - status: 'set', - created_at: '2022-08-26T12:50:17.858Z', - access_code_id: '26d6138c-6524-4f3c-ac96-43cc3bea0a8d' - } -] -*/ -``` -{% endtab %} - -{% tab title="PHP" %} -```php -$seam->access_codes->unmanaged->list( - device_id: '11111111-1111-1111-1111-444444444444', -); -``` -{% endtab %} - -{% tab title="Ruby" %} -```ruby -seam.access_codes.unmanaged.list( - device_id: "123e4567-e89b-12d3-a456-426614174000" -) - -# [] -``` -{% endtab %} -{% endtabs %} - -*** - -## Response - -Returns an `access_codes` array, in which each returned `access_code` contains the set of applicable access code properties. For details, see [Access Codes](../). - -### Sample Response - -{% tabs %} -{% tab title="JSON" %} -```json -{ - "access_codes": [ - { - "code": "1988", - "name": "Code 1", - "status": "set", - "created_at": "2022-08-26T12:50:17.858Z", - "access_code_id": "26d6138c-6524-4f3c-ac96-43cc3bea0a8d" - }, - ... - ], - "ok": true -} -``` -{% endtab %} -{% endtabs %} diff --git a/docs/api-clients/access_codes/update-multiple-linked-access-codes.md b/docs/api-clients/access_codes/update-multiple-linked-access-codes.md deleted file mode 100644 index fa4c23a5e..000000000 --- a/docs/api-clients/access_codes/update-multiple-linked-access-codes.md +++ /dev/null @@ -1,238 +0,0 @@ ---- -description: >- - Update the starting and ending times for a set of linked access codes across - multiple devices. ---- - -# Update Multiple Linked Access Codes - -``` -POST /access_codes/update ⇒ void -``` - -Updates the `starts_at` and `ends_at` timestamps of a specified group of [access codes](../../products/smart-locks/access-codes/) linked by a `common_code_key`, across multiple devices. You create these groups of access codes using [`/access_codes/create_multiple`](../../api-clients/access\_codes/create\_multiple.md), and all these codes have the same PIN code. See also [Creating and Updating Multiple Linked Access Codes](../../capability-guides/smart-locks/access-codes/creating-and-updating-multiple-linked-access-codes.md). - -{% tabs %} -{% tab title="Python" %} -**Request:** - -```python -# Update the starting and ending times -# for a group of 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" -) -``` - -**Response:** - -``` -None -``` -{% endtab %} - -{% tab title="cURL (bash)" %} -**Request:** - -```sh -# Update the starting and ending times -# for a group of 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\" -}" -``` - -**Response:** - -```json -{ - "ok": true -} -``` -{% endtab %} - -{% tab title="JavaScript" %} -**Request:** - -```javascript -// Update the starting and ending times -// for a group of 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" -}); -``` - -**Response:** - -```json -void -``` -{% endtab %} - -{% tab title="Ruby" %} -**Request:** - -```ruby -# Update the starting and ending times -# for a group of 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" -) -``` - -**Response:** - -``` -void -``` -{% endtab %} - -{% tab title="PHP" %} -**Request:** - -```php -// Update the starting and ending times -// for a group of 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" -); -``` - -**Response:** - -```json -void -``` -{% endtab %} - -{% tab title="C#" %} -**Request:** - -```csharp -// Update the starting and ending times -// for a group of 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" -); -``` - -**Response:** - -```json -void -``` -{% endtab %} - -{% tab title="Java" %} -**Request:** - -```java -// Update the starting and ending times -// for a group of linked access codes, -// using the common_code_key to identify -// the group of access codes to update. -seam.accessCodes() - .updateMultiple(AccessCodesUpdateMultipleRequest.builder() - .commonCodeKey(commonCodeKey) - .startsAt("2024-11-15T12:00:00Z") - .endsAt("2024-11-17T15:00:00Z") - .build()); -``` - -**Response:** - -```json -void -``` -{% endtab %} - -{% tab title="Go" %} -**Request:** - -```go -// Update the starting and ending times -// for a group of linked access codes, -// using the common_code_key to identify -// the group of access codes to update. -client.AccessCodes.UpdateMultiple( - context.Background(), - &api.AccessCodesUpdateMultipleRequest{ - CommonCodeKey: commonCodeKey, - StartsAt: api.String("2024-11-15T12:00:00Z"), - EndsAt: api.String("2024-11-17T15:00:00Z"), - }, -) - -if uErr != nil { - return uErr -} - -return nil -``` - -**Response:** - -```json -void -``` -{% endtab %} -{% endtabs %} - -## Request Parameters - -### `common_code_key` - -Type: `string` Required: Yes - -Key that links the group of access codes, assigned on creation by `/access_codes/create_multiple`. - -*** - -### `starts_as` - -Type: `string` Required: No - -Date and time at which the validity of the linked access codes starts, in [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) format. - -*** - -### `ends_at` - -Type: `string` Required: No - -Date and time at which the validity of the linked access codes 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`. - -*** - -## Return Type - -void diff --git a/docs/api-clients/access_codes/update.md b/docs/api-clients/access_codes/update.md deleted file mode 100644 index 183502623..000000000 --- a/docs/api-clients/access_codes/update.md +++ /dev/null @@ -1,181 +0,0 @@ ---- -description: Update an Access Code for a Device by its ID ---- - -# Update an Access Code - -{% swagger method="put" path="/access_codes/update" baseUrl="https://connect.getseam.com" summary="Update an Access Code" %} -{% swagger-description %} - -{% endswagger-description %} - -{% swagger-parameter in="body" name="access_code_id" required="true" %} -Access code id -{% endswagger-parameter %} - -{% swagger-parameter in="body" name="name" required="false" %} -Access code name -{% endswagger-parameter %} - -{% swagger-parameter in="body" name="code" required="false" %} -Access code -{% endswagger-parameter %} - -{% swagger-parameter in="body" name="starts_at" %} - -{% endswagger-parameter %} - -{% swagger-parameter in="body" name="ends_at" %} - -{% endswagger-parameter %} - -{% swagger-response status="200: OK" description="Successfully update access code" %} -```javascript -{ - "action_attempt": { - "status": "pending", - "action_type": "UPDATE_ACCESS_CODE", - "action_attempt_id": "bbb8a07d-a91d-4564-b002-8172f7cdadc4", - "result": null, - "error": null - }, - "ok": true -} -``` -{% endswagger-response %} - -{% swagger-response status="400: Bad Request" description="" %} -```javascript -{ - "error": { - "type": "invalid_input", - "message": "Required for provided \"access_code_id\"", - "validation_errors": { - "_errors": [], - "access_code_id": { - "_errors": [ - "Required" - ] - } - }, - "request_id": "ec56770c-b45e-4faa-9614-d987d793d684" - }, - "ok": false -} -``` -{% endswagger-response %} - -{% swagger-response status="404: Not Found" description="" %} -```javascript -{ - "error": { - "type": "device_not_found", - "message": "Device not found", - "request_id": "7330bdd3-b263-4a5d-8282-9a64012ccbd4" - }, - "ok": false -} -``` -{% endswagger-response %} -{% endswagger %} - -### Code Example - -{% tabs %} -{% tab title="Ruby" %} -```ruby -seam.access_codes.update( - access_code_id: "123e4567-e89b-12d3-a456-426614174000", - code: "1112", - name: 'New name' -) - -# { -# "code"=>"1112", -# "name"=>"New name", -# "type"=>"ongoing", -# "status"=>"setting", -# "created_at"=>"2022-07-06T16:01:18.063Z", -# "access_code_id"=>"123e4567-e89b-12d3-a456-426614174000"}}> -``` -{% endtab %} - -{% tab title="Javascript" %} -```javascript -await seam.accessCodes.update({ - access_code_id: "cd706212-ec14-499a-abd5-ba04123ee65e", - code: "1111" -}); - -/* -{ - code: '1111', - name: 'My first code', - type: 'ongoing', - status: 'setting', - created_at: '2022-08-31T17:27:33.324Z', - access_code_id: 'cd706212-ec14-499a-abd5-ba04123ee65e' -} -*/ -``` -{% endtab %} - -{% tab title="Python" %} -```python -seam.access_codes.update( -"cd706212-ec14-499a-abd5-ba04123ee65e", -None, None, 4321) - -# AccessCode( -# access_code_id='cd706212-ec14-499a-abd5-ba04123ee65e', -# type='ongoing', -# code='4321', -# starts_at=None, -# ends_at=None, -# name='My first code', -# status='setting' -# ) - -``` -{% endtab %} -{% endtabs %} - -### Parameters - -| `access_code_id` | type:string | ID of the Access Code | -| ---------------- | ------------------------------- | --------------------------- | -| `device_id` |

type: string
Optional

| ID of the Device | -| `name` |

type: string
Optional

| Name of Access Code | -| `starts_at` |

type: string
Optional

| From when is the code valid | -| `ends_at` |

type: string
Optional

| Code expiry | -| `code` |

type: string
Optional

| Access code of Device | - -### - -### 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 - -{% tabs %} -{% tab title="JSON" %} -```json -{ - "action_attempt": { - "status": "pending", - "action_type": "UPDATE_ACCESS_CODE", - "action_attempt_id": "bbb8a07d-a91d-4564-b002-8172f7cdadc4", - "result": null, - "error": null - }, - "ok": true -} -``` -{% endtab %} -{% endtabs %} diff --git a/docs/api/_blueprint.json b/docs/api/_blueprint.json index b53873430..1218b2036 100644 --- a/docs/api/_blueprint.json +++ b/docs/api/_blueprint.json @@ -288,7 +288,7 @@ }, { "name": "use_backup_access_code_pool", - "description": "Indicates whether to use a [backup access code pool](https://docs.seam.co/latest/core-concepts/access-codes#backup-access-codes) provided by Seam. If `true`, you can use [`/access_codes/pull_backup_access_code`](../api-clients/access_codes/pull_backup_access_code.md).", + "description": "Indicates whether to use a [backup access code pool](https://docs.seam.co/latest/core-concepts/access-codes#backup-access-codes) provided by Seam. If `true`, you can use [`/access_codes/pull_backup_access_code`](https://docs.seam.co/latest/api-clients/access_codes/pull_backup_access_code).", "isRequired": false, "isDeprecated": false, "deprecationMessage": "", @@ -617,7 +617,7 @@ }, { "name": "use_backup_access_code_pool", - "description": "Indicates whether to use a [backup access code pool](https://docs.seam.co/latest/core-concepts/access-codes#backup-access-codes) provided by Seam. If `true`, you can use [`/access_codes/pull_backup_access_code`](../api-clients/access_codes/pull_backup_access_code.md).", + "description": "Indicates whether to use a [backup access code pool](https://docs.seam.co/latest/core-concepts/access-codes#backup-access-codes) provided by Seam. If `true`, you can use [`/access_codes/pull_backup_access_code`](https://docs.seam.co/latest/api-clients/access_codes/pull_backup_access_code).", "isRequired": false, "isDeprecated": false, "deprecationMessage": "", @@ -1436,7 +1436,7 @@ }, { "name": "use_backup_access_code_pool", - "description": "Indicates whether to use a [backup access code pool](https://docs.seam.co/latest/core-concepts/access-codes#backup-access-codes) provided by Seam. If `true`, you can use [`/access_codes/pull_backup_access_code`](../api-clients/access_codes/pull_backup_access_code.md).", + "description": "Indicates whether to use a [backup access code pool](https://docs.seam.co/latest/core-concepts/access-codes#backup-access-codes) provided by Seam. If `true`, you can use [`/access_codes/pull_backup_access_code`](https://docs.seam.co/latest/api-clients/access_codes/pull_backup_access_code).", "isRequired": false, "isDeprecated": false, "deprecationMessage": "", diff --git a/docs/api/access_codes/create.md b/docs/api/access_codes/create.md index 60b4b121d..9b985b20c 100644 --- a/docs/api/access_codes/create.md +++ b/docs/api/access_codes/create.md @@ -112,7 +112,7 @@ Date and time at which the validity of the new access code starts, in [ISO 8601] **`use_backup_access_code_pool`** *Boolean* -Indicates whether to use a [backup access code pool](https://docs.seam.co/latest/core-concepts/access-codes#backup-access-codes) provided by Seam. If `true`, you can use [`/access_codes/pull_backup_access_code`](../../api-clients/access_codes/pull_backup_access_code.md). +Indicates whether to use a [backup access code pool](https://docs.seam.co/latest/core-concepts/access-codes#backup-access-codes) provided by Seam. If `true`, you can use [`/access_codes/pull_backup_access_code`](https://docs.seam.co/latest/api-clients/access_codes/pull_backup_access_code). --- diff --git a/docs/api/access_codes/create_multiple.md b/docs/api/access_codes/create_multiple.md index f96f6bde8..fe732e4a0 100644 --- a/docs/api/access_codes/create_multiple.md +++ b/docs/api/access_codes/create_multiple.md @@ -120,7 +120,7 @@ Date and time at which the validity of the new access code starts, in [ISO 8601] **`use_backup_access_code_pool`** *Boolean* -Indicates whether to use a [backup access code pool](https://docs.seam.co/latest/core-concepts/access-codes#backup-access-codes) provided by Seam. If `true`, you can use [`/access_codes/pull_backup_access_code`](../../api-clients/access_codes/pull_backup_access_code.md). +Indicates whether to use a [backup access code pool](https://docs.seam.co/latest/core-concepts/access-codes#backup-access-codes) provided by Seam. If `true`, you can use [`/access_codes/pull_backup_access_code`](https://docs.seam.co/latest/api-clients/access_codes/pull_backup_access_code). --- diff --git a/docs/api/access_codes/update.md b/docs/api/access_codes/update.md index e71215988..040b7e95b 100644 --- a/docs/api/access_codes/update.md +++ b/docs/api/access_codes/update.md @@ -126,7 +126,7 @@ Type to which you want to convert the access code. To convert a time-bound acces **`use_backup_access_code_pool`** *Boolean* -Indicates whether to use a [backup access code pool](https://docs.seam.co/latest/core-concepts/access-codes#backup-access-codes) provided by Seam. If `true`, you can use [`/access_codes/pull_backup_access_code`](../../api-clients/access_codes/pull_backup_access_code.md). +Indicates whether to use a [backup access code pool](https://docs.seam.co/latest/core-concepts/access-codes#backup-access-codes) provided by Seam. If `true`, you can use [`/access_codes/pull_backup_access_code`](https://docs.seam.co/latest/api-clients/access_codes/pull_backup_access_code). --- diff --git a/docs/capability-guides/smart-locks/access-codes/creating-access-codes/README.md b/docs/capability-guides/smart-locks/access-codes/creating-access-codes/README.md index a44ccfb7c..1468d3a48 100644 --- a/docs/capability-guides/smart-locks/access-codes/creating-access-codes/README.md +++ b/docs/capability-guides/smart-locks/access-codes/creating-access-codes/README.md @@ -19,11 +19,11 @@ layout: ## Overview -This guide explains how to create online access codes on an online smart lock. With the [Access Codes](../../../../api-clients/access_codes/) API, generate PIN codes on a door lock and share it with visitors, allowing them keyless access. +This guide explains how to create online access codes on an online smart lock. With the [Access Codes](../../../../api/access_codes/) API, generate PIN codes on a door lock and share it with visitors, allowing them keyless access. Seam supports programming two types of online access codes for online door locks: -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-clients/access_codes/delete.md) endpoint. +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.md) 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. {% hint style="info" %} @@ -232,7 +232,7 @@ Ongoing online access codes are ideal for long-term users that wish to keep the ### 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-clients/access_codes/create.md). Assign an optional `name` to the access code for easier identification within the [Seam Console](https://console.seam.co) and smart lock app. +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.md). 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](../../../../products/smart-locks/access-codes/access-code-requirements-for-door-locks.md) to understand any requirements specific to the door lock. @@ -550,7 +550,7 @@ There are two methods to verify that an ongoing access code has been set on the ### **Polling Method** -Use the `access_code` reference returned by the create function to call the [Get Access Code](../../../../api-clients/access_codes/get/) function. A basic implementation would involve polling this endpoint until the `status` of the access code updates to `set`. +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"](../../../../products/smart-locks/access-codes/troubleshooting-access-code-issues.md) for further guidance. @@ -577,7 +577,7 @@ Time-bound online access codes are suitable for temporary access, like guest vis ### 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-clients/access_codes/create.md) endpoint. +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.md) 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. @@ -936,7 +936,7 @@ There are two methods to verify that an time-bound access code has been set on t ### **Polling Method** -Use the `access_code` reference returned by the create function to call the [Get Access Code](../../../../api-clients/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`. +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](../../../../products/smart-locks/access-codes/troubleshooting-access-code-issues.md) for assistance. diff --git a/docs/device-and-system-integration-guides/smartthings-hubs-+-smart-locks.md b/docs/device-and-system-integration-guides/smartthings-hubs-+-smart-locks.md index 98f6fa603..bd6c720e1 100644 --- a/docs/device-and-system-integration-guides/smartthings-hubs-+-smart-locks.md +++ b/docs/device-and-system-integration-guides/smartthings-hubs-+-smart-locks.md @@ -49,7 +49,7 @@ Note the following SmartThings-specific features: ### Reporting Access Code Length Constraints -For SmartThings-connected devices, you can report the set of supported access code lengths or the minimum and maximum supported code lengths. For details, see [Report Device Access Code Constraints](../api-clients/access_codes/report-device-access-code-constraints.md). +For SmartThings-connected devices, you can report the set of supported access code lengths or the minimum and maximum supported code lengths. For details, see [Report Device Access Code Constraints](../api/access_codes/report-device-access-code-constraints.md). *** diff --git a/docs/device-guides/implementing-robust-access-code-management-for-guests.md b/docs/device-guides/implementing-robust-access-code-management-for-guests.md index e915bda6b..af2688065 100644 --- a/docs/device-guides/implementing-robust-access-code-management-for-guests.md +++ b/docs/device-guides/implementing-robust-access-code-management-for-guests.md @@ -46,7 +46,7 @@ Seam's backup access code pool, we automatically make sure all backup access cod are healthy, ready for immediate usage, replaced after every use, and automatically removed when a reservation ends. -Seam's official backup access code pool can be enabled by adding `use_backup_access_code_pool: true` to any [`/access_codes/create` API request](https://docs.seam.co/latest/api-clients/access_codes/create). You can then retrieve access codes using [`/access_codes/pull_backup_access_code`](https://docs.seam.co/latest/api-clients/access_codes/pull_backup_access_code). +Seam's official backup access code pool can be enabled by adding `use_backup_access_code_pool: true` to any [`/access_codes/create` API request](https://docs.seam.co/latest/api/access_codes/create). You can then retrieve access codes using [`/access_codes/pull_backup_access_code`](https://docs.seam.co/latest/api/access_codes/pull_backup_access_code). {% tabs %} diff --git a/docs/products/smart-locks/access-codes/backup-access-codes.md b/docs/products/smart-locks/access-codes/backup-access-codes.md index cf14cebc7..730105bcc 100644 --- a/docs/products/smart-locks/access-codes/backup-access-codes.md +++ b/docs/products/smart-locks/access-codes/backup-access-codes.md @@ -516,7 +516,7 @@ 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-clients/access_codes/get/) or [List Access Codes](../../../api/access_codes/list.md). If the backup code pool has been exhausted, this property returns `false`. +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.md). If the backup code pool has been exhausted, this property returns `false`. {% hint style="info" %} Note that we only support pulling backup codes for `time_bound` codes at this time. diff --git a/docs/products/smart-locks/access-codes/modifying-access-codes.md b/docs/products/smart-locks/access-codes/modifying-access-codes.md index b7a087be2..80d0a629b 100644 --- a/docs/products/smart-locks/access-codes/modifying-access-codes.md +++ b/docs/products/smart-locks/access-codes/modifying-access-codes.md @@ -200,7 +200,7 @@ There are two methods to verify that a permanent access code has been set on the **Polling Method** -Utilize the `access_code_id` returned in the response from the create endpoint to invoke the [Get Access Code](../../../api-clients/access_codes/get/) endpoint. A basic implementation would involve polling this endpoint until the `status` of the access code updates to `set`. +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"](troubleshooting-access-code-issues.md) for further guidance. @@ -216,7 +216,7 @@ There are two methods to verify that a time-bound access code has been set on th **Polling Method** -Use the `access_code_id` provided in the response from the create endpoint to call the [Get Access Code](../../../api-clients/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`. +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](troubleshooting-access-code-issues.md) for assistance. diff --git a/docs/products/smart-locks/access-codes/retrieving-access-codes.md b/docs/products/smart-locks/access-codes/retrieving-access-codes.md index b4c0944a8..21826ba50 100644 --- a/docs/products/smart-locks/access-codes/retrieving-access-codes.md +++ b/docs/products/smart-locks/access-codes/retrieving-access-codes.md @@ -709,7 +709,7 @@ System.out.println(accessCodes); ## Retrieving Individual Access Codes -To retrieve a specific access code, include the desired `access_code_id` in the [Get Access Code](../../../api-clients/access_codes/get/) request. +To retrieve a specific access code, include the desired `access_code_id` in the [Get Access Code](../../../api/access_codes/get/) request. {% tabs %} {% tab title="Python" %} diff --git a/docs/products/smart-locks/access-codes/troubleshooting-access-code-issues.md b/docs/products/smart-locks/access-codes/troubleshooting-access-code-issues.md index 4fb72b627..6c9ffb742 100644 --- a/docs/products/smart-locks/access-codes/troubleshooting-access-code-issues.md +++ b/docs/products/smart-locks/access-codes/troubleshooting-access-code-issues.md @@ -29,7 +29,7 @@ If the device or connected account associated with an access code has an error, ## 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-clients/access_codes/get/) or [List Access Codes](../../../api/access_codes/list.md) 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](troubleshooting-access-code-issues.md#suggested-access-code-remedies) for next steps. +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.md) 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](troubleshooting-access-code-issues.md#suggested-access-code-remedies) for next steps. {% tabs %} {% tab title="Python" %}