Butlr Developer Docs
  • Welcome
  • What is Butlr
  • Spatial Metrics
  • Getting Started
    • Authentication
    • Making your first query
    • Mint Client Credentials
  • Changelog
  • Asset Management
    • GraphQL API Overview
      • Sites
      • Buildings
      • Floors
      • Rooms
      • Zones
      • Hives
      • Sensors
      • Asset Tags
    • GraphQL API Introsepction
  • Historical Occupancy
    • Reporting API Overview
      • Floor Occupancy
      • Room Occupancy
      • Zone Occupancy
      • Query Occupancy by Tag
      • Traffic
      • Presence Time
      • Statistic Overview
    • FAQs
  • Real-time occupancy
    • Webhooks Overview
      • Area Detections
      • Entryway Traffic
      • Floor Occupancy
      • Room Occupancy
      • Zone Occupancy
      • Motion Detection
      • No Motion Detection
    • Manage Webhooks
      • Create Webhooks
      • Update Webhooks
      • Delete Webhooks
      • List Webhooks
  • LINKS
    • Butlr Postman Collection
    • Butlr Website
    • Status
    • Support
    • Log In
Powered by GitBook
On this page
  • Payload
  • Field Descriptions
  1. Real-time occupancy
  2. Webhooks Overview

Zone Occupancy

The Zone Occupancy webhook event provides real-time updates on the number of occupants detected by the presence sensor on a specific zone.

Please note that we recompute occupancy data at every 1-minute cadence, looking back a few minutes to account for potential delays. This will result in repeated data for a rolling 5-minute window. You can expect duplicate events, updated occupancy counts for previous minutes and possible discrepancies between initial and recomputed values. When processing events, consider storing unique timestamps, using the latest data and implementing deduplication or caching mechanisms.

Payload

The Zone Occupancy event follows a standardized JSON structure:

{
  "id": "event_2oUBiSXgx48RtbZKXHm5ekpAzFe",
  "type": "ZONE_OCCUPANCY",
  "timestamp": 1727735832000,
  "version": "v1.0.0",
  "metadata": {
    "org_id": "org_2oUBiRES2AmpczNM5yLu7pChz8o",
    "site_id": "site_2oUBkdxF0lLJZxyWVix09ZTsMNV",
    "building_id": "building_2oUBkaFkcYwDzo7HLXpPh8bP4cD",
    "floor_id": "space_2oUBnI7YL51GNemTvKIxEgSZ8gx",
    "room_id": "room_2oUDDps5iKHHo6RwlMgGVihmTlq", // (optional)
    "zone_id": "zone_2oUJLGKGlqPjwnUCwXNXpX3HB28",
    "floor_custom_id": "2tZStWPtxqpmb3w0PoJDm7AnfIX", // (optional)
    "room_custom_id": "2tZSGplhA4CZ58wFlTf7wAeKMVo",  // (optional)
    "zone_custom_id": "2tZTBBPk0Xmmo8zl1zFXrBHZwsz",  // (optional)
    "org_name": "Murphy Group",
    "site_name": "Los Angeles",
    "building_name": "Bergnaum Building",
    "floor_name": "1st Floor",
    "room_name": "Cherry Falls", // (optional)
    "zone_name": "Desk 01"
  },
  "data": 4
}

Field Descriptions

Event Metadata

Field
Type
Description

id

string

Unique event identifier

type

string

Event type (e.g., "zone_occupancy")

timestamp

number

Timestamp of the event (in milliseconds)

version

string

Event version (e.g., "v1.0.0")

Organization and Location Metadata

Field
Type
Description

org_id

string

Unique organization identifier

site_id

string

Unique site identifier

building_id

string

Unique building identifier

floor_id

string

Unique floor identifier

room_id

string (optional)

Unique room identifier

zone_id

string

Unique zone identifier

floor_custom_id

string (optional)

Customer's unique floor identifier

room_custom_id

string (optional)

Customer's unique room identifier

zone_custom_id

string (optional)

Customer's unique zone identifier

org_name

string

Organization name

site_name

string

Site name

building_name

string

Building name

floor_name

string

Floor name

room_name

string (optional)

Room name

zone_name

string

Zone name

Occupancy Data

data

number

Current occupancy count on the room

PreviousRoom OccupancyNextMotion Detection

Last updated 2 months ago