> For the complete documentation index, see [llms.txt](https://docs.butlr.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.butlr.io/real-time-occupancy/webhooks-overview/room-occupancy.md).

# Room Occupancy

{% hint style="warning" %}
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.
{% endhint %}

## Payload

The Room Occupancy event follows a standardized JSON structure:

```json
{
  "id": "event_2oUBiSXgx48RtbZKXHm5ekpAzFe",
  "type": "ROOM_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",
    "floor_custom_id": "2tZStWPtxqpmb3w0PoJDm7AnfIX", // (optional)
    "room_custom_id": "2tZSGplhA4CZ58wFlTf7wAeKMVo",  // (optional)
    "org_name": "Murphy Group",
    "site_name": "Los Angeles",
    "building_name": "Bergnaum Building",
    "floor_name": "1st Floor",
    "room_name": "Cherry Falls"
  },
  "data": 4
}
```

### Field Descriptions

#### Event Metadata

<table><thead><tr><th width="130">Field</th><th width="95">Type</th><th>Description</th></tr></thead><tbody><tr><td>id</td><td>string</td><td>Unique event identifier</td></tr><tr><td>type</td><td>string</td><td>Event type (e.g., "room_occupancy")</td></tr><tr><td>timestamp</td><td>number</td><td>Timestamp of the event (in milliseconds)</td></tr><tr><td>version</td><td>string</td><td>Event version (e.g., "v1.0.0")</td></tr></tbody></table>

#### Organization and Location Metadata

<table><thead><tr><th width="173">Field</th><th width="155">Type</th><th>Description</th></tr></thead><tbody><tr><td>org_id</td><td>string</td><td>Unique organization identifier</td></tr><tr><td>site_id</td><td>string</td><td>Unique site identifier</td></tr><tr><td>building_id</td><td>string</td><td>Unique building identifier</td></tr><tr><td>floor_id</td><td>string</td><td>Unique floor identifier</td></tr><tr><td>room_id</td><td>string</td><td>Unique room identifier</td></tr><tr><td>floor_custom_id</td><td>string (optional)</td><td>Customer's unique floor identifier</td></tr><tr><td>room_custom_id</td><td>string (optional)</td><td>Customer's unique room identifier</td></tr><tr><td>org_name</td><td>string</td><td>Organization name</td></tr><tr><td>site_name</td><td>string</td><td>Site name</td></tr><tr><td>building_name</td><td>string</td><td>Building name</td></tr><tr><td>floor_name</td><td>string</td><td>Floor name</td></tr><tr><td>room_name</td><td>string</td><td>Room name</td></tr></tbody></table>

#### Occupancy Data

<table><thead><tr><th width="98">Field</th><th width="96">Type</th><th>Description</th></tr></thead><tbody><tr><td>data</td><td>number</td><td>Current occupancy count on the room</td></tr></tbody></table>