Skip to main content

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​

TitleStatus CodeAdapter URN - Error CodeDetailCDR Status CodeCDR URN - Error Code
Invalid Field400urn: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.
Invalid format supplied for accountIds.

500urn:au-cds:error:cds-all:GeneralError/Unexpected
Invalid Header400urn: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.
x-fapi-interaction-id - If supplied, it must be a Universal Unique Identifier (UUID) and compliant with RFC4122. If not supplied, a compliant value is autogenerated.
Invalid format supplied for
x-fapi-interaction-id.

500urn:au-cds:error:cds-all:GeneralError/Unexpected
Expected Error400urn:au-cds:error:cds-all:GeneralError/ExpectedThis status code indicates that the Expected Error has encountered.500urn:au-cds:error:cds-all:GeneralError/Unexpected
Invalid Resource404urn:au-cds:error:cds-all:Resource/InvalidThe requested resource identifier is permanently unavailable.404urn:au-cds:error:cds-all:Resource/Invalid
Legal Block451urn:dio:error:cds-all:Resource/LegalBlockThis status code indicates that the server is denying access to the resource as a consequence of a legal demand.422urn:au-cds:error:cds-all:Resource/Unavailable
Ineligible Block451urn:dio:error:cds-all:Resource/IneligibleBlockThis status code indicates that the Customer is ineligible for CDR Data Sharing.422urn:au-cds:error:cds-all:Resource/Invalid
Call Center Block451urn:dio:error:cds-all:Resource/CallCenterBlockThis status code indicates that the consumer should call the Call Center for further information.422urn:au-cds:error:cds-all:Resource/Invalid
Internal Server Error500urn:au-cds:error:cds-all:GeneralError/UnexpectedThis status code indicates that the server encountered an internal error or misconfiguration.500urn:au-cds:error:cds-all:GeneralError/Unexpected

Get Energy Account Detail​

Loading...

Β 

CDR Error Mapping​

TitleStatus CodeAdapter URN - Error CodeDetailCDR Status CodeCDR URN - Error Code
Invalid Field400urn: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.
Invalid format supplied for accountIds.

500urn:au-cds:error:cds-all:GeneralError/Unexpected
Invalid Header400urn: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.
x-fapi-interaction-id - If supplied, it must be a Universal Unique Identifier (UUID) and compliant with RFC4122. If not supplied, a compliant value is autogenerated.
Invalid format supplied for
x-fapi-interaction-id.

500urn:au-cds:error:cds-all:GeneralError/Unexpected
Expected Error400urn:au-cds:error:cds-all:GeneralError/ExpectedThis status code indicates that the Expected Error has encountered.500urn:au-cds:error:cds-all:GeneralError/Unexpected
Invalid Resource404urn:au-cds:error:cds-all:Resource/InvalidThe requested resource identifier is permanently unavailable.404urn:au-cds:error:cds-all:Resource/Invalid
Legal Block451urn:dio:error:cds-all:Resource/LegalBlockThis status code indicates that the server is denying access to the resource as a consequence of a legal demand.422urn:au-cds:error:cds-all:Resource/Unavailable
Ineligible Block451urn:dio:error:cds-all:Resource/IneligibleBlockThis status code indicates that the Customer is ineligible for CDR Data Sharing.422urn:au-cds:error:cds-all:Resource/Invalid
Call Center Block451urn:dio:error:cds-all:Resource/CallCenterBlockThis status code indicates that the consumer should call the Call Center for further information.422urn:au-cds:error:cds-all:Resource/Invalid
Internal Server Error500urn:au-cds:error:cds-all:GeneralError/UnexpectedThis status code indicates that the server encountered an internal error or misconfiguration.500urn:au-cds:error:cds-all:GeneralError/Unexpected

Β 


Data Adapter version to CDR version mapping​

Note

The V0 Data Adapter response for listEnergyAccounts is no longer supported and will be removed from the specification in a future release.

