# 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

```http
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.

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

## Example request

```json
{
  "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.

```http
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

```http
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}
```