PUT /api/v202406/esachannel/{esaChannelId}

Updates an existing ESA channel's configuration, including its interval, summarization method and unit

EditEsaChannelV202406 Permissions: Meters (Edit)

Use this endpoint to change a channel’s settings. Two consequences are worth knowing before calling it.

Attached alerts constrain the change. If any active custom threshold alert is attached to this channel, the request is rejected when the requested change would leave the channel ineligible for that alert - a unit that is not exactly the alert’s unit (no unit conversion is performed), or a summarization method the alert’s type and direction do not allow. Detach the alert with DELETE /api/v202608/esaalert/{esaAlertId}/channel/{esaChannelId} first if the change is still wanted.

An interval change can propagate to other channels, and be rejected because of them. A calculated channel’s interval is derived from the channels in its formula, so changing this channel’s interval can move the interval of a calculated channel on the same meter. If that moves a channel’s interval to a value incompatible with a ’total over time’ alert attached to it, the whole request is rejected and the error names that channel and alert - which may be a channel the caller did not set out to change. Nothing is persisted when this happens.

Changing the interval also fails if the channel has manually-entered readings.

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.

Path Parameters

Name	Description	Type	Required
esaChannelId	Unique numeric identifier of the ESA channel to edit, supplied via the request path	integer (int32)	Required

Request Body

EsaChannelEdit

Property

Description

Type

channelDescription

The channel description Max length of 255 Required (defined)

string

channelImportId

The channel import identifier Max length of 255 Required (defined)

string

channelInfo

The name of the ESA channel Max length of 50 Required

string

esaChannelVersion

EsaChannelVersionEdit

EsaChannelVersionEdit properties

Property

Description

Type

beginDate

Date and time that this channel version is valid from. The valid period is exclusive of the beginDate. The time zone of this date will match the data point’s time zone. Therefore, if any time zone information is provided, it will be ignored.

string (date-time)

formula

The formula that should be used to calculate the channel’s values. Should only be provided when channel’s IsCalculated property equals true.

string

isValuePositive

Indicates if the final value is always positive

boolean

maximumReading

The channel Maximum Computed Reading Must be between -999999999999999 and 999999999999999 Max scale of 15, max precision of 30 NULL Valid

number (double)

minimumReading

The channel Minimum Computed Reading Must be between -999999999999999 and 999999999999999 Max scale of 15, max precision of 30 NULL Valid

number (double)

multiplier

The channel multiplier Must be between -9999999999999 and 9999999999999 Required Max scale of 15, max precision of 30

number (double)

observationRuleId

Indicates the channel observation rule Demand channels cannot have the odometer observation rule Required Must be a valid value for ObservationRuleEnum: Odometer = 1, Trip = 2

integer (int32)

offset

The channel offset Exclusive to the Trip observation rule Must be between -9999999999999 and 9999999999999 Max scale of 15, max precision of 30

number (double)

rollbackAllowance

The channel Odometer Rollover Allowance. Exclusive to the Odometer observation rule If not provided, the default 0.1 is used Must be between 0 and 1 Max scale of 15, max precision of 30 NULL Valid Must be null when ObservationRuleId is set to Trip, case sensitive

number (double)

rolloverValue

The channel Odometer Rollover Value. Exclusive to the Odometer observation rule If not provided, the default 999999999999999 is used Must be between 0 and 999999999999999 Max scale of 15, max precision of 30 NULL Valid Must be null when ObservationRuleId is set to Trip, case sensitive

number (double)

udfs

List of user defined/custom fields and values for this channel version If the Udfs list is null or empty no values are assigned If a udf is omitted no value is assigned to that udf To remove a value from an existing Udf, pass in the UdfId and set the Value to null

UDFValue[]

UDFValue properties

Property	Description	Type
udfId	udfId of the UDF being edited Required (defined)	integer (int32)
value	Required (defined)	string

unitId

The channel unit identifier. It cannot be a Money unit type. Required

