Supported use cases

This section outlines common workflows supported via the ButterflyMX Public API, including access control, visitor management, and tenant operations.

🟢 Grant Access (Swipe to Open)

Use the /v4/door_release_requests endpoint to programmatically open doors.

  • Supported Resources:
    • access_point_id — for doors or groups of doors
    • device_id — for smart locks or entry devices
  • Permissions:
    • Tenants can grant access to their own assigned access points
      • Use scope=self to restrict results to the authenticated tenant
    • Admins can grant access to any access point in buildings they manage

📘 See also: Access Points, Devices, Tenants


🟡 Visitor Passes

Visitor access can be granted through virtual keys via the Keychains API.

  • Types:
    • custom (scheduled)
    • one_time
    • recurring
    • delivery_pass
  • Who can use it:
    • Tenants (for their units)
    • Admins (for any tenant)

📘 Endpoints:

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

🔍 Access and Call Logs

Query historical data on entry events and video calls.

  • Access Logs:
    GET /v4/buildings/{building_id}/access_logs
  • Call Logs:
    GET /v4/buildings/{building_id}/calls

Optional filters include date ranges, unit labels, or release methods like "swipe to open" or "QR code".


📹 Video Calls

Call events can be queried, but real-time video and communication functionality is managed through a separate SDK.

📘 For live interaction and media handling, see the ButterflyMX SDK on GitHub.

  • Preference Updates: Tenants can update call/contact preferences (coming soon).

👤 Tenant Profile Management

Tenants can view and manage their profiles.

  • Fields Available:

    • Full name
    • Email address
    • Phone number
  • PIN Access Tool Management:

    • Create/update via /v4/access_tools/pins
    • PINs must follow security guidelines (no repeated or sequential digits unless 4-digit legacy format)

🔔 Webhooks via Integrations

Set up webhooks to respond to system events.

  • Types of Events:

    • call — for video call events
    • access_log — for door releases and entry events
  • Endpoint:
    POST /v4/buildings/{building_id}/integrations

  • Required Fields:

    • url, method, resource_type, actions