Overview
Welcome to the XY Sense Developer Portal
XY Sense is an advanced occupancy intelligence platform that turns real-time, highly accurate, privacy-preserving sensor data into actionable insights for your office buildings. Our sensors capture 100% anonymous XY coordinates in real time to power workplace experience platforms, BMS, BI dashboards and other custom applications.
Our integration offering centres on the XY Sense API: secure access to live and historical occupancy data via Webhooks and/or GraphQL queries, with updates as frequent as every two seconds. Whether you're triggering building automation, syncing space availability, or feeding predictive models, our API is built for fast, flexible integration into your existing tech stack.
This documentation will walk you through authentication, core endpoints, webhook configuration, and common integration patterns — everything you need to get XY Sense occupancy data flowing into your application.
Ready to make your first API call? The Quickstart takes you from API key to first response in four steps. Otherwise, read on for what the platform offers and how the pieces fit together.
The two integration surfaces
XY Sense provides a GraphQL API and Webhooks, which may be used independently or together to integrate your Space, Floor Sightings, Occupancy events, and Analytics data into third-party platforms.
GraphQL API
The XY Sense GraphQL API utilises GraphQL as its query language.
The API can be used to query:
- Space data (ie/ Name and ID of all spaces on a given Floor)
- Sensor data and connection status (ie/ the position and connection status of all sensors on a floor)
- Historical Analytics and Heatmap data
- Latest or recent Occupancy information for Spaces
- Latest or recent Space Sensor readings
- Latest or recent Sightings on a Floor
XY Sense provides an interactive in-browser API Explorer that you can use to build and validate API queries and explore documentation.
Webhooks
Webhooks provide a fast and secure way to reliably stream Occupancy changes, Space Sensor readings, and Floor Sighting updates to other systems.
XY Sense batches and posts updates to any number of nominated HTTPS endpoints while queuing and tracking the delivery status of each change to guarantee at-least-once delivery in the order that the updates occurred.
Integration patterns
For most integrations, use both surfaces together:
- Use GraphQL to discover the buildings, floors, spaces, and sensors available to your integration.
- Register webhooks for the event types you need.
- Store the GraphQL reference data locally and join incoming webhook events to it by ID.
- Use GraphQL again for cache misses, reconciliation, historical data, and occasional backfills.
Prefer webhooks for ongoing occupancy, floor-sighting, and space-sensor updates. They deliver changes with lower latency and avoid continuous polling. Poll GraphQL only when webhooks cannot provide the history or query shape your workflow needs.
| Need | Recommended surface |
|---|---|
| Receive near-real-time changes | Webhooks |
| Keep a live downstream system updated | Webhooks |
| Discover buildings, floors, spaces, and sensors | GraphQL |
| Add names, hierarchy, floor plans, or sensor associations to events | GraphQL, cached locally |
| Reconcile missed or uncertain data | GraphQL |
| Query analytics, heatmaps, or historical windows | GraphQL |
Start with GraphQL API to bootstrap your reference data, then configure Webhooks for ongoing changes.
What is covered
- GraphQL query access for buildings, floors, spaces, occupancy, sightings, space sensor readings, analytics, and historical heatmap data.
- Webhook registration and event delivery for occupancy changes, floor sightings, and space sensor readings.
- Generated API reference pages from the external integration schema in this repository.
Production endpoints
- GraphQL endpoint:
https://core-api.app.xysense.io/api/external/query - Auth endpoint:
https://core-api.app.xysense.io/api/v1/auth - GraphiQL explorer:
https://core-api.app.xysense.io/ui/external/graphiql