Get Energy Accounts V1

This page documents version 1 of the Get Energy Account end point.

Data Holders MAY go-live on November 15 2022 with this version.
Data Holders MUST implement Get Energy Accounts v2 by April 7th 2023.
Data Holders MAY decommission Get Energy Accounts v1 as soon as Get Energy Accounts v2 is supported.
Data Holders MUST provide values for all mandatory fields and select reasonable default values if the data is not available for closed accounts

This version is to be ceased to be called by data recipients when the Data Holder supports Get Energy Accounts v2.

Get Energy Accounts

Code samples

GET /energy/accounts HTTP/1.1

Accept: application/json
x-v: string
x-min-v: string
x-fapi-interaction-id: string
x-fapi-auth-date: string
x-fapi-customer-ip-address: string
x-cds-client-headers: string

var headers = {
  'Accept':'application/json',
  'x-v':'string',
  'x-min-v':'string',
  'x-fapi-interaction-id':'string',
  'x-fapi-auth-date':'string',
  'x-fapi-customer-ip-address':'string',
  'x-cds-client-headers':'string'

};

$.ajax({
  url: '/energy/accounts',
  method: 'get',

  headers: headers,
  success: function(data) {
    console.log(JSON.stringify(data));
  }
})

GET /energy/accounts

Obtain the list of energy accounts available under the authorised consent

Endpoint Version


Version	1

Parameters

Name	In	Type	Required	Description
page	query	PositiveInteger	optional	Page of results to request (standard pagination)
page-size	query	PositiveInteger	optional	Page size to request. Default is 25 (standard pagination)
x-v	header	string	mandatory	Version of the API end point requested by the client. Must be set to a positive integer. The data holder should respond with the highest supported version between x-min-v and x-v. If the value of x-min-v is equal to or higher than the value of x-v then the x-min-v header should be treated as absent. If all versions requested are not supported then the data holder must respond with a 406 Not Acceptable. See HTTP Headers
x-min-v	header	string	optional	Minimum version of the API end point requested by the client. Must be set to a positive integer if provided. The data holder should respond with the highest supported version between x-min-v and x-v. If all versions requested are not supported then the data holder must respond with a 406 Not Acceptable.
x-fapi-interaction-id	header	string	optional	An [RFC4122] UUID used as a correlation id. If provided, the data holder must play back this value in the x-fapi-interaction-id response header. If not provided a [RFC4122] UUID value is required to be provided in the response header to track the interaction.
x-fapi-auth-date	header	string	conditional	The time when the customer last logged in to the Data Recipient Software Product as described in [FAPI-R-Draft]. Required for all resource calls (customer present and unattended). Not required for unauthenticated calls.
x-fapi-customer-ip-address	header	string	optional	The customer's original IP address if the customer is currently logged in to the data recipient. The presence of this header indicates that the API is being called in a customer present context. Not to be included for unauthenticated calls.
x-cds-client-headers	header	Base64	conditional	The customer's original standard http headers Base64 encoded, including the original User Agent header, if the customer is currently logged in to the data recipient. Mandatory for customer present calls. Not required for unattended or unauthenticated calls.

Example responses

200 Response

{
  "data": {
    "accounts": [
      {
        "accountId": "string",
        "accountNumber": "string",
        "displayName": "string",
        "creationDate": "string",
        "plans": [
          {
            "nickname": "string",
            "servicePointIds": [
              "string"
            ],
            "planOverview": {
              "displayName": "string",
              "startDate": "string",
              "endDate": "string"
            }
          }
        ]
      }
    ]
  },
  "links": {
    "self": "string",
    "first": "string",
    "prev": "string",
    "next": "string",
    "last": "string"
  },
  "meta": {
    "totalRecords": 0,
    "totalPages": 0
  }
}

Responses