integer (int32)

intervalMinutes

The channel interval identifier One of ‘5’, ‘10’, ‘15’, ‘30’, ‘60’, ‘1440’, ‘10080’, ‘43200’ Case sensitive Required when IsCalculated is set to False, case sensitive. Must be null when IsCalculated is set to True, case sensitive

integer (int32)

isCalculated

Indicates whether or not this is a calculated channel with a formula. When IsCalculated is true, the formula will need to be provided in channel version. Conversions from Non-Calculated Channel to Calculated Channel: If the channel has no readings, If the channel has only one version, If the channel is not in other formulas Conversions from Calculated Channel to Non-Calculated Channel: If the channel has no readings Required (defined)

boolean

isPrimaryDemand

If the channel is demand value Required (defined)

boolean

isPrimaryValue

If the channel is primary value Required (defined)

boolean

observationTypeId

The channel type identifier Required

integer (int32)

summarizationMethodId

How readings are aggregated into each interval - Sum, Average, Max or Min. Determines what a threshold alert on this channel can mean, so changing it is rejected while an attached alert’s type and direction do not allow the new method (Sum for ’total over time’; Max or Average for ‘above’; Max, Average or Min for ‘below’). Required

integer (int32)

Example Request Body application/json

{  "channelDescription": "string",  "channelImportId": "string",  "channelInfo": "string",  "esaChannelVersion": {    "beginDate": "2026-11-14",    "formula": "string",    "isValuePositive": false,    "maximumReading": 1.0,    "minimumReading": 1.0,    "multiplier": 1.0,    "observationRuleId": 1,    "offset": 1.0,    "rollbackAllowance": 1.0,    "rolloverValue": 1.0,    "udfs": [
      {      "udfId": 1,      "value": "string"
    }
    ],    "unitId": 1
  },  "intervalMinutes": 1,  "isCalculated": false,  "isPrimaryDemand": false,  "isPrimaryValue": false,  "observationTypeId": 1,  "summarizationMethodId": 1
}

Responses

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

Response Body Parameters

EsaChannelResponse

Property

Description

Type

alerts

The manually-created (non-Sentinel) threshold alerts attached to this channel, regardless of AlertActive. Empty if the channel has no such alerts.

Each alert’s Channels holds one entry, this channel’s, so Enabled says whether the alert is switched on for this channel. It does not list the alert’s other channels.

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

channelDescription

Description of the channel

string

channelId

The identifier for the channel

integer (int32)

channelImportId

The import identifier for the channel.

string

channelInfo

The channel name

string

channelVersions

List of channel versions Versions include channel settings that may change over time

EsaChannelVersionResponse[]

EsaChannelVersionResponse properties

Property

Description

Type

beginDate

Date and time that this channel version is valid from. The valid period is exclusive of the beginDate.

string (date-time)

channelVersionId

The channel version identifier

integer (int32)

endDate

Date and time that this channel version is valid until. The valid period is inclusive of the endDate.

string (date-time)

formula

The formula that should be used in calculated channels.

string

isValuePositive

Indicates if the channel final value is always positive

boolean

maximumReading

The channel’s maximum reading

number (double)

minimumReading

The channel’s minimum reading

number (double)

multiplier

The channel multiplier

number (double)

observationRule

ObservationRule

ObservationRule properties

Property	Description	Type
observationRuleCode	The observation rule code	string
observationRuleId	The observation rule identifier	integer (int32)
observationRuleInfo	The observation rule info	string

offset

The channel offset

number (double)

resolvedFormula

Formula, but with the input Channels and Meters referenced by ChannelInfo (name) instead of by ID.

string

rollbackAllowance

The channel’s roll back allowance

number (double)

rolloverValue

The channel’s rollover value

number (double)

udfs

List of user defined/custom fields and values for this channel version

UDFFieldChild[]

UDFFieldChild properties

Property

Description

Type

dataType

DataTypeResponse

DataTypeResponse properties

