There are two ways to interact with VergeSense’s APIs: VergeSense can set up pre-packaged Webhooks to automatically “push” relevant data to your platform, enabling greater customization. Or, you can use VergeSense’s REST / Analytics API to “pull” the data you need.
\nWebhooks are the preferred way to get a stream of real time data, for example, for every sensor, room, point in time, or a person count in a given space. When using webhooks, the data is pushed to your platform where you can perform further analysis.
\nSome use cases for webhooks:
\nIndicate availability of rooms in real time. For example, you have a kiosk in your lobby and want to know when rooms are available.
\nIntegrate with business intelligence dashboards. For example, Robin Powered or an Integrated Workplace Management System (IWMS) of your choosing.
\nMeanwhile, the REST API is useful for getting specific or historical metadata from a point in time. When using the REST API, VergeSense stores the data and performs the analysis for you to conveniently access.
\nA use case for the REST API:
\nTo get an API key, contact support@vergesense.com to request a VergeSense Admin account.
Once you have a VergeSense Admin account, navigate to Integrations and click Generate API Key.
\n![](\"https://files.readme.io/2ed10b9-Generate_API_Key_1.png\")
\n\nOn the popup screen, enter an API Token Name, select buildings to which the API key applies, then click Save.
\n![](\"https://files.readme.io/9085977-Generate_API_Key_2.png\")
\n\nTo view or modify the API key, navigate to Integrations and click Details.
\n![](\"https://files.readme.io/7d035d6-Generate_API_Key_3.png\")
\n\nFrom the Details screen, you can
\nedit the API Token Name,
\nclick the eye icon to view the API key,
\nselect buildings to which the API key applies, or
\nclick Rotate to generate a new API key.
\nYour organization may choose to periodically rotate the API key for enhanced security or in the event the API key was compromised.
\n![](\"https://files.readme.io/9105acf-Generate_API_Key_4.png\")
\n\nAPIs request allows you to retrieve data from a data source or to send data. API requests should be made to the following endpoints depending on the deployment environment:
AWS (default): https://api.vergesense.com
Azure: https://api.azure.vergesense.com
API endpoints are authenticated via the API key. Once you have an API key, you must use the HTTP header vs-api-key. Otherwise, a 403: Forbidden error will be returned. All requests must use https://. Requests made to http:// will not be accepted.
400 Bad Request
Invalid request sent to API. Additional information appears in the response body.
403 Forbidden
Caused by a missing HTTP header or invalid API token.
404 Not Found
The requested resource does not exist.
409 Conflict
The request conflicts with another request.
Timestamps should be specified in ISO 8601 format.
\nThe following formats are both valid: 2019-01-15T23:30:28-08:00 and 2019-01-15T23:30:28Z.
Timestamps will be returned in ISO 8601 UTC format, for example: 2019-01-15T23:30:28Z.
API requests will timeout after 30 seconds. If your requests are timing out, use an appropriate filter to reduce the result set and the time required to calculate a response.
\nA rate limit of 120 requests per minute is enforced across all API endpoints based on the source IP address.
\nAPI changes will be published on our public facing changelog. Through the changelog VergeSense will publish information regarding new endpoints, improvements, and deprecations.
\nAn RSS feed of the changelog is available using this URL: https://headwayapp.co/vergesense-changelog/rss
\nAt VergeSense we use a YYYY-MM-DD format to version our APIs. The first time you make a request to our API we will set your API version to the most recent version. Optionally, if you'd like to use a different version of the API, you can use the vs-version request header. This document is for version 2017-06-14. The current version of the API is 2019-04-17. To find a full list of versions along with their respective changes, please see our ChangeLog.
Fetch all detections for spaces on a given day.
Response conforms to the JSON API spec https://jsonapi.org/.
Responses are limited to 10,000 detections after which pagination will take place.
Space Detection Model
\n","urlObject":{"path":["spaces","detections"],"host":["https://cloud.vergesense.com"],"query":[{"description":{"content":"Date to fetch thresholds crossings for. Date is required unless a timestamp filter query parameter is provided.
\n","type":"text/plain"},"key":"date","value":""},{"description":{"content":"Greater than or equal to the timestamp.
\n","type":"text/plain"},"key":"filter[timestamp][gte]","value":""},{"description":{"content":"Greater than the timestamp.
\n","type":"text/plain"},"key":"filter[timestamp][gt]","value":""},{"description":{"content":"Less than or equal to the timestamp.
\n","type":"text/plain"},"key":"filter[timestamp][lte]","value":null},{"description":{"content":"Less than or equal to the timestamp.
\n","type":"text/plain"},"key":"filter[timestamp][lt]","value":null},{"description":{"content":"Requested page number. Only used when pagination is applicable.
\n","type":"text/plain"},"key":"page[number]","value":""}],"variable":[]}},"response":[{"id":"f8d601e6-76dd-4188-86bd-6a46cbee09bf","name":"spaces","originalRequest":{"method":"GET","header":[{"key":"Accept","value":"application/json","type":"text"},{"key":"vs-api-key","value":"6067ce385a2f6fb57c27b75628c38140","type":"text"}],"url":"https://api.vergesense.com/spaces"},"_postman_previewlanguage":"Text","header":[],"cookie":[],"responseTime":null,"body":""}],"_postman_id":"a6998cbf-53b4-41ff-ba16-dc52c64f9dbd"},{"name":"/spaces/thresholds/crossings","id":"0ca47607-ac72-42d9-bb08-317904a3a01c","protocolProfileBehavior":{"disabledSystemHeaders":{"content-length":true},"disableBodyPruning":true},"request":{"auth":{"type":"noauth","isInherited":false},"method":"GET","header":[{"key":"Accept","value":"application/json","type":"text"},{"key":"vs-api-key","value":"{{api-key}}","type":"text"}],"url":"https://cloud.vergesense.com/spaces/thresholds/crossings?date=&filter[timestamp][gte]\n=&filter[timestamp][lte]&filter[timestamp][gt]&filter[timestamp][lt]&page[number]=1","description":"Fetch all threshold crossings for spaces on a given day.
Response conforms to the JSON API spec https://jsonapi.org/.
Responses are limited to 1,000 threshold crossings after which pagination will take place.
Space Threshold Crossing Model
\n","urlObject":{"path":["spaces","thresholds","crossings"],"host":["https://cloud.vergesense.com"],"query":[{"description":{"content":"Date to fetch thresholds crossings for. Date is required unless a timestamp filter query parameter is provided.
\n","type":"text/plain"},"key":"date","value":""},{"description":{"content":"Greater than or equal to the timestamp.
\n","type":"text/plain"},"key":"filter[timestamp][gte]\n","value":""},{"description":{"content":"Greater than the timestamp.
\n","type":"text/plain"},"key":"filter[timestamp][lte]","value":null},{"description":{"content":"Less than or equal to the timestamp.
\n","type":"text/plain"},"key":"filter[timestamp][gt]","value":null},{"key":"filter[timestamp][lt]","value":null},{"key":"page[number]","value":"1"}],"variable":[]}},"response":[],"_postman_id":"0ca47607-ac72-42d9-bb08-317904a3a01c"},{"name":"/spaces","id":"118b30b3-eb5c-4f2b-8033-006a3ec70974","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"noauth","isInherited":false},"method":"GET","header":[{"key":"vs-api-key","value":"{{api-key}}","type":"text"}],"url":"https://cloud.vergesense.com/spaces?building_ref_id&floor_ref_id&space_ref_id&space_type","description":"This API Endpoint will provide you with the most recent sensor reports for spaces within 24 hours timeframe.
\nHTTP Method: GET
\nBaseURL: https://api.vergesense.com
\nEndpoint: /space
\nURL: {{BaseURL}/{{Endpoint}}
\nFilter on building_ref_id to get only the spaces belonging to a particular building.
\n","type":"text/plain"},"key":"building_ref_id","value":null},{"description":{"content":"Filter on floor_ref_id to get only the spaces belonging to a particular floor.
\n","type":"text/plain"},"key":"floor_ref_id","value":null},{"description":{"content":"Filter on space_ref_id to get a single space.
\n","type":"text/plain"},"key":"space_ref_id","value":null},{"description":{"content":"Options: desk, desk_area, conference_room, lounge_area, collaboration_room, phone_booth, activity_zone, and office
\n","type":"text/plain"},"key":"space_type","value":null}],"variable":[]}},"response":[],"_postman_id":"118b30b3-eb5c-4f2b-8033-006a3ec70974"}],"id":"022441a1-5a66-451e-82a5-e1c3a3bcfe37","description":"This API documentation provides you with the recent space report, space detection and the space threshold crossings of spaces associated the sensors.
\n","_postman_id":"022441a1-5a66-451e-82a5-e1c3a3bcfe37"},{"name":"Metrics API","item":[{"name":"/metrics/spaces","id":"ddd86c29-43a8-426a-a4fa-82a39a2039d2","protocolProfileBehavior":{"disabledSystemHeaders":{},"disableBodyPruning":true},"request":{"auth":{"type":"noauth","isInherited":false},"method":"GET","header":[{"key":"Accept","value":"application/json","type":"text"},{"key":"vs-api-key","value":"{{api-key}}","type":"text"}],"url":"https://cloud.vergesense.com/metrics/spaces?filter[timestamp][gte]=&filter[timestamp][lte]=&interval=&page[number]=&page[size]=","description":"Metrics for spaces aggregated by the requested interval
\nTimestamp (UTC) that you would like the results to be greater than or equal to.
\n","type":"text/plain"},"key":"filter[timestamp][gte]","value":""},{"description":{"content":"Timestamp (UTC) that you would like the results to be less than or equal to.
\n","type":"text/plain"},"key":"filter[timestamp][lte]","value":""},{"description":{"content":"Interval (in minutes) to use for the bucketing of metrics data.
\n","type":"text/plain"},"key":"interval","value":""},{"description":{"content":"Page number for pagination.
\n","type":"text/plain"},"key":"page[number]","value":""},{"description":{"content":"Number of spaces to include per page. Limit is 1000.
\n","type":"text/plain"},"key":"page[size]","value":""}],"variable":[]}},"response":[{"id":"eb91c56c-8fc7-446e-b5db-7cae2698c5ac","name":"spaces","originalRequest":{"method":"GET","header":[{"key":"Accept","value":"application/json","type":"text"},{"key":"vs-api-key","value":"6067ce385a2f6fb57c27b75628c38140","type":"text"}],"url":"https://api.vergesense.com/spaces"},"_postman_previewlanguage":"Text","header":[],"cookie":[],"responseTime":null,"body":""}],"_postman_id":"ddd86c29-43a8-426a-a4fa-82a39a2039d2"},{"name":"/metrics/hourly/spaces","id":"d3f0c843-4b3e-44c6-a8e3-ad17f51b31bf","protocolProfileBehavior":{"disabledSystemHeaders":{},"disableBodyPruning":true},"request":{"auth":{"type":"noauth","isInherited":false},"method":"GET","header":[{"key":"Accept","value":"application/json","type":"text"},{"key":"vs-api-key","value":"{{api-key}}","type":"text"}],"url":"https://cloud.vergesense.com/metrics/hourly/spaces?fields[metrics_hourly_space]&page[number]=1&page[size]=10&filter[space_type.key]&filter[space_type.name]&filter[building_ref_id]=&filter[floor_ref_id]=S2&filter[space_ref_id]=&filter[local_date][gte]=2023-04-25&filter[local_date][lte]=2023-04-26&filter[local_hour][gte]\n=8&filter[local_hour][lte]=16&sort=-local_date,local_hour","description":"Hourly metrics for spaces
\nlocal_date and local_hour have 6 different comparison operators.
filter[][]=
Limit attributes that are included in a request. Comma separated list of attributes.
\n","type":"text/plain"},"key":"fields[metrics_hourly_space]","value":null},{"description":{"content":"Page number for pagination.
\n","type":"text/plain"},"key":"page[number]","value":"1"},{"description":{"content":"Amount of records to return per page. Limit is 1000.
\n","type":"text/plain"},"key":"page[size]","value":"10"},{"description":{"content":"Filter metrics based on it's associated space type's key.
\n","type":"text/plain"},"key":"filter[space_type.key]","value":null},{"description":{"content":"Filter metrics based on it's associated space type's name.
\n","type":"text/plain"},"key":"filter[space_type.name]","value":null},{"description":{"content":"Filter metrics based on it's associated space's building_ref_id.
\n","type":"text/plain"},"key":"filter[building_ref_id]","value":""},{"description":{"content":"Filter metrics based on it's associated space's floor_ref_id.
\n","type":"text/plain"},"key":"filter[floor_ref_id]","value":"S2"},{"description":{"content":"Filter metrics based on it's associated space's space_ref_id.
\n","type":"text/plain"},"key":"filter[space_ref_id]","value":""},{"description":{"content":"Number between 0-23. Filter metrics where local_hour is greater than or equal to value.
\n","type":"text/plain"},"key":"filter[local_date][gte]","value":"2023-04-25"},{"description":{"content":"Filter metrics where local_date is less than or equal to value.
\n","type":"text/plain"},"key":"filter[local_date][lte]","value":"2023-04-26"},{"description":{"content":"Number between 0-23. Filter metrics where local_hour is greater than or equal to value.
\n","type":"text/plain"},"key":"filter[local_hour][gte]\n","value":"8"},{"description":{"content":"Number between 0-23. Filter metrics where local_hour is less than or equal to value.
\n","type":"text/plain"},"key":"filter[local_hour][lte]","value":"16"},{"description":{"content":"Comma separated list of attributes used to sort the collection. Use a negative(-) sign to reverse the order
\n","type":"text/plain"},"key":"sort","value":"-local_date,local_hour"}],"variable":[]}},"response":[{"id":"634c3cba-63e4-449a-8101-c1b96754ea91","name":"spaces","originalRequest":{"method":"GET","header":[{"key":"Accept","value":"application/json","type":"text"},{"key":"vs-api-key","value":"6067ce385a2f6fb57c27b75628c38140","type":"text"}],"url":"https://api.vergesense.com/spaces"},"_postman_previewlanguage":"Text","header":[],"cookie":[],"responseTime":null,"body":""}],"_postman_id":"d3f0c843-4b3e-44c6-a8e3-ad17f51b31bf"},{"name":"/metrics/hourly/floors","id":"4de49609-f363-47ff-a9ed-2b498629a52c","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"noauth","isInherited":false},"method":"GET","header":[{"key":"vs-api-key","value":"{{api-key}}","type":"text"}],"url":"https://cloud.vergesense.com/metrics/hourly/floors\n?sort=-local_date,local_hour&fields[metrics_hourly_space]=&page[number]=&page[size]&filter[building_ref_id]&filter[floor_ref_id]&filter[local_date][gte]&filter[local_date][lte]&filter[local_hour][gte]&filter[local_hour][lte]","description":"Hourly metrics for floors
\nPath
\n/metrics/hourly/floors?filter[floor_ref_id]=3&filter[local_date][gt]=2022-08-02&filter[local_date][lt]=2022-08-20&filter[local_hour][gt]=4&filter[building_ref_id]=Skyline_Blvd_HQ
Description
\nRetrieve all hourly floor metrics where the local_date is greater than 2022-08-02 and local_date is less than 2022-08-20 and the local_hour is greater than 4 and the building_ref_id equals Skyline_Blvd_HQ.
local_date and local_hour have 6 different comparison operators.
filter[][]=
Comma separated list of attributes used to sort the collection. Use a negative(-) sign to reverse the order.
\n","type":"text/plain"},"key":"sort","value":"-local_date,local_hour"},{"description":{"content":"Limit attributes that are included in a request. Comma separated list of attributes.
\n","type":"text/plain"},"key":"fields[metrics_hourly_space]","value":""},{"description":{"content":"Page number for pagination.
\n","type":"text/plain"},"key":"page[number]","value":""},{"description":{"content":"Amount of records to return per page. Limit is 1000
\n","type":"text/plain"},"key":"page[size]","value":null},{"description":{"content":"Filter metrics based on it's associated space's building_ref_id.
\n","type":"text/plain"},"key":"filter[building_ref_id]","value":null},{"description":{"content":"Filter metrics based on it's associated space's floor_ref_id.
\n","type":"text/plain"},"key":"filter[floor_ref_id]","value":null},{"description":{"content":"Filter metrics where local_date is greater than or equal to value.
\n","type":"text/plain"},"key":"filter[local_date][gte]","value":null},{"description":{"content":"Filter metrics where local_date is less than or equal to value
\n","type":"text/plain"},"key":"filter[local_date][lte]","value":null},{"description":{"content":"Number between 0-23. Filter metrics where local_hour is greater than or equal to value.
\n","type":"text/plain"},"key":"filter[local_hour][gte]","value":null},{"description":{"content":"Number between 0-23. Filter metrics where local_hour is less than or equal to value.
\n","type":"text/plain"},"key":"filter[local_hour][lte]","value":null}],"variable":[]}},"response":[],"_postman_id":"4de49609-f363-47ff-a9ed-2b498629a52c"}],"id":"7bfbab95-056c-404f-8149-9a3cb6da7803","_postman_id":"7bfbab95-056c-404f-8149-9a3cb6da7803","description":""},{"name":"Building API","item":[{"name":"/buildings","id":"e8f8580e-b5f2-4ae7-b1bd-fb909f187d4f","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[{"key":"vs-api-key","value":"{{api-key}}","type":"text"}],"url":"https://cloud.vergesense.com/buildings","description":"Get a list of buildings that VergeSense has data on.
\n","urlObject":{"path":["buildings"],"host":["https://cloud.vergesense.com"],"query":[],"variable":[]}},"response":[],"_postman_id":"e8f8580e-b5f2-4ae7-b1bd-fb909f187d4f"},{"name":"/buildings/:building_ref_id","id":"0be6cd89-a02f-4fa2-9e42-369ac2d18716","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[{"key":"x-api-key","value":"{{api-key}}","type":"text"}],"url":"https://cloud.vergesense.com/buildings/:building_ref_id?floor_ref_id=","description":"Get information about the hierarchy of a building, down to the VergeSense sensor level.
\n","urlObject":{"path":["buildings",":building_ref_id"],"host":["https://cloud.vergesense.com"],"query":[{"key":"floor_ref_id","value":""}],"variable":[{"id":"c391a783-d367-48e3-9fbf-fee72cb76145","description":{"content":"building_ref_id is required
\n","type":"text/plain"},"type":"any","value":"","key":"building_ref_id"}]}},"response":[],"_postman_id":"0be6cd89-a02f-4fa2-9e42-369ac2d18716"}],"id":"53afb009-6908-4446-b89a-84ff472ac469","description":"The API Documentation will provide you with the list of building associated to your API Key or your account
\n","_postman_id":"53afb009-6908-4446-b89a-84ff472ac469"},{"name":"Hardware API","item":[{"name":"/hardware/sensors","id":"05750189-06ff-40c0-8d17-5c0b28a51476","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"noauth","isInherited":false},"method":"GET","header":[{"key":"x-api-key","value":"{{api-key}}","type":"text"}],"url":"https://cloud.vergesense.com/hardware/sensors?page[number]=","description":"Fetch all sensors.
Response conforms to the JSON API spec https://jsonapi.org/.
Responses are limited to 1,000 sensors after which pagination will take place.
Hardware Sensor Model
\n","urlObject":{"path":["hardware","sensors"],"host":["https://cloud.vergesense.com"],"query":[{"description":{"content":"Requested page number. Only used when pagination is applicable.
\n","type":"text/plain"},"key":"page[number]","value":""}],"variable":[]}},"response":[],"_postman_id":"05750189-06ff-40c0-8d17-5c0b28a51476"},{"name":"/hardware/gateways","id":"0555c6c0-b81d-4c18-a804-64caeb1b78ec","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[{"key":"x-api-key","value":"{{api-key}}","type":"text"}],"url":"https://api.vergesense.com/hardware/gateways?page[number]=1","description":"Fetch all gateways. Response conforms to the JSON API spec https://jsonapi.org/.Responses are limited to 1,000 gateway after which pagination will take place.
Hardware Gateway Model
\n","urlObject":{"protocol":"https","path":["hardware","gateways"],"host":["api","vergesense","com"],"query":[{"key":"page[number]","value":"1"}],"variable":[]}},"response":[],"_postman_id":"0555c6c0-b81d-4c18-a804-64caeb1b78ec"}],"id":"a394d4f2-d752-4afc-bcae-025b4f622cda","_postman_id":"a394d4f2-d752-4afc-bcae-025b4f622cda","description":""},{"name":"Webhook API","item":[{"name":"/webhooks","id":"4e81c1ce-d15f-42fb-8226-2cb8a2d3b2f3","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"noauth","isInherited":false},"method":"POST","header":[{"key":"vs-api-key","value":"{{api-key}}","type":"text"}],"body":{"mode":"raw","raw":"{\n \"enabled\": \"false\",\n \"parameters\": {\n \"AUTHORIZATION\": {\n \"BASIC\": {\n \"BASIC_AUTH_USERNAME\": \"Username\",\n \"BASIC_AUTH_PASSWORD\": \"Password\"\n }\n },\n \"CUSTOM_HEADERS\": {\n \"customkey\": \"--customkey--\"\n },\n \"EVENT_ENDPOINT\": \"Endpoint URL\"\n },\n \"action_id\": 3,\n \"name\": \"--Name of your webhook --\"\n}","options":{"raw":{"language":"json"}}},"url":"https://cloud.vergesense.com/webhooks","description":"Create a webhook.
\nname: Name of the webhook
\naction_id: The webhook type to setup (3 - Space Report, 4 - Sensor Report, 5 - Space Availability, 6 - PIR Triggered)
\nenabled: Whether or not the webhook is enabled
\nEVENT_ENDPOINT: HTTPS endpoint to send the webhook to
\nparameters: Parameters to configure the webhook
\nPARAMETERS OBJECT EVENT_ENDPOINT: HTTPS endpoint to send the webhook to
\nAUTHORIZATION:Optional authorization configuration
\nBASIC_AUTH_USERNAME: Username used in Basic authentication
\nCUSTOM_HEADERS: Object of key value pairs to send as part of the webhook request
\nCUSTOM_HEADERS : customkey
\nfilters: Filters to restrict the webhook to. If absent will attach the webhook to all buildings
\n","urlObject":{"path":["webhooks"],"host":["https://cloud.vergesense.com"],"query":[],"variable":[]}},"response":[],"_postman_id":"4e81c1ce-d15f-42fb-8226-2cb8a2d3b2f3"},{"name":"/webhooks/:id/enable","id":"cc04cb56-e950-4890-9788-7ce4f901d57e","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"vs-api-key","value":"{{api-key}}","type":"text"}],"url":"https://cloud.vergesense.com/webhooks/:id/enable","description":"Enable a webhook.
\n","urlObject":{"path":["webhooks",":id","enable"],"host":["https://cloud.vergesense.com"],"query":[],"variable":[{"id":"9dd19501-d62d-4445-b337-1cae102d298a","type":"any","value":"1","key":"id"}]}},"response":[],"_postman_id":"cc04cb56-e950-4890-9788-7ce4f901d57e"},{"name":"/webhooks/:id/disable","id":"b8779e20-c682-4dd4-abd2-7810cbfe10bf","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"vs-api-key","value":"{{api-key}}","type":"text"}],"url":"https://cloud.vergesense.com/webhooks/:id/enable","description":"Disable a webhook.
\n","urlObject":{"path":["webhooks",":id","enable"],"host":["https://cloud.vergesense.com"],"query":[],"variable":[{"id":"56ba31e7-4601-4124-befe-a70b3e4b31a0","type":"any","value":"1","key":"id"}]}},"response":[],"_postman_id":"b8779e20-c682-4dd4-abd2-7810cbfe10bf"},{"name":"/webhooks","id":"87472a39-689a-4e22-84f1-aa48f36df567","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[],"url":"https://cloud.vergesense.com/webhooks","description":"Retrieve all webhooks.
\n","urlObject":{"path":["webhooks"],"host":["https://cloud.vergesense.com"],"query":[],"variable":[]}},"response":[],"_postman_id":"87472a39-689a-4e22-84f1-aa48f36df567"},{"name":"webhooks/setup","id":"81e071b9-59f0-4689-b440-eb7f7a7ffc61","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[{"key":"vs-api-key","value":"{{api-key}}","type":"text"}],"url":"https://cloud.vergesense.com/webhooks/setup","description":"Retrieve the webooks that are available to be setup, including their names, descriptions, and other basic information about them.
\n","urlObject":{"path":["webhooks","setup"],"host":["https://cloud.vergesense.com"],"query":[],"variable":[]}},"response":[],"_postman_id":"81e071b9-59f0-4689-b440-eb7f7a7ffc61"},{"name":"/webhooks/:id","id":"fa7aeaeb-7244-45a6-a202-894d2660ef01","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"noauth","isInherited":false},"method":"PATCH","header":[{"key":"vs-api-key","value":"{{api-key}}","type":"text"}],"url":"https://cloud.vergesense.com/webhooks/id/","description":"Delete a webhook.
\n","urlObject":{"path":["id"],"host":["https://cloud.vergesense.com"],"query":[],"variable":[]}},"response":[],"_postman_id":"440090b7-2313-4650-b98a-b4cd4b91cf41"},{"name":"/webhooks/:id/logs","id":"c237effc-4c68-416e-8ba1-3eb119e97f9a","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"noauth","isInherited":false},"method":"GET","header":[{"key":"vs-api-key","value":"{{api-key}}","type":"text"}],"url":"https://cloud.vergesense.com/webhooks/:id/logs?page&limit&start_at&end_at","description":"Retrieve a webhook's logs. This endpoint only contains the last 7 days of logs
\n","urlObject":{"path":["webhooks",":id","logs"],"host":["https://cloud.vergesense.com"],"query":[{"key":"page","value":null},{"key":"limit","value":null},{"key":"start_at","value":null},{"key":"end_at","value":null}],"variable":[{"id":"1906d6dd-a950-4abf-b2b3-6a937ec4bfae","type":"any","value":null,"key":"id"}]}},"response":[],"_postman_id":"c237effc-4c68-416e-8ba1-3eb119e97f9a"}],"id":"59552172-c273-4d2a-90f7-656685e8e8e0","description":"VergeSense's API allows you to subscribe to various events generated by your sensors. Supported events include:
\nspace_reportspace_availabilityTo subscribe to a webhook either use the API endpoint below or use the VergeSense UI in order to configure.
\nVergeSense provides a variety of ways for customers to authenticate requests from VergeSense to their desired destination. Authentication is not required but some form is recommended.
\nIP Address Allow List
VergeSense sends webhook requests from a known set of IP addresses. Should some form of IP address filtering be desired, contact VergeSense for more information regarding the list of IP addresses.
VergeSense supports custom headers, allowing customers to define any specific headers they would like sent as part of a webhook POST request.
VergeSense has the following expectations when interacting with a user provide endpoint:
\n2xx HTTP status codeIf any of these conditions are not met then the request will fail. If >99% of requests fail within a 24 period then VergeSense will automatically disable the webhook. You will be notified of this via email with details pertaining to the top errors and will be able to correct the issue and re-enable.
For this type of event, reports will be sent that aggregate all sensor data and other metadata into a single report of the most up to date information regarding a space. This is especially useful in situations where multiple sensors are required to cover a single space, for example a very large conference room. In these cases, the report data is aggregated across the individual sensor reports to provide information for the whole space in one easily consumable event.
\nSpace Report Event
\ntype SpaceReportEvent = {\n // customer defined building reference ID\n building_ref_id: String,\n // customer defined floor reference ID\n floor_ref_id: String|null,\n // customer defined space reference ID\n space_ref_id: String|null,\n event_type: \"space_report\",\n // iso8601 timestamp\n timestamp: String,\n // number of people in the space\n person_count: Number,\n // whether or not there were objects like laptops, backpacks, coats, etc. detected\n signs_of_life: Boolean,\n // whether or not motion was detected in the space\n motion_detected: Boolean|null,\n // detailed information regarding the people in the space\n people: {\n // array of arrays of [x,y] coordinate pairs for each person detected by a device\n coordinates: [Array<[Number, Number]>?],\n count: Number,\n distances: {\n units: \"meters\",\n // meters apart people are from one another\n values: [Number]\n }\n },\n // array of device IDs that report on the space\n sensor_ids: [String],\n // present if the device supports it otherwise not present\n environment?: {\n humidity: {\n // relative humidity\n units: \"RH\",\n value: Number\n },\n // indoor air quality\n iaq: {\n units: \"UBA\",\n value: Number\n },\n // device id that reported environmental information\n sensor: String,\n temperature: {\n // celsius\n units: \"C\",\n value: Number\n },\n // iso8601 timestamp\n timestamp: String\n }\n}\n\nWhile the \"Space Report\" webhook will send a report every time a sensor that reports on a space has new information, the \"Space Availability\" webhook is used to be notified when the availability of a space has changed. The possible states for the state field are available|occupied. The payload is an array -- one record per space that a sensor reports on.
Space Availability Event
\n[\n {\n \"building_ref_id\": \"building_1\",\n \"floor_ref_id\": \"floor_4\",\n \"space_ref_id\": \"123.321\",\n \"sensor_ids\": [\"VS0-123\", \"VS1-321\"],\n \"event_type\": \"space_availability\",\n \"timestamp\": \"2019-08-21T21:10:25Z\",\n \"state\": \"occupied\"\n }\n]\n