Creates a new Above/Below or Total Over Time threshold alert
Use this endpoint to create a manual threshold alert. The AlertType field must be ‘above/below’ (triggers when a single reading crosses the threshold) or ’total over time’ (triggers when the accumulated value over the specified Interval exceeds the threshold; Interval is required in that case and must be at least 60 minutes). The alert is assigned the Medium severity rating and references the 24/7 schedule. If ChannelIds are provided, all channels must be active, accessible to the calling user, and eligible for the alert.
A channel is eligible only if it is a primary value or primary demand channel, has a summarization method the alert type and direction allow (Max or Average for ‘above’; Max, Average, or Min for ‘below’; Sum for ’total over time’), and has exactly the alert’s unit. Units must match exactly, not merely share a unit type: no unit conversion is performed anywhere, so a kWh channel cannot be used with an MWh alert. A meter whose channels carry different units therefore needs one alert per unit. For ’total over time’ the alert’s Interval must also be a whole multiple of the channel’s interval (it may equal it), since the total is accumulated from whole channel intervals. Use GET /esaalert/{alertId}/channels to list the channels that satisfy all of this.
Request Headers
| Header | Value | Required | Description |
|---|---|---|---|
| ECI-ApiKey | string | Yes | Your API key. See Authentication. |
| Content-Type | application/json | Yes | All requests must specify JSON content type, including the request body. |
Request Body
| Property | Description | Type |
|---|---|---|
| alertType | Alert type discriminator. Valid values: ‘above/below’ or ’total over time’. Required One of ‘above/below’, ’total over time’ | string |
| channelIds | Optional ESA channel IDs to associate to the alert. Null or empty creates an alert with no channel assignments, which can be added later via POST /esaalert/{esaAlertId}/channel. Every id supplied must be eligible for this alert - primary value or demand, a summarization method the type and direction allow, exactly the alert’s unit, and for ’total over time’ an interval the alert’s Interval is a whole multiple of. The whole request is rejected if any is not. | integer[] |
| direction | Direction the threshold is evaluated in. Valid values: ‘above’ or ‘below’. Required One of ‘above’, ‘below’ | string |
| interval | Interval in minutes for ’total over time’ alerts. Null for ‘above/below’ alerts. Required when AlertType is set to total over time Must be null when AlertType is set to above/below Must be between 60 and 2147483647 | integer (int32) |
| triggerValue | Threshold value that triggers the alert. Required | number (double) |
| unitId | The Unit.unitID the threshold is expressed in. Any channel assigned to this alert must carry exactly this unit, not merely one of the same unit type: no unit conversion is performed, so a kWh channel cannot be used with an MWh alert. This cannot be changed after creation. Required Must be between 1 and 2147483647 | integer (int32) |
{ "alertType": "string", "channelIds": [
1
], "direction": "string", "interval": 1, "triggerValue": 1.0, "unitId": 1
}Responses
Response Body Parameters
| Property | Description | Type | |||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| alertActive | Whether the alert is active. | boolean | |||||||||||||||||||||||||||||||||
| alertId | Primary key of the EsaAlert record. | integer (int32) | |||||||||||||||||||||||||||||||||
| alertMode | Alert mode. 2 = Manual. Automatic types such as Trend Insights use other values. | integer (int32) | |||||||||||||||||||||||||||||||||
| channels | The channels this alert is attached to, and the meter and place each one sits under. An alert can be attached to any number of channels, so this is a collection rather than a single id. Null and empty mean different things. Null means the endpoint does not supply the association - the create response does not, because the caller supplied the channel ids in the request. Empty means the alert genuinely has no channels attached. On the list endpoint (GET, threshold alerts), this only reports the channels that matched the request’s own filters - not necessarily every channel the alert is attached to. A channel-, meter-, place-, or status filter can each narrow it down to a subset. |
EsaAlertChannel[] | |||||||||||||||||||||||||||||||||
|
EsaAlertChannel properties
|
|||||||||||||||||||||||||||||||||||
| esaAlertSeverityRating | EsaAlertSeverityRating | ||||||||||||||||||||||||||||||||||
|
EsaAlertSeverityRating properties
|
|||||||||||||||||||||||||||||||||||
| esaAlertSeverityRatingId | FK to the alert’s EsaAlertSeverityRating. Create assigns Medium. | integer (int32) | |||||||||||||||||||||||||||||||||
| esaAlertType | EsaAlertType | ||||||||||||||||||||||||||||||||||
|
EsaAlertType properties
|
|||||||||||||||||||||||||||||||||||
| esaThresholdAlert | EsaThresholdAlert | ||||||||||||||||||||||||||||||||||
|
EsaThresholdAlert properties
|
|||||||||||||||||||||||||||||||||||
| unit | EsaAlertUnit | ||||||||||||||||||||||||||||||||||
|
EsaAlertUnit properties
|
|||||||||||||||||||||||||||||||||||
{ "alertActive": false, "alertId": 1, "alertMode": 1, "channels": [
{ "channelId": 1, "enabled": false, "meterId": 1, "placeId": 1
}
], "esaAlertSeverityRating": { "esaAlertSeverityRatingId": 1, "severityRatingDescription": "string", "severityRatingInfo": "string"
}, "esaAlertSeverityRatingId": 1, "esaAlertType": { "alertTypeDescription": "string", "alertTypeInfo": "string", "allowAutomatic": false, "allowManual": false, "canHaveAssignee": false, "esaAlertTypeId": 1, "requiresAssignee": false
}, "esaThresholdAlert": { "alertMode": 1, "esaAlertId": 1, "esaThresholdAlertId": 1, "interval": 1, "notificationTriggerCount": 1, "scheduleId": 1, "triggerValue": 1.0, "triggerValueType": 1, "unitId": 1
}, "unit": { "unitCode": "string", "unitDisplayName": "string", "unitId": 1, "unitInfo": "string", "unitType": { "unitTypeCode": "string", "unitTypeId": 1, "unitTypeInfo": "string"
}
}
}