Types of APIs
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.
Webhooks 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.
Some use cases for webhooks:
- Indicate availability of rooms in real time. For example, you have a kiosk in your lobby and want to know when rooms are available.
- Integrate with business intelligence dashboards. For example, Robin Powered or an Integrated Workplace Management System (IWMS) of your choosing.
Meanwhile, 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.
A use case for the REST API:
- Building a historical report. For example, you want to generate a report for Building 1, Floor 3 to determine how busy Conference Room B was in the month of February.
Setup
To get an API key, contact [email protected] to request a VergeSense Admin account.
Once you have a VergeSense Admin account, navigate to Integrations and click Generate API Key.
On the popup screen, enter an API Token Name, select buildings to which the API key applies, then click Save.
To view or modify the API key, navigate to Integrations and click Details.
From the Details screen, you can
- edit the API Token Name,
- click the eye icon to view the API key,
- select buildings to which the API key applies, or
- click Rotate to generate a new API key.
Your organization may choose to periodically rotate the API key for enhanced security or in the event the API key was compromised.
Requests
APIs 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
Authentication
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.
Error Codes
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
Timestamps should be specified in ISO 8601 format.
The 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.
Timeouts and Rate Limiting
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.
A rate limit of 120 requests per minute is enforced across all API endpoints based on the source IP address.
API Changes
API changes will be published on our public facing changelog. Through the changelog VergeSense will publish information regarding new endpoints, improvements, and deprecations.
RSS Feed
An RSS feed of the changelog is available using this URL: https://headwayapp.co/vergesense-changelog/rss
Versioning
At 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.
Postman Collection
The VergeSense API is available as a Postman collection. This collection can be found here: https://documenter.getpostman.com/view/6835591/2s9Y5Wx3QL