Occupancy Sensor API

Last updated
Save as PDF

About the API

The Occupancy Sensor API is designed to ingest Occupancy Events from IoT sensors in near real-time. It is delivered as a standard Webhook. If you want to learn how the Sensor Integration Works, see Occupancy Sensors.

Web-Hook Endpoint

The specific endpoint will be provisioned on a case-by-case basis. Each webhook will take the form: https://<TBD>.spaceiq.com/webhook/<token>

Inputs

HTTP POST
Request Header: "Content-Type: application/json"
Request Body: JSON formatted with the following fields:

Field	Type	Required	Description
event_code	String	Yes	Unique code for this event (no 2 events should have the same event_code)
occupancy_status	String	Yes	enum: occupied - the sensor is reporting the space as occupied vacant - the sensor is reporting the space as vacant offline - the sensor vendor is reporting that the sensor is not-functional / not to be trusted, typically because the sensor hasn't "phoned home" within an expected time period
sensor_codes	Array[String]	Yes	Unique identifier(s) for the sensor device(s) that reported the event in the vendor’s system. A meeting room may have multiple sensors in it.
space_codes	Array[String]	Yes	An array of Serraview Space IDs that the sensor is deployed to. This is usually a single value, but maybe multiple values in the case of a ceiling mounted sensor that had multiple desks within its field of view. In the event this array is empty, it means the sensor was unable to determine what spaces were in view.
floor_code	String	Yes	The Serraview Floor Name that the sensor is deployed to.
building_code	String	Yes	The Serraview Building Name that the sensor is deployed to.
headcount	Integer \| null	No	The number of people detected in the event. If the sensor isn't able to provide an accurate headcount (eg. PIR sensors), this should be set to null.
floor_x	Decimal \| null	No	The x coordinate on the Serraview floor plan (map) where the space is. This should be set to null if unknown.
floor_y	Decimal \| null	No	The y coordinate on the floor plan (map) where the space is. This should be set to null if unknown.
event_time	String	YES	UTC Date and Time of the Event in ISO8601 format.
vendor	String	YES	The name of the sensor manufacturer (eg. Coworkr, Vergesense, etc).
model	String	YES	The type of sensor as prescribed by the sensor vendor (eg. Counter, Workpoint, etc)

Outputs

This webhook is asynchronous and does not provide any input validation. The only valid response is 200 OK.

Failures

If the webhook is not accessible, we recommend retrying up to a maximum of 5 times with a 1 minute break in between each retry.

Example

Request Body:

{
  "event_code": "1",
  "occupancy_status": "occupied",
  "sensor_codes": ["sensor123"],
  "space_codes": ["11.123"],
  "floor_code": "11",
  "building_code": "Smith St",
  "headcount": 1,
  "floor_x": null,
  "floor_y": null,
  "event_time": "2021-03-19T10:05:55Z",
  "vendor": "vergesense",
  "model" : "counter"
}