---
title: "Pull a Backup Access Code"
method: POST
path: "/access_codes/pull_backup_access_code"
tags: ["/access_codes"]
---

# Pull a Backup Access Code

`POST /access_codes/pull_backup_access_code`

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

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

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

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

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

## Request body

- object
  - `access_code_id` string, uuid, required — ID of the access code for which you want to pull a backup access code.

## Response `200`

OK

- object
  - `access_code` AccessCode, required — Represents a smart lock [access code](/low-level-apis/smart-locks/access-codes). See the [access_code object](/api/access_codes/object).
    - `access_code_id` string, uuid, required — Unique identifier for the access code.
    - `code` string, nullable, required — Code used for access. Typically, a numeric or alphanumeric string.
    - `common_code_key` string, nullable, required — Unique identifier for a group of access codes that share the same code.
    - `created_at` string, date-time, required — Date and time at which the access code was created.
    - `device_id` string, uuid, required — Unique identifier for the device associated with the access code.
    - `dormakaba_oracode_metadata` object, nullable — Metadata for a dormakaba Oracode managed access code. Only present for access codes from dormakaba Oracode devices.
      - `is_cancellable` boolean — Indicates whether the stay can be cancelled via the Dormakaba Oracode API.
      - `is_early_checkin_able` boolean — Indicates whether early check-in is available for this stay.
      - `is_extendable` boolean — Indicates whether the stay can be extended via the Dormakaba Oracode API.
      - `is_overridable` boolean — Indicates whether the access code can be overridden. When false, the maximum number of overrides has been reached.
      - `site_name` string — Dormakaba Oracode site name associated with this access code.
      - `stay_id` number, float — Dormakaba Oracode stay ID associated with this access code.
      - `user_level_id` string — Dormakaba Oracode user level ID associated with this access code.
      - `user_level_name` string, nullable — Dormakaba Oracode user level name associated with this access code.
    - `ends_at` string, date-time, nullable — Date and time after which the time-bound access code becomes inactive.
    - `errors` object[], required — Errors associated with the [access code](/low-level-apis/smart-locks/access-codes).
      - `error_code` string — Error or warning code.
      - `message` string — Human-readable description.
      - `created_at` string, date-time — When this error or warning was generated.
    - `is_backup` boolean — Indicates whether the access code is a backup code.
    - `is_backup_access_code_available` boolean, required — Indicates whether a backup access code is available for use if the primary access code is lost or compromised.
    - `is_external_modification_allowed` boolean, required — Indicates whether changes to the access code from external sources are permitted.
    - `is_managed` true, required — Indicates whether Seam manages the access code.
    - `is_offline_access_code` boolean, required — Indicates whether the access code is intended for use in offline scenarios. If `true`, this code can be created on a device without a network connection.
    - `is_one_time_use` boolean, required — Indicates whether the access code can only be used once. If `true`, the code becomes invalid after the first use.
    - `is_scheduled_on_device` boolean — Indicates whether the code is set on the device according to a preconfigured schedule.
    - `is_waiting_for_code_assignment` boolean — Indicates whether the access code is waiting for a code assignment.
    - `name` string, nullable, required — Name of the access code. Enables administrators and users to identify the access code easily, especially when there are numerous access codes. Note that the name provided on Seam is used to identify the code on Seam and is not necessarily the name that will appear in the lock provider's app or on the device. This is because lock providers may have constraints on names, such as length, uniqueness, or characters that can be used. In addition, some lock providers may break down names into components such as `first_name` and `last_name`. To provide a consistent experience, Seam identifies the code on Seam by its name but may modify the name that appears on the lock provider's app or on the device. For example, Seam may add additional characters or truncate the name to meet provider constraints. To help your users identify codes set by Seam, Seam provides the name exactly as it appears on the lock provider's app or on the device as a separate property called `appearance`. This is an object with a `name` property and, optionally, `first_name` and `last_name` properties (for providers that break down a name into components).
    - `pending_mutations` union[], required — Collection of pending mutations for the access code. Indicates changes that Seam is in the process of pushing to the device.
      - union
        - object — Seam is in the process of setting an access code on the device.
          - `created_at` string, date-time, required — Date and time at which the mutation was created.
          - `message` string, required — Detailed description of the mutation.
          - `mutation_code` 'creating', required — Mutation code to indicate that Seam is in the process of setting an access code on the device.
        - object — Seam is waiting until closer to the access code's start time before programming it on the device.
          - `created_at` string, date-time, required — Date and time at which the mutation was created.
          - `message` string, required — Detailed description of the mutation.
          - `mutation_code` 'deferring_creation', required — Mutation code to indicate that Seam is waiting until closer to the access code's start time before programming it on the device.
          - `scheduled_at` string, date-time, required — Date and time at which Seam will attempt to program this access code on the device.
        - object — Seam is in the process of removing an access code from the device.
          - `created_at` string, date-time, required — Date and time at which the mutation was created.
          - `message` string, required — Detailed description of the mutation.
          - `mutation_code` 'deleting', required — Mutation code to indicate that Seam is in the process of removing an access code from the device.
        - object — Seam is in the process of pushing an updated PIN code to the device.
          - `created_at` string, date-time, required — Date and time at which the mutation was created.
          - `from` object, required — Previous code configuration.
            - `code` string, nullable, required — Previous PIN code.
          - `message` string, required — Detailed description of the mutation.
          - `mutation_code` 'updating_code', required — Mutation code to indicate that Seam is in the process of pushing an updated PIN code to the device.
          - `to` object, required — New code configuration.
            - `code` string, nullable, required — New PIN code.
        - object — Seam is in the process of pushing an updated access code name to the device.
          - `created_at` string, date-time, required — Date and time at which the mutation was created.
          - `from` object, required — Previous name configuration.
            - `name` string, nullable, required — Previous access code name.
          - `message` string, required — Detailed description of the mutation.
          - `mutation_code` 'updating_name', required — Mutation code to indicate that Seam is in the process of pushing an updated access code name to the device.
          - `to` object, required — New name configuration.
            - `name` string, nullable, required — New access code name.
        - object — Seam is in the process of pushing an updated time frame to the device.
          - `created_at` string, date-time, required — Date and time at which the mutation was created.
          - `from` object, required — Previous time frame configuration.
            - `ends_at` string, date-time, nullable, required — Previous end time for the access code.
            - `starts_at` string, date-time, nullable, required — Previous start time for the access code.
          - `message` string, required — Detailed description of the mutation.
          - `mutation_code` 'updating_time_frame', required — Mutation code to indicate that Seam is in the process of pushing updated access code time frame to the device.
          - `to` object, required — New time frame configuration.
            - `ends_at` string, date-time, nullable, required — New end time for the access code.
            - `starts_at` string, date-time, nullable, required — New start time for the access code.
    - `pulled_backup_access_code_id` string, uuid, nullable — Identifier of the pulled backup access code. Used to associate the pulled backup access code with the original access code.
    - `starts_at` string, date-time, nullable — Date and time at which the time-bound access code becomes active.
    - `status` 'setting' | 'set' | 'unset' | 'removing' | 'unknown', required — Current status of the access code within the operational lifecycle. Values are `setting`, a transitional phase that indicates that the code is being configured or activated; `set`, which indicates that the code is active and operational; `unset`, which indicates a deactivated or unused state, either before activation or after deliberate deactivation; `removing`, which indicates a transitional period in which the code is being deleted or made inactive; and `unknown`, which indicates an indeterminate state, due to reasons such as system errors or incomplete data, that highlights a potential need for system review or troubleshooting. See also [Lifecycle of Access Codes](/low-level-apis/smart-locks/access-codes/lifecycle-of-access-codes).
    - `type` 'time_bound' | 'ongoing', required — Type of the access code. `ongoing` access codes are active continuously until deactivated manually. `time_bound` access codes have a specific duration.
    - `warnings` object[], required — Warnings associated with the [access code](/low-level-apis/smart-locks/access-codes).
      - `error_code` string — Error or warning code.
      - `message` string — Human-readable description.
      - `created_at` string, date-time — When this error or warning was generated.
    - `workspace_id` string, uuid, required — Unique identifier for the Seam workspace associated with the access code.

## Other responses

- `400` — Bad Request
- `401` — Unauthorized

---

[API](https://skmtc.net/seam/apis/seam-connect.md) · [All operations](https://skmtc.net/seam/apis/seam-connect/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/seam/seam-connect/versions/00c35395ce12/schema)