POST /api/v202608/esaalert

Creates one Above/Below or Total Over Time threshold alert per ESA channel from a single alert definition

CreateThresholdAlertV202608 Permissions: Meters (Create)

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

EsaAlertCreate
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)
Example Request Body application/json
{  "alertType": "string",  "channelIds": [
    1
  ],  "direction": "string",  "interval": 1,  "triggerValue": 1.0,  "unitId": 1
}

Responses

200 OK The request succeeded and the response body contains the requested data.

Response Body Parameters

EsaAlertCreateResponse
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
Property Description Type
alertActive Whether the alert is active. Required (defined) boolean
alertId Primary key of the EsaAlert record. Required (defined) integer (int32)
alertMode Alert mode. 2 = Manual. Automatic types such as Trend Insights use other values. Required (defined) integer (int32)
channels

The channels this alert is attached to, and the meter and place each one sits under. Alerts are currently limited to one channel each, so this holds at most one entry. It stays a collection because the data model supports an alert spanning several channels, and alerts created before that limit may still have more than one.

Null and empty mean different things. Null means the endpoint does not supply the association. Empty means the alert genuinely has no channels attached. The create response always supplies it, holding the one channel each alert was created for. 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. Required (defined)

EsaAlertChannel[]
EsaAlertChannel properties
Property Description Type
channelId Primary key of the attached EsaChannel. integer (int32)
enabled Whether the alert is enabled for this specific channel. Distinct from EsaAlertResponseDTO.AlertActive, which is a single switch for the whole alert across every channel it is attached to - this one can differ per channel. Not enforced during evaluation yet: ThresholdAlertCheckJob currently gates only on AlertActive, so a channel reporting false here still fires today. ECAP-34685 adds the per-channel gate. Until it lands, treat this as configuration state, not as a statement about whether notifications will be raised. boolean
meterId The meter the channel’s data point belongs to. integer (int32)
placeId The place the channel’s meter sits in - the meter’s own place, not an ancestor. Note the list endpoint’s parentPlaceId filter matches any ancestor place, so this will usually differ from the value a caller filtered by. integer (int32)
esaAlertSeverityRating EsaAlertSeverityRating
EsaAlertSeverityRating properties
Property Description Type
esaAlertSeverityRatingId Primary key of the EsaAlertSeverityRating record. integer (int32)
severityRatingDescription Human-readable description of the severity rating. string
severityRatingInfo Display name for the severity rating (e.g. “Medium”). string
esaAlertSeverityRatingId FK to the alert’s EsaAlertSeverityRating. Create assigns Medium. Required (defined) integer (int32)
esaAlertType EsaAlertType
EsaAlertType properties
Property Description Type
alertTypeDescription Human-readable description of the alert type’s behaviour. string
alertTypeInfo Display name for the alert type (e.g. “Above/Below”). string
allowAutomatic Whether alerts of this type can be triggered automatically. boolean
allowManual Whether alerts of this type can be created manually. boolean
canHaveAssignee Whether alerts of this type support an assignee. boolean
esaAlertTypeId Primary key of the EsaAlertType record. integer (int32)
requiresAssignee Whether alerts of this type require an assignee. boolean
esaThresholdAlert EsaThresholdAlert
EsaThresholdAlert properties
Property Description Type
alertMode Alert mode value (2 = Custom). integer (int32)
esaAlertId FK to the parent EsaAlert record. integer (int32)
esaThresholdAlertId Primary key of the EsaThresholdAlert record. integer (int32)
interval Accumulation window in minutes for ’total over time’ alerts; null for ‘above/below’. integer (int32)
notificationTriggerCount Number of consecutive threshold violations before firing (always 1). integer (int32)
scheduleId FK to the Schedule used for this alert (24/7 by default). integer (int32)
triggerValue The threshold value being monitored. number (double)
triggerValueType Direction the threshold is evaluated in. integer (int32)
unitId FK to Unit defining the unit of measurement for the threshold. integer (int32)
unit EsaAlertUnit
EsaAlertUnit properties
Property Description Type
unitCode Short unit code (e.g. “KWH”). string
unitDisplayName Full display name (e.g. “kilowatt-hour”). string
unitId Primary key of the Unit record. integer (int32)
unitInfo Unit display label (e.g. “kWh”). string
unitType EsaAlertUnitType
EsaAlertUnitType properties
Property Description Type
unitTypeCode Short type code (e.g. “Counter”). string
unitTypeId Primary key of the UnitType record. integer (int32)
unitTypeInfo Display label for the unit type (e.g. “counter”). string
Example Response application/json
{  "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": {}
    }
  }
  ]
}
400 Bad Request The request was malformed or contains invalid parameters. Check the request body and query parameters.