Access and Call Logs

This guide explains how to programmatically access door release records and video call history for buildings or tenants.

Access to logs is scoped by user permissions — admins can view logs across buildings they manage; tenants can only view their own activity.

🚪 Access Logs

Access logs represent events where someone attempted to or successfully unlocked an access point using ButterflyMX — via app, PIN, RFID, or visitor pass.

🔗 Endpoint

GET /v4/buildings/{building_id}/access_logs

🔍 Query Parameters

Parameter	Type	Description
`page` / `per`	int	Pagination control
`q[logged_at_gteq]`	string (date)	Start date (inclusive)
`q[logged_at_lteq]`	string (date)	End date (inclusive)
`q[release_method_in][]`	array	Filter by methods (e.g., `swipe_to_open`, `qr_code`, `pin`)
`q[unit_label_or_user_full_name_or_delivery_authorization_description_start]`	string	Fuzzy search by tenant/unit name

📦 Sample Response

{
  "data": [
    {
      "id": 123456,
      "logged_at": "2025-04-24T10:24:35Z",
      "access_point": 22177636,
      "release_status": "Unlocked",
      "entry_method": "Swipe to open",
      "name": "Jane Doe",
      "unit": 843107216,
      "image_url": "https://cdn.butterflymx.com/snapshot.png"
    }
  ]
}

📞 Call Logs

Call logs represent historical video call attempts made from ButterflyMX devices (e.g., front door panel) to tenants or attendants.

🔗 Endpoint

GET /v4/buildings/{building_id}/calls

🔍 Query Parameters

Parameter	Type	Description
`page` / `per`	int	Pagination control
`q[logged_at_gteq]`	string (datetime)	Start timestamp
`q[logged_at_lteq]`	string (datetime)	End timestamp
`q[unit_label_or_user_full_name_start]`	string	Partial match on unit or name
`q[notification_type_eq]`	string	e.g. `visitor`
`q[origin_eq]`	string	Origin device ID (optional)

📦 Sample Response

{
  "data": [
    {
      "id": 400494507,
      "building_id": 577696272,
      "logged_at": "2025-04-21T10:24:35Z",
      "notification_type": "visitor",
      "recipient": {
        "id": 377389742,
        "type": "Tenant"
      },
      "unit": {
        "id": 474917539
      },
      "device": {
        "id": 708353660,
        "name": "Main Entrance"
      },
      "status": "initializing",
      "image_url": "https://cdn.butterflymx.com/video-thumbnail.jpg"
    }
  ]
}

🧠 Use Cases

Security auditing: Track entry attempts and video call activity across access points
Analytics: Measure visitor trends, peak access times, or delivery volumes
Integrations: Sync logs with CRM, property management, or incident tracking systems

✅ Tips & Best Practices

Use pagination (page and per) to retrieve large datasets efficiently

Updated 10 days ago