Visitor Passes

Visitor Passes are implemented through the Keychains API, which supports different access types and schedules. These are typically used for:

• Deliveries
• Guests and appointments
• Self-guided tours
• Maintenance access

🧑 Who Can Issue Passes?

Passes are associated with a tenant or unit and grant access to specific doors or devices.

🔑 Keychain Types for Visitor Access

🚀 Creating a Visitor Pass

To create a visitor pass, use the corresponding endpoint below and provide required access details.

🔗 Endpoints

• POST /v4/keychains/custom
• POST /v4/keychains/one_time
• POST /v4/keychains/delivery_pass
• POST /v4/keychains/recurring

📝 Sample Request (One-Time Pass)

{
  "keychain": {
    "name": "Visitor - Electrician",
    "tenant_id": 377389742,
    "starts_at": "2025-05-01T13:00:00Z",
    "ends_at": "2025-05-01T15:00:00Z",
    "recipients": ["guest@example.com", "+12345678900"],
    "access_point_ids": [842395203],
    "device_ids": [708353660]
  }
}

🔐

You must specify either tenant_id or unit_id and provide access control targets (access points or devices).

✉️ How Visitors Receive Passes

Upon creation, visitors typically receive their access credentials via:

• Email with a virtual key link
• SMS with a secure URL (if a phone number is provided)

These links allow guests to use their visitor pass to unlock doors from their smartphone without needing to install an app.

🔒

Custom Delivery Option:

If you provide an emptyrecipients array, no automatic email or SMS will be sent. This is useful if you want to deliver the PIN code or QR code using your own system (e.g., in-app message, branded email, or printed label)

In this case, you can retrieve the QR code and PIN via the Virtual Keys API

🔎 Listing Visitor Passes

Use the Keychains index endpoint to retrieve existing passes:

GET /v4/keychains

Supports filters such as:

• q[tenant_id_eq]
• q[starts_at_gteq], q[ends_at_lteq]
• q[name_start] for label filtering

❌ Deleting a Pass

To revoke access immediately:

DELETE /v4/keychains/{id}

This deactivates all virtual keys associated with the keychain.

📦 Response Sample

{
  "data": {
    "id": 940364946,
    "name": "DoorDash",
    "type": "delivery_pass",
    "starts_at": "2025-04-24T10:24:38Z",
    "ends_at": "2025-05-24T10:24:38Z",
    "virtual_key_ids": [1035872621],
    "access_point_ids": [22177636],
    "device_ids": [708353660]
  }
}

🧠 Use Cases

• Automated guest scheduling (e.g., calendaring integrations)
• Self-guided tours for prospective tenants
• Delivery pass generation from package tracking systems
• Contractor access via property management platforms

✅ Best Practices

• Validate access windows: Always ensure starts_at and ends_at are in the future and follow logical order (start < end).

• Use correct time zones: All timestamps (starts_at, ends_at, time_from, time_to) must be provided in UTC.
  If you're working with users in a specific building time zone, convert to UTC before making API calls. You can retrieve the building’s time zone using:

  GET /v4/buildings/{building_id} → time_zone field (e.g., "America/New_York")

  Example:

  JavaScript

  // Convert local time to UTC using moment-timezone
  moment.tz("2025-05-01 09:00", "America/New_York").utc().format()

• Send tenant confirmations: Notify tenants via email or in-app when a visitor pass is created on their behalf.

• Use delivery passes for limited-use scenarios: These are optimized for brief, one-time access with minimal configuration.

• Revoke access when needed: Deleting a keychain immediately deactivates its associated visitor key.