Status	Meaning	Description	Schema
200	OK	Successful response	EnergyAccountListResponse
400	Bad Request	The following error codes MUST be supported: 400 - Invalid Field 400 - Invalid Page Size 400 - Invalid Version	ErrorListResponse
406	Not Acceptable	The following error codes MUST be supported: 406 - Unsupported Version	ErrorListResponse
422	Unprocessable Entity	The following error codes MUST be supported: 422 - Invalid Page	ErrorListResponse

Response Headers

Status	Header	Type	Description
200	x-v	string	none
200	x-fapi-interaction-id	string	none
400	x-fapi-interaction-id	string	none
406	x-fapi-interaction-id	string	none
422	x-fapi-interaction-id	string	none

EnergyAccountListResponse

{
  "data": {
    "accounts": [
      {
        "accountId": "string",
        "accountNumber": "string",
        "displayName": "string",
        "creationDate": "string",
        "plans": [
          {
            "nickname": "string",
            "servicePointIds": [
              "string"
            ],
            "planOverview": {
              "displayName": "string",
              "startDate": "string",
              "endDate": "string"
            }
          }
        ]
      }
    ]
  },
  "links": {
    "self": "string",
    "first": "string",
    "prev": "string",
    "next": "string",
    "last": "string"
  },
  "meta": {
    "totalRecords": 0,
    "totalPages": 0
  }
}

Properties

Name	Type	Required	Description
data	object	mandatory	none
» accounts	[EnergyAccount]	mandatory	Array of accounts
links	LinksPaginated	mandatory	none
meta	MetaPaginated	mandatory	none

EnergyAccount

{
  "accountId": "string",
  "accountNumber": "string",
  "displayName": "string",
  "creationDate": "string",
  "plans": [
    {
      "nickname": "string",
      "servicePointIds": [
        "string"
      ],
      "planOverview": {
        "displayName": "string",
        "startDate": "string",
        "endDate": "string"
      }
    }
  ]
}

Properties

allOf

Name	Type	Required	Description
anonymous	EnergyAccountBase	mandatory	none

and

Name	Type	Required	Description
anonymous	object	mandatory	The array of plans containing service points and associated plan details
» plans	[object]	mandatory	The array of plans containing service points and associated plan details
»» nickname	string	optional	Optional display name for the plan provided by the customer to help differentiate multiple plans
»» servicePointIds	[string]	mandatory	An array of servicePointIds, representing NMIs, that this plan is linked to. If there are no service points allocated to this plan then an empty array would be expected
»» planOverview	object	mandatory	none
»»» displayName	string	optional	The name of the plan if one exists
»»» startDate	DateString	mandatory	The start date of the applicability of this plan
»»» endDate	DateString	optional	The end date of the applicability of this plan

EnergyAccountBase

{
  "accountId": "string",
  "accountNumber": "string",
  "displayName": "string",
  "creationDate": "string"
}

Properties

Name	Type	Required	Description
accountId	string	mandatory	The ID of the account. To be created in accordance with CDR ID permanence requirements
accountNumber	string	optional	Optional identifier of the account as defined by the data holder. This must be the value presented on physical statements (if it exists) and must not be used for the value of accountId
displayName	string	optional	An optional display name for the account if one exists or can be derived. The content of this field is at the discretion of the data holder
creationDate	DateString	mandatory	The date that the account was created or opened

LinksPaginated

{
  "self": "string",
  "first": "string",
  "prev": "string",
  "next": "string",
  "last": "string"
}

Properties

Name	Type	Required	Description
self	URIString	mandatory	Fully qualified link that generated the current response document
first	URIString	conditional	URI to the first page of this set. Mandatory if this response is not the first page
prev	URIString	conditional	URI to the previous page of this set. Mandatory if this response is not the first page
next	URIString	conditional	URI to the next page of this set. Mandatory if this response is not the last page
last	URIString	conditional	URI to the last page of this set. Mandatory if this response is not the last page

MetaPaginated

{
  "totalRecords": 0,
  "totalPages": 0
}

Properties

Name	Type	Required	Description
totalRecords	NaturalNumber	mandatory	The total number of records in the full set. See pagination.
totalPages	NaturalNumber	mandatory	The total number of pages in the full set. See pagination.