Skip to main content
Eptura Knowledge Center

Occupancy Sensor API

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"
}