Copy page

Common workflows

Send meter values

Use this workflow to send meter values for one or more Accounting Points.

This is typically used when meter values are provided directly to UtilityCloud by an external meter data system, partner system, or integration, instead of being received from a national energy market hub.

Endpoint

Code
POST /v1/se/general-mv-adapter/CreateMeterValuesSeries

When to use

Use this workflow when an external system needs to submit time series values to UtilityCloud.

Typical use cases include:

• sending meter values for district heating
• sending EV charging consumption values
• sending values for other service types handled directly in UtilityCloud

Request structure

The request contains a CorrelationId and a list of MeteredTimeSeries.

Each MeteredTimeSeries identifies the Metering/Accounting Point, value type, unit, resolution, source, and the meter values for one or more time intervals.

Code
{
  "CorrelationId": "1f7a3534-9de8-4e1f-9f87-ff414c1ad912",
  "MeteredTimeSeries": []
}

Example request

Code
{
  "CorrelationId": "1f7a3534-9de8-4e1f-9f87-ff414c1ad912",
  "MeteredTimeSeries": [
    {
      "AccountingPointIdentifier": "909012300012345678",
      "EnergyType": "Consumption",
      "Unit": "kWh",
      "Resolution": "PT1H",
      "Source": "My System",
      "CorrelationId": "9ab92f47-6fb8-441f-b4a1-9499819e4c89",
      "MeteredValues": [
        {
          "StartTime": "2022-12-16T23:00:00Z",
          "EndTime": "2022-12-17T00:00:00Z",
          "TimeSeriesValue": 1.933,
          "Status": "Metered",
          "InsertTime": "2022-12-17T00:00:00.876Z"
        }
      ]
    }
  ]
}

Request fields

Field	Description
CorrelationId	Correlation id for the request. Use a new GUID for tracing each submission.
MeteredTimeSeries	List of time series to submit.

MeteredTimeSeries fields

Field	Description
AccountingPointIdentifier	Identifier of the Accounting Point the values belong to.
EnergyType	Type of value being submitted. Supported values are Consumption and Production.
Unit	Measurement unit. Supported values are kWh and m3.
Resolution	Time resolution of the values. Supported values are PT15M, PT60M, and PT1H.
Source	Source system or integration that provided the values.
CorrelationId	Correlation id for the individual time series. Use a new GUID for tracing.
MeteredValues	List of values for the time series.

MeteredValues fields

Field	Description
StartTime	Start time of the value interval.
EndTime	End time of the value interval.
TimeSeriesValue	Numeric value for the interval.
Status	Status of the value. Supported values are Metered, Estimated, Temporary, Calculated, and Rejected.
InsertTime	Time when the value was inserted or registered by the source system.

Supported values

EnergyType

Value	Description
Consumption	The time series represents consumption.
Production	The time series represents production.

Resolution

Value	Description
PT15M	15-minute resolution.
PT60M	60-minute resolution.
PT1H	1-hour resolution.

Unit

Value	Description
kWh	Kilowatt-hour.
m3	Cubic meter.

Status

Value	Description
Metered	The value is measured.
Estimated	The value is estimated.
Temporary	The value is temporary.
Calculated	The value is calculated.
Rejected	The value is rejected.

Payload sizing

As a guideline, a single request can include up to 1,000 Accounting Points with up to 4,000 values per Accounting Point.

Maximum payload size may also be constrained by HTTP or gateway limits. If size-related errors occur, split the submission into smaller batches.

Response

A valid request is accepted for processing.

Code
202 Accepted

The submitted meter values can then be used as input for calculation, settlement, billing, reporting, validation, estimation, and operational processes.

Notes

Meter values are submitted as time series values.

Each value represents one interval with a start time, end time, value, status, and insert time.

Use UTC timestamps with ISO 8601 formatting.

Use a new CorrelationId for each request and for each time series where applicable. This helps with tracing and troubleshooting.

The Accounting Point must exist in UtilityCloud before meter values are submitted for it.

The submitted values should match the expected unit, resolution, and Service Type configuration for the Accounting Point.

Related endpoints

Code
POST /v1/se/general-mv-adapter/CreateMeterValuesSeries
GET /v1/se/calculation/GetCalculation?customer={customerGuid}&meteringpoint={accountingPointIdentification}&firstDay={firstDay}&lastDay={lastDay}&agg={aggregation}
GET /se/v2/GetPriceInformation?customer={customerGuid}&ap={accountingPointIdentification}&date={date}