Creates one Above/Below or Total Over Time threshold alert per ESA channel from a single alert definition
Use this endpoint to create manual threshold alerts. The definition in the request is applied to each channel in ChannelIds, creating one independent alert per channel: each has its own id and can be edited, enabled, disabled or deleted without affecting the others. 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). Each alert is assigned the Medium severity rating and references the 24/7 schedule. At least one channel is required, and all channels must be active, accessible to the calling user, and eligible for the alert. The request is all-or-nothing: if any channel fails, no alerts are created.
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.
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 | The ESA channel IDs to create the alert for. Required, must contain at least one entry, and no duplicates. One independent alert is created per channel, each with its own copy of this definition. 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, and no alerts are created, if any is not. Required Min length of 1 | 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 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| alerts | The created alerts, one per channel in the request, in the same order as the request’s ChannelIds. Each alert’s Channels holds exactly the one channel it was created for. Never empty: a request that creates nothing is rejected instead. | EsaAlertResponse[] | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
EsaAlertResponse properties
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
{ "alerts": [
{ "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": {}
}
}
]
}