> 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/integrations-api-third-party-sensors/integrations.md).

# Overview

The Integrations API serves historical data from **third-party sensors** that are installed in your Butlr spaces, such as desk occupancy, motion, and temperature sensors. These sensors sit in the same site → building → floor → room hierarchy as your Butlr hardware, and add one level below it: the [**spot**](/integrations-api-third-party-sensors/spots.md).

**Base URL:** `https://api-integrations.butlr.io` (HTTPS only)

| Endpoint                                                                           | Purpose                                                                                      |
| ---------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
| [`POST /api/v1/reporting`](/integrations-api-third-party-sensors/reporting-api.md) | Time-series data: occupancy, temperature, door/window activity, events, and device heartbeat |

{% hint style="warning" %}
**This is a separate API from the** [**Reporting API**](/historical-occupancy/reporting-api-overview.md) **under Historical Occupancy.** It has its own host, request body, and error codes. Requests written for `api.butlr.io/api/v3/reporting` will not work here, and the reverse is also true.
{% endhint %}

## Which Reporting API should I use?

|               | Reporting API (Historical Occupancy)                 | Integrations Reporting API                                                                                 |
| ------------- | ---------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| Data from     | Butlr sensors                                        | Third-party sensors                                                                                        |
| Endpoint      | `POST https://api.butlr.io/api/v3/reporting`         | `POST https://api-integrations.butlr.io/api/v1/reporting`                                                  |
| Request shape | `measurement`, `window`, `filter`                    | Flat JSON: `measurements`, `items`, `start`, `stop`, `interval`                                            |
| Aggregation   | You choose a function (`sum`, `mean`, …) in `window` | Pre-computed: every statistic (`min`, `max`, `mean`, …) comes back as its own field                        |
| Response      | Rows per series                                      | `data` object keyed by entity ID                                                                           |
| Errors        | See that API's docs                                  | `{"errors": [{"code": …, "description": "…"}]}`: `-2`/`-3` for authentication, `-5xxx` for everything else |

## Supported sensors

| Sensor                  | What you can query                                                                                                           |
| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| Desk occupancy          | [Desk occupancy](/integrations-api-third-party-sensors/reporting-api/occupancy.md) per spot, rolled up to room and floor     |
| Motion                  | [Motion occupancy](/integrations-api-third-party-sensors/reporting-api/occupancy.md) per spot, rolled up to room and floor   |
| Temperature             | [Temperature](/integrations-api-third-party-sensors/reporting-api/temperature.md) per sensor, room, and floor                |
| Door/window contact     | [Door/window opening counts](/integrations-api-third-party-sensors/reporting-api/door-window-activity.md) per room and floor |
| Touch                   | [Individual touch events](/integrations-api-third-party-sensors/reporting-api/touch-events.md) per room                      |
| All third-party sensors | [Connectivity heartbeat](/integrations-api-third-party-sensors/reporting-api/device-heartbeat.md) per device                 |

[Cleaning alerts](/integrations-api-third-party-sensors/reporting-api/cleaning-alerts.md) generated from traffic and door/window data can also be queried.

## Next steps

1. [Spots & Sensor Placement](/integrations-api-third-party-sensors/spots.md): how third-party sensors map to your spaces, and the IDs you query with.
2. [Authentication & Rate Limits](/integrations-api-third-party-sensors/authentication.md): get a token and stay within limits.
3. [Reporting API Overview](/integrations-api-third-party-sensors/reporting-api.md): make your first request.