Property	Description	Type
dataTypeCode	The data type code/short name Required (defined)	string
dataTypeId	The unique identifier for the data type (e.g., 1=boolean, 2=integer, 3=string, 4=double, 6=date, 12=select list, 13=URL) Required (defined)	integer (int32)
dataTypeInfo	The data type display name/description Required (defined)	string

description

A description of what this UDF field is used for Required (defined)

string

displayOrder

The sort order for displaying this field relative to other UDF fields Required (defined)

integer (int32)

important

When true, this UDF field is flagged as important and may be highlighted in the UI Required (defined)

boolean

name

The display name of the UDF field Required (defined)

string

udfId

The unique identifier for this UDF field definition Required (defined)

integer (int32)

udfSelectValues

For select-list type UDFs, the available options that can be chosen as values Required (defined)

UDFSelectValueEntityResponse[]

UDFSelectValueEntityResponse properties

Property	Description	Type
displayOrder	The sort order for displaying this option in the select list Required (defined)	integer (int32)
udfSelectValueId	The unique identifier of this select option. Use this value (not the display Value) when setting a select-list UDF. Required (defined)	integer (int32)
value	The display text for this select option Required (defined)	string

value

The current value of this UDF field for the entity. Null if no value has been set. Format depends on DataType. Required (defined)

string

unit

UnitChild

UnitChild properties

Property	Description	Type
unitCode	The unit code	string
unitId	The unit identifier	integer (int32)
unitInfo	The unit info	string

dataCompletenessPercentage

The percentage of expected readings that are present over the last 30 days. Null indicates no readings exist for this channel.

number (double)

dataPoint

DataPointChildWithParentAndImportId

DataPointChildWithParentAndImportId properties

Property

Description

Type

active

Indicates whether the data point is Active

boolean

commodity

CommodityChild

CommodityChild properties

Property

Description

Type

commodityCode

The commodity code Required (defined)

string

commodityIcon

Icon

Icon properties

Property	Description	Type
code	The icon code Must be between 0 and 64 characters Required when Color is set	string
color	The icon color Must be between 0 and 32 characters Required when Code is set	string

commodityId

The commodity identifier Required (defined)

integer (int32)

commodityInfo

The commodity info Required (defined)

string

dataPointCode

The data point code

string

dataPointId

The data point identifier

integer (int32)

dataPointImportId

The import identifier for the data point

string

dataPointInfo

The data point info

string

isCalculatedDataPoint

Indicates whether the data point is a calculated data point

boolean

isDataRolledUp

Indicates if the primary value channel on the datapoint has a summarization method of SUM

boolean

parentPlace

PlaceChild

PlaceChild properties

Property

Description

Type

isDataRolledUp

Tells whether or not the place’s data is rolled up to its parents.

boolean

placeCode

The place code

string

placeId

The place identifier

integer (int32)

placeInfo

The place info

string

placeType

PlaceTypeResponse

PlaceTypeResponse properties

Property

Description

Type

icon

Icon

Icon properties

Property	Description	Type
code	The icon code Must be between 0 and 64 characters Required when Color is set	string
color	The icon color Must be between 0 and 32 characters Required when Code is set	string

isSystemPlaceType

Flag to indicate if the place type is a system-level place type

boolean

placeEntityType

PlaceEntityTypeV202406

PlaceEntityTypeV202406 properties

Property	Description	Type
placeEntityTypeId	The place entity type identifier	integer (int32)
placeEntityTypeInfo	The place entity type name	string

placeTypeCode

The place type code

string

placeTypeId

The place type identifier

integer (int32)

placeTypeInfo

The place type info

string

structure

Indicates if the place is a structure

boolean

sentinelEnabled

Indicates if the Sentinel is active for primary value channels

boolean

serialNumber

The data point’s current serial number

string

firstReadingDate

