This API provides access to administrative operations for configuring, monitoring, and maintaining the gateways and sensors that make up an Everactive installation, and for managing the software that detects and responds to events reported by sensors.

Using the REST API

The Data Services REST API has two parts, one for managing the hardware configuration (Evergateways and Eversensors), and one for managing the software (Webhooks) that a client uses to receive and process the data reported by sensors.

Resources

Access Data Services resources through this base URL:

https://api.data.everactive.com/ds/{ds-api-version}

The current DS API version is v1.

Authentication

The Everactive REST API uses OAuth2 with the client_credentials authentication flow. The client_credentials grant type is used for backend system-to-system integrations, when the system authenticating to the API is not acting on behalf of a user. (See more information about this grant type.)

To use the Everactive API you must obtain authorization client credentials. At this time, authorization client credentials are available to Everactive partners and can be obtained by contacting Everactive.

The credentials consist of a client ID and client secret combination. The client ID/client secret combination is only intended for server-side integrations with the Everactive API.

❗️

Authentication security

The client secret must be protected and hidden from end users. It is the responsibility of developers integrating their backend systems with Everactive to keep the client secret secure.

The Everactive API uses OAuth2 to authenticate and generate a Bearer token to authorize API endpoints. To obtain a client_credentials token, make a POST request to the following endpoint:

https://api.data.everactive.com/auth/token

Send your credentials in the body of the request, as a JSON object with the following format:

{
  "client_id": "the_client_id",
  "client_secret": "the_client_secret",
  "grant_type": "client_credentials"
}

Request / Response body

Most Everactive API requests and responses use JSON for the body. No other data formats (such as XML) are accepted or provided.

All responses are wrapped in a JSON object with the primary payload in the data property. Additional properties can describe error conditions and pagination information, depending on the type of payload returned.

Pagination information:
A response that returns an Array of data in the data property also returns an additional paginationInfo object with the following format:

{
  "paginationInfo": {
    "page": 1,
    "pageSize": 50,
    "totalItems": 153,
    "totalPages": 4
  }
}

Error information:
Requests that result in an error condition have the following response format:

{
  "code": "error_validation",
  "message": "Validation error.",
  "errors": [
    "code": "err_invalid_mac_address",
    "field": "sensor.macAddress",
    "message": "no:ta:re:al:ma:c0 is an invalid MAC Address"
  ]
}

Webhooks

The Everactive Data Services API allows Evercloud clients to create webhooks to receive near real-time sensor reading data. As readings are received, Evergateways send HTTP POST requests to the endpoint you designate when creating the subscription.

When an event is triggered, Evercloud sends a POST request to your registered webhook. The body contains a JSON object whose properties depend on the type of Eversensor that produced the reading.

• Steam trap monitors (STM sensors) send temperature/humidity readings.
• Machine-health monitors (MHM sensors) send vibrational/electrical readings.

Webhook security

Webhook subscriptions must use HTTPS. Additionally, it is possible to designate key / value headers that should be included in each HTTP POST Everactive sends to the subscription endpoint. These header values can be used to provide an API Key or Basic Auth header to ensure the data received originated from Everactive.

Sensor data schemas

Sensors report metadata on their own identity and status, in addition to detecting and reporting either temperature/humidity or vibrational/electrical readings for the equipment they are attached to.

All data reported by Eversensors is JSON-encoded for transmission in the body of API requests and webhook messages. The schema for each type of sensor includes information about the sensor type and MAC address, the time and date of the reading, and the gateway through which the reading was received. Beyond this type-independent information, the data properties for each type of sensor reflect the type of data detected.

For complete details, see Eversensors API overview.