Data Adapter VersionCDR VersionTransformation details
ListEnergyAccounts V2GetEnergyAccountDetail V4This is a 1:1 mapping. No transformation required.
ListEnergyAccounts V2GetEnergyAccountDetail V3Further information on this transformation, see below.
ListEnergyAccounts V2GetEnergyAccountDetail V2See ListEnergyAccounts V1 -> GetEnergyAccountDetail V2 mapping. Also see ListEnergyAccounts V2 -> GetEnergyAccountDetail V3 mapping.
ListEnergyAccounts V1GetEnergyAccountDetail V4Further information on this transformation, see below.
ListEnergyAccounts V1GetEnergyAccountDetail V3This is a 1:1 mapping. No transformation required.
ListEnergyAccounts V1GetEnergyAccountDetail V2Via 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.bandedDailySupplyCharges to allow sharing of banded daily supply charges
  • An optional period field to help support stepped tariff calculations
  • Changes to solarFeedInTariff including:
    • Converting timeVaryingTariffs into an array to allow representation of multiple feed in tariffs
    • The addition of a new mandatory displayName to timeVaryingTariffs
    • The addition of two new ENUM values CURRENT and VARIABLE to scheme

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 dailySupplyCharges is not null, set dailySupplyChargeType to SINGLE, set bandedDailySupplyCharges to null and the dailySupplyCharges will be mapped 1:1 with dailySupplyCharge. Else, set dailySupplyChargeType, bandedDailySupplyCharges and dailySupplyCharges to null.
  • period
    • Set period to null.
  • solarFeedInTariff.timeVaryingTariffs
    • Make timeVaryingTariffs an array and set the first value as the value supplied from the adapter V1.
    • Set displayName as the empty string ("").
    • Map the scheme through 1:1.

ListEnergyAccounts V2 -> GetEnergyAccountDetail V3​

For downgrade behaviour from adapter V2 to CDR V3, see the mapping logic below:

  • tariffPeriod.bandedDailySupplyCharges
    • If the dailySupplyChargeType is SINGLE, bandedDailySupplyCharges will be null and the dailySupplyCharges will be mapped 1:1.
    • If the dailySupplyChargeType is BAND, bandedDailySupplyCharges will be null and the dailySupplyCharges will also be null.
  • period
    • All period fields returned from the data adapter will be dropped in the CDR response.
  • solarFeedInTariff.timeVaryingTariffs
    • The first timeVaryingTariffs entry in the array will be returned (while dropping the displayName field). If the scheme is CURRENT or VARIABLE, it will be transformed to OTHER.

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:

NameDescription
accountCustomers[]An array of relationships between a specified account and one or more Principals.
accountCustomers[].userIdThe User Identifier associated with the specified relationship.
accountCustomers[].relationshipAn enumeration specifying the type of relationship for the account and specified Principal
accountCustomers[].vulnerableA 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 CommonAddressV1 object allowing for an address to specified in either Simple or PAF format.

The primary purpose of this attribute is to provide a presentation level address for consent flow during account selection.

Endpoint Specific Guidance​

  • The Data Adapter call is made with an accountIds filter for any call after consent flow is completed.
  • The array of strings implementation for List Energy Accounts has explode=true so the accountsIds parameter 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 ParametersMeaningOccurrence
No account IDsConsent Flow
β–ͺ Consent Flow
β–ͺ HaaS Admin
1 account IDCDS DetailADR data requests
> 1 account IDCDS BasicADR data requests
Adapter SpecSubfieldConsent flowenergy:accounts.basic:read
accountIdn/aREQUIREDREQUIRED
accountNumbern/aREQUIREDOPTIONAL
accountCustomers LISTn/aREQUIREDn/a
accountAddress OBJECTn/aREQUIREDOPTIONAL
status ENUM
β–ͺ CLOSED
β–ͺ OPEN
n/aREQUIREDOPTIONAL - if absent, OPEN assumed
displayNamen/aREQUIREDOPTIONAL
creationDaten/aREQUIREDREQUIRED if status is OPEN
plans LISTLISTREQUIREDREQUIRED
nicknamen/aOPTIONAL
servicePointIds
β–ͺ servicePointId
β–ͺ deviceType
REQUIRED
β–ͺ REQUIRED
β–ͺ REQUIRED
REQUIRED (array may be empty)
β–ͺ REQUIRED
β–ͺ REQUIRED
planOverview.displayNameREQUIRED if status isOPENOPTIONAL
planOverview.startDaten/aREQUIRED
planOverview.endDaten/aOPTIONAL
planDetail.fuelTypeREQUIREDOPTIONAL