List Energy Accounts
Describes the List Energy Accounts call.
Purposeβ
The purpose of this endpoint is to deliver accounts for the energy sector related to a specific Principal using the principalId.
This Data Adapter endpoint is used to deliver the responses for the following Consumer Data Standards endpoint:
Data Adapter APIβ
List Energy Accountsβ
Loading...
Β
Consumer Data Standards Associationsβ
Get Energy Accountsβ
Loading...
Β
CDR Error Mappingβ
| Title | Status Code | Adapter URN - Error Code | Detail | CDR Status Code | CDR URN - Error Code |
|---|---|---|---|---|---|
| Invalid Field | 400 | urn:au-cds:error:cds-all:Field/Invalid | Applies when the value of required path parameter, i.e. principalId is an invalid type or the value violates the field's constraints. | 500 | urn:au-cds:error:cds-all:GeneralError/Unexpected |
| Invalid Header | 400 | urn:au-cds:error:cds-all:Header/Invalid | Applies when a HTTP Header is provided but the value provided is an invalid type or violates the field type constraints as defined in the Consumer Data Standards. | 500 | urn:au-cds:error:cds-all:GeneralError/Unexpected |
| Expected Error | 400 | urn:au-cds:error:cds-all:GeneralError/Expected | This status code indicates that the Expected Error has encountered. | 500 | urn:au-cds:error:cds-all:GeneralError/Unexpected |
| Invalid Resource | 404 | urn:au-cds:error:cds-all:Resource/Invalid | The requested resource identifier is permanently unavailable. | 404 | urn:au-cds:error:cds-all:Resource/Invalid |
| Legal Block | 451 | urn:dio:error:cds-all:Resource/LegalBlock | This status code indicates that the server is denying access to the resource as a consequence of a legal demand. | 422 | urn:au-cds:error:cds-all:Resource/Unavailable |
| Ineligible Block | 451 | urn:dio:error:cds-all:Resource/IneligibleBlock | This status code indicates that the Customer is ineligible for CDR Data Sharing. | 422 | urn:au-cds:error:cds-all:Resource/Invalid |
| Call Center Block | 451 | urn:dio:error:cds-all:Resource/CallCenterBlock | This status code indicates that the consumer should call the Call Center for further information. | 422 | urn:au-cds:error:cds-all:Resource/Invalid |
| Internal Server Error | 500 | urn:au-cds:error:cds-all:GeneralError/Unexpected | This status code indicates that the server encountered an internal error or misconfiguration. | 500 | urn:au-cds:error:cds-all:GeneralError/Unexpected |
Get Energy Account Detailβ
Loading...
Β
CDR Error Mappingβ
| Title | Status Code | Adapter URN - Error Code | Detail | CDR Status Code | CDR URN - Error Code |
|---|---|---|---|---|---|
| Invalid Field | 400 | urn:au-cds:error:cds-all:Field/Invalid | Applies when the value of required path parameter, i.e. principalId is an invalid type or the value violates the field's constraints. | 500 | urn:au-cds:error:cds-all:GeneralError/Unexpected |
| Invalid Header | 400 | urn:au-cds:error:cds-all:Header/Invalid | Applies when a HTTP Header is provided but the value provided is an invalid type or violates the field type constraints as defined in the Consumer Data Standards. | 500 | urn:au-cds:error:cds-all:GeneralError/Unexpected |
| Expected Error | 400 | urn:au-cds:error:cds-all:GeneralError/Expected | This status code indicates that the Expected Error has encountered. | 500 | urn:au-cds:error:cds-all:GeneralError/Unexpected |
| Invalid Resource | 404 | urn:au-cds:error:cds-all:Resource/Invalid | The requested resource identifier is permanently unavailable. | 404 | urn:au-cds:error:cds-all:Resource/Invalid |
| Legal Block | 451 | urn:dio:error:cds-all:Resource/LegalBlock | This status code indicates that the server is denying access to the resource as a consequence of a legal demand. | 422 | urn:au-cds:error:cds-all:Resource/Unavailable |
| Ineligible Block | 451 | urn:dio:error:cds-all:Resource/IneligibleBlock | This status code indicates that the Customer is ineligible for CDR Data Sharing. | 422 | urn:au-cds:error:cds-all:Resource/Invalid |
| Call Center Block | 451 | urn:dio:error:cds-all:Resource/CallCenterBlock | This status code indicates that the consumer should call the Call Center for further information. | 422 | urn:au-cds:error:cds-all:Resource/Invalid |
| Internal Server Error | 500 | urn:au-cds:error:cds-all:GeneralError/Unexpected | This status code indicates that the server encountered an internal error or misconfiguration. | 500 | urn:au-cds:error:cds-all:GeneralError/Unexpected |
Β
Data Adapter version to CDR version mappingβ
The V0 Data Adapter response for listEnergyAccounts is no longer supported and will be removed from the specification in a future release.
| Data Adapter Version | CDR Version | Transformation details |
|---|---|---|
| ListEnergyAccounts V2 | GetEnergyAccountDetail V4 | This is a 1:1 mapping. No transformation required. |
| ListEnergyAccounts V2 | GetEnergyAccountDetail V3 | Further information on this transformation, see below. |
| ListEnergyAccounts V2 | GetEnergyAccountDetail V2 | See ListEnergyAccounts V1 -> GetEnergyAccountDetail V2 mapping. Also see ListEnergyAccounts V2 -> GetEnergyAccountDetail V3 mapping. |
| ListEnergyAccounts V1 | GetEnergyAccountDetail V4 | Further information on this transformation, see below. |
| ListEnergyAccounts V1 | GetEnergyAccountDetail V3 | This is a 1:1 mapping. No transformation required. |
| ListEnergyAccounts V1 | GetEnergyAccountDetail V2 | Via selecting the first solar feed in tariff rate as the non-stepped amount. Further information on this transformation, see below. |
ListEnergyAccounts V1 -> GetEnergyAccountDetail V4β
GetEnergyAccountDetail V4 introduces:
tariffPeriod.bandedDailySupplyChargesto allow sharing of banded daily supply charges- An optional
periodfield to help support stepped tariff calculations - Changes to
solarFeedInTariffincluding:- Converting
timeVaryingTariffsinto an array to allow representation of multiple feed in tariffs - The addition of a new mandatory
displayNametotimeVaryingTariffs - The addition of two new ENUM values CURRENT and VARIABLE to
scheme
- Converting
If any of these fields are of importance to your business, you should consider implementing V2 of the adapter endpoint. Otherwise, the following upgrade logic will be followed:
tariffPeriod.bandedDailySupplyCharges- If
dailySupplyChargesis notnull, setdailySupplyChargeTypetoSINGLE, setbandedDailySupplyChargestonulland thedailySupplyChargeswill be mapped 1:1 withdailySupplyCharge. Else, setdailySupplyChargeType,bandedDailySupplyChargesanddailySupplyChargestonull.
- If
period- Set
periodtonull.
- Set
solarFeedInTariff.timeVaryingTariffs- Make
timeVaryingTariffsan array and set the first value as the value supplied from the adapter V1. - Set
displayNameas the empty string (""). - Map the
schemethrough 1:1.
- Make
ListEnergyAccounts V2 -> GetEnergyAccountDetail V3β
For downgrade behaviour from adapter V2 to CDR V3, see the mapping logic below:
tariffPeriod.bandedDailySupplyCharges- If the
dailySupplyChargeTypeisSINGLE,bandedDailySupplyChargeswill benulland thedailySupplyChargeswill be mapped 1:1. - If the
dailySupplyChargeTypeisBAND,bandedDailySupplyChargeswill benulland thedailySupplyChargeswill also benull.
- If the
period- All
periodfields returned from the data adapter will be dropped in the CDR response.
- All
solarFeedInTariff.timeVaryingTariffs- The first
timeVaryingTariffsentry in the array will be returned (while dropping thedisplayNamefield). If theschemeisCURRENTorVARIABLE, it will be transformed toOTHER.
- The first
ListEnergyAccounts V1 -> GetEnergyAccountDetail V2β
The following applies for each Solar Feed In Tariff (SFI) on each plan and account,
- A single tariff (i.e., tariffUType = βsingleTariffβ), will be mapped to the first amount entered in V1 planDetail.electricityContract.solarFeedInTariff.singleTariff.rates.
- Time varying tariffs (i.e., tariffUType = "timeVaryingTariff"), will be mapped so that the first solar feed amount will be selected for each V1 solarFeedInTariff.timeVaryingTariff.rates.
The pseudocode below provides further clarification
for a in V1.account:
for p in a.plans:
for sfit in p.planDetails.solarFeedInTariff:
if sfit.tariffUType == 'singleTariff':
sfit.singleTariff.amount = sfit.singleTariff.rates[0]
delete sfit.singleTariff.rates
if sfit.tariffUType == 'timeVaryingTariff':
sfit.timeVaryingTariff.amount = sfit.timeVaryingTariff.rates[0]
delete sfit.timeVaryingTariff.rates
Β
Supplemental Fieldsβ
Beyond attributes which map one-to-one between Data Adapter and Consumer Data Standards fields the following are identified as additional fields specifically with relation to the successful operation of the HaaS environment:
| Name | Description |
|---|---|
accountCustomers[] | An array of relationships between a specified account and one or more Principals. |
accountCustomers[].userId | The User Identifier associated with the specified relationship. |
accountCustomers[].relationship | An enumeration specifying the type of relationship for the account and specified Principal |
accountCustomers[].vulnerable | A boolean specifying whether, in the context of this particular Account and Principal relationship the Principal should be considered a vulnerable customer. |
accountAddress | This attribute contains a |
Endpoint Specific Guidanceβ
- The Data Adapter call is made with an
accountIdsfilter for any call after consent flow is completed. - The array of strings implementation for List Energy Accounts has explode=true so the
accountsIdsparameter will be generated for each array item. - The data adapter should not return any accounts that are not associated with the accountId(s) specified in the request.
List Energy Accounts Optimisation Guidelinesβ
The List Energy Accounts endpoint combines several purposes and CDR endpoints into one call. However, you can still identify the specific purpose of each request. There are three different ways List Energy Accounts can be called, and each determines how much data is returned:
| List Accounts Parameters | Meaning | Occurrence |
|---|---|---|
| No account IDs | Consent Flow | βͺ Consent Flow βͺ HaaS Admin |
| 1 account ID | CDS Detail | ADR data requests |
| > 1 account ID | CDS Basic | ADR data requests |
List Energy Accounts - Consent Flow vs CDS Basicβ
| Adapter Spec | Subfield | Consent flow | energy:accounts.basic:read |
|---|---|---|---|
accountId | n/a | REQUIRED | REQUIRED |
accountNumber | n/a | REQUIRED | OPTIONAL |
accountCustomers LIST | n/a | REQUIRED | n/a |
accountAddress OBJECT | n/a | REQUIRED | OPTIONAL |
status ENUM βͺ CLOSED βͺ OPEN | n/a | REQUIRED | OPTIONAL - if absent, OPEN assumed |
displayName | n/a | REQUIRED | OPTIONAL |
creationDate | n/a | REQUIRED | REQUIRED if status is OPEN |
plans LIST | LIST | REQUIRED | REQUIRED |
nickname | n/a | OPTIONAL | |
servicePointIds βͺ servicePointId βͺ deviceType | REQUIRED βͺ REQUIRED βͺ REQUIRED | REQUIRED (array may be empty) βͺ REQUIRED βͺ REQUIRED | |
planOverview.displayName | REQUIRED if status isOPEN | OPTIONAL | |
planOverview.startDate | n/a | REQUIRED | |
planOverview.endDate | n/a | OPTIONAL | |
planDetail.fuelType | REQUIRED | OPTIONAL |