Skip to main content
Programming access codes involves asynchronous processes because Seam must communicate with smart devices and third-party applications outside your main application. Seam tracks each access code through its lifecycle for you. You can read an access code’s lifecycle from the access code object:
  • display_status — a human-readable label for where the code sits in its lifecycle, for example Active, Issuing, or Waiting to issue. Show it to users, but do not branch on it in code — the wording can change at any time.
  • pending_mutations — the changes Seam is actively pushing to the device. Each entry carries a mutation_code: creating, deferring_creation, updating_code, updating_name, updating_time_frame, or deleting. An empty list means the device reflects the code’s requested state.
  • errors and warnings — problems Seam has encountered while working on the code. See Troubleshooting Access Code Issues.
  • starts_at and ends_at — the code’s intended active window. Codes without them are ongoing.
The access code status property is deprecated and will be removed. Do not build logic on it. Instead, read pending_mutations, errors, warnings, starts_at, and ends_at.

​
Lifecycle Phases

A typical time-bound access code moves through these phases: Waiting to issue → Issuing → Upcoming → Active → Deleting → Deleted An ongoing code skips the schedule-related phases and goes straight from Issuing to Active. Errors and warnings can occur at any point — see Errors and Warnings below.

​
Waiting to Issue

display_status: "Waiting to issue" · pending mutation: deferring_creation For natively-scheduled codes, Seam deliberately waits to program the code onto the device until close to the starts_at time. The deferring_creation pending mutation’s scheduled_at field tells you when Seam plans to begin programming.

​
Issuing

display_status: "Issuing" · pending mutation: creating Seam is actively programming the code onto the device. When programming succeeds, the mutation clears and Seam emits access_code.issued. If issuance is delayed: Seam sets the delay_in_issuing warning, emits access_code.delay_in_issuing, and keeps retrying. Notify the device owner to check the device and connected account. If the issue persists as starts_at approaches, pull a backup access code. If issuance fails: Seam sets the failed_to_issue error and emits access_code.failed_to_issue. The recipient may be locked out — pull a backup access code or arrange alternative access. Seam keeps retrying and clears the error if a retry succeeds.

​
Upcoming

display_status: "Upcoming" The code has been programmed onto the device but its starts_at time has not arrived yet. For natively-scheduled codes, Seam preloads the code onto the device ahead of the starts_at time. A preloaded code has no pending mutations; it waits on the device for its activation time.

​
Active

display_status: "Active" The code works on the device: no pending mutations, no errors, and the current time is within the code’s window (or the code is ongoing). When you receive access_code.issued, you can share the code with its intended recipient.

​
Updating

display_status: "Updating" · pending mutation: updating_code, updating_name, or updating_time_frame You requested a change to the code’s PIN, name, or time frame (see Modifying Access Codes), and Seam is pushing it to the device.
  • access_code.mutations_requested fires at request time, before the change reaches the device.
  • When the device confirms the change, the pending mutation clears and Seam emits the matching event (access_code.code_changed, access_code.name_changed, or access_code.time_frame_changed), each carrying from and to values.
If the update fails: Seam sets the failed_to_update error and emits access_code.failed_to_update. The code on the device does not match its requested state, and the recipient’s access may not work as expected. Pull a backup access code or arrange alternative access. Seam keeps retrying and clears the error once the update is applied.

​
Deleting

display_status: "Deleting" · pending mutation: deleting The code is being taken off the device — because you deleted it or because its ends_at time was reached. If deletion fails: Seam sets the failed_to_delete error and emits access_code.failed_to_delete. The code may still grant access past its intended window. Notify the device owner. Seam keeps retrying and clears the error once the code is off the device.

​
Deleted

Once the code is off the device, Seam currently deletes the access code object from its database. Retrieving it afterward returns a 404.
Seam is changing this behavior so access codes won’t return a 404 unless explicitly deleted by the API user.

​
Errors and Warnings

Errors and warnings can appear alongside any phase. They show up on display_status when they represent the most important thing a user needs to know about the code.
Seam always keeps trying when recovery is possible. Even after a failure event, Seam may emit a success event (such as access_code.issued) if a retry succeeds. Your application should be prepared to handle both.

​
Lifecycle Events Reference

Listen for these events on your webhook. See the access code events reference for full payloads.
These events supersede the deprecated device-oriented events such as access_code.set_on_device. See Migrating to Access Code Lifecycle Events.

​
Next Steps