DateTimeOffset of the earliest Reading for the Channel. For Calculated Channels, this is the first Summarized Reading. For all other Channels, this is the first Processed Reading. The DateTimeOffset will always be a valid time in the Meter’s Time Zone. If the offset is removed, it will be the local date and time, in the Meter’s Time Zone.

string (date-time)

hasReadings

Indicates if the channel has readings

boolean

interval

The channel interval

integer (int32)

isCalculated

Indicates if the channel is calculated

boolean

isCalculatedConvertible

Indicates if the channel can be converted from calculated to non-calculated or vice-versa From Non-Calculated to Calculated: If the channel has no readings, If the channel has only one version, If the channel is not in other formulas From Calculated to Non-Calculated: If the channel has no readings

boolean

isPrimaryDemand

Indicates if the channel is the primary demand channel for the data point

boolean

isPrimaryValue

Indicates if the channel is the primary value channel for the data point

boolean

lastReadingDate

DateTimeOffset of the most recent Reading for the Channel. For Calculated Channels, this is the most recent Summarized Reading. For all other Channels, this is the most recent Processed Reading. The DateTimeOffset will always be a valid time in the Meter’s Time Zone. If the offset is removed, it will be the local date and time, in the Meter’s Time Zone.

string (date-time)

lastReadingValue

ValueWithUnit

ValueWithUnit properties

Property

Description

Type

unit

UnitChild

UnitChild properties

Property	Description	Type
unitCode	The unit code	string
unitId	The unit identifier	integer (int32)
unitInfo	The unit info	string

value

Value

number (double)

meter

MeterChildIncludePlace

MeterChildIncludePlace properties

Property

Description

Type

active

Indicates whether the Meter is Active

boolean

commodity

CommodityChild

CommodityChild properties

Property

Description

Type

commodityCode

The commodity code Required (defined)

string

commodityIcon

Icon

Icon properties

Property	Description	Type
code	The icon code Must be between 0 and 64 characters Required when Color is set	string
color	The icon color Must be between 0 and 32 characters Required when Code is set	string

commodityId

The commodity identifier Required (defined)

integer (int32)

commodityInfo

The commodity info Required (defined)

string

isCalculatedMeter

Indicates whether the meter is a calculated meter

boolean

isEsaCalculatedMeter

Indicates whether the meter is an ESA calculated meter

boolean

isSplitChildMeter

Indicates whether the meter is a child of a split

boolean

isSplitParentMeter

Indicates whether the meter is a parent of a split

boolean

meterCode

The meter code

string

meterId

The meter identifier

integer (int32)

meterInfo

The meter info

string

meterType

MeterTypeChild

MeterTypeChild properties

Property	Description	Type
meterTypeCode	Short code for the meter type (e.g., “ELEC”, “GAS”)	string
meterTypeId	Unique numeric identifier of the meter type	integer (int32)
meterTypeInfo	Descriptive name of the meter type	string

parentPlace

PlaceChild

PlaceChild properties

Property

Description

Type

isDataRolledUp

Tells whether or not the place’s data is rolled up to its parents.

boolean

placeCode

The place code

string

placeId

The place identifier

integer (int32)

placeInfo

The place info

string

placeType

PlaceTypeResponse

PlaceTypeResponse properties

Property

Description

Type

icon

Icon

Icon properties

Property	Description	Type
code	The icon code Must be between 0 and 64 characters Required when Color is set	string
color	The icon color Must be between 0 and 32 characters Required when Code is set	string

isSystemPlaceType

Flag to indicate if the place type is a system-level place type

boolean

placeEntityType

PlaceEntityTypeV202406

PlaceEntityTypeV202406 properties

Property	Description	Type
placeEntityTypeId	The place entity type identifier	integer (int32)
placeEntityTypeInfo	The place entity type name	string

placeTypeCode

The place type code

string

placeTypeId

The place type identifier

integer (int32)

placeTypeInfo

The place type info

string

structure

Indicates if the place is a structure

boolean

serialNumber

The meter’s current serial number

string

observationType

ObservationTypeChild

ObservationTypeChild properties

Property	Description	Type
credit	Indicates the type of credit for the observation type. Possible values include: 1 (Credit), 2 (Debit), 3 (Ignore)	integer (int32)
nounCode	The observation type’s noun code	string
nounId	The identifier for the observation type’s noun	integer (int32)
observationTypeCode	The observation type code	string
observationTypeId	The observation type identifier	integer (int32)
observationTypeInfo	The observation type info	string

summarizationMethod

SummarizationMethod

SummarizationMethod properties

Property	Description	Type
summarizationMethodId	The summarization method identifier	integer (int32)
summarizationMethodInfo	The name of the summarization method	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": {}
    }
  }
  ],  "channelDescription": "string",  "channelId": 1,  "channelImportId": "string",  "channelInfo": "string",  "channelVersions": [
    {    "beginDate": "2026-11-14",    "channelVersionId": 1,    "endDate": "2026-11-14",    "formula": "string",    "isValuePositive": false,    "maximumReading": 1.0,    "minimumReading": 1.0,    "multiplier": 1.0,    "observationRule": {      "observationRuleCode": "string",      "observationRuleId": 1,      "observationRuleInfo": "string"
    },    "offset": 1.0,    "resolvedFormula": "string",    "rollbackAllowance": 1.0,    "rolloverValue": 1.0,    "udfs": [
      {      "dataType": {},      "description": "string",      "displayOrder": 1,      "important": false,      "name": "string",      "udfId": 1,      "udfSelectValues": [],      "value": "string"
    }
    ],    "unit": {      "unitCode": "string",      "unitId": 1,      "unitInfo": "string"
    }
  }
  ],  "dataCompletenessPercentage": 1.0,  "dataPoint": {    "active": false,    "commodity": {      "commodityCode": "string",      "commodityIcon": {},      "commodityId": 1,      "commodityInfo": "string"
    },    "dataPointCode": "string",    "dataPointId": 1,    "dataPointImportId": "string",    "dataPointInfo": "string",    "isCalculatedDataPoint": false,    "isDataRolledUp": false,    "parentPlace": {      "isDataRolledUp": false,      "placeCode": "string",      "placeId": 1,      "placeInfo": "string",      "placeType": {}
    },    "sentinelEnabled": false,    "serialNumber": "string"
  },  "firstReadingDate": "2026-11-14",  "hasReadings": false,  "interval": 1,  "isCalculated": false,  "isCalculatedConvertible": false,  "isPrimaryDemand": false,  "isPrimaryValue": false,  "lastReadingDate": "2026-11-14",  "lastReadingValue": {    "unit": {      "unitCode": "string",      "unitId": 1,      "unitInfo": "string"
    },    "value": 1.0
  },  "meter": {    "active": false,    "commodity": {      "commodityCode": "string",      "commodityIcon": {},      "commodityId": 1,      "commodityInfo": "string"
    },    "isCalculatedMeter": false,    "isEsaCalculatedMeter": false,    "isSplitChildMeter": false,    "isSplitParentMeter": false,    "meterCode": "string",    "meterId": 1,    "meterInfo": "string",    "meterType": {      "meterTypeCode": "string",      "meterTypeId": 1,      "meterTypeInfo": "string"
    },    "parentPlace": {      "isDataRolledUp": false,      "placeCode": "string",      "placeId": 1,      "placeInfo": "string",      "placeType": {}
    },    "serialNumber": "string"
  },  "observationType": {    "credit": 1,    "nounCode": "string",    "nounId": 1,    "observationTypeCode": "string",    "observationTypeId": 1,    "observationTypeInfo": "string"
  },  "summarizationMethod": {    "summarizationMethodId": 1,    "summarizationMethodInfo": "string"
  }
}

400 Bad Request The request was malformed or contains invalid parameters. Check the request body and query parameters.

404 Not Found The requested resource was not found. Verify the ID or path is correct.