Introduction

Glow's EUI/Postcode Check is an direct integration verification method that automatically verifies an energy consumer as the occupant of a property using a unique code found on their existing in-home display (IHD).

This method can be fully integrated into your own front-end using the Glow APIs.

Definitions

Term	Definition
Verification	Process whereby a User's smart meters are verified to confirm they are compatible with Hildebrand's ability to retrieve data from them.
Consent	Specific to the Smart Energy Code: formal process to capture permission from the User to retrieve their energy consumption and related data from their smart meters under the Terms and Conditions in place at the time their consent is captured.
MPxN	Meter point identifier, every property has a unique MPxN. MPAN identifies electricity meter, MPRN identifies gas meter.
SECAS	Smart Energy Code Administrator; regulate Hildebrand's ability to offer the service.
DCC	Data Communications Company - manages the smart metering infrastructure in the UK.
DCC Inventory	Holds the details of all smart metering devices against a property.
Terms and Conditions	Hildebrand's Terms and Conditions - acceptance is required for energy consumer onboarding. Approved by SECAS. Version controlled.
User	Individual energy consumer (expected to have a valid smart meter).
IHD	In-home display. Provided by an energy supplier to show energy usage.
CAD	Consumer Access Device. Connects directly to the meter at a property for real time data, and can also be used for verifications. Some IHDs are combined IHD/CAD devices.
PPMID	A Prepayment Meter Interface Device, often integrated with an IHD (see above) for energy tracking and monitoring.
EUI	16-character identifier found on an IHD - sometimes labeled as a GUID or MAC. This is a unique code that can be used for verification.

Background

This document describes how organisations signed up to the Glow Data Service can use the Glow Platform to onboard users and their smart meters via our EUI/Postcode check.

This method relies on the third party's application to:

capture all the registration information required for onboarding from the user

validate the registration information

present the Terms and Conditions to the user in a way that ensures integrity of explicit consent

submit the validated registration information to the Glow Platform via the API

eventually renew the user's consent (from a period of 12 months after the user's initial sign-up, otherwise consent will expire after 18 with no intervention).

Registration information consists of the user's postcode and the EUI of the IHD, CAD or PPMID at their property. If the user does not have one of these devices, they will need to use a different verification method.

Limitations

The EUI/Postcode Check method requires the organisation to have their own front-end to integrate these APIs into in order to facilitate the energy consumer onboarding process.

High-level Process

The below outlines the high-level process for onboarding an energy consumer using the EUI/Postcode check, and the interactions between the energy consumer, organisation application and the Glow Platform.

Verification via EUI/Postcode

Capture EUI and Postcode

Add a step to your onboarding journey to capture the EUI and postcode, to then be used to run an eligibility check as per the following section.

Run an eligibility check

To check whether a provided EUI and postcode combination is valid, use the following Eligibility API. Please note that this API does not require authentication. This call checks the smart meter for compatibility with the service and validates the user input.

Retain the EUI and MPxN that has passed this check to then be used in the Registration step. The EUI in this case can be the full EUI, or just the last 4 digits.

Successful response (status code 200):

{
    "valid": true,
    "status": "OK"
}

Failed response (status code 200):

{
    "valid": false,
    "status": "NOK"
}

The EUI is the long 16 character hexadecimal number printed on the In Home Display or sometimes needs to be read from menus within the display. It may be separated by dashes or colons. For example 70:B3:D5:16:F0:00:03:51.

It is good practice to:

validate hexadecimal numbers on EUI input

validate EUI length after removing any separators (16 characters)

validate UK postcode using external checks and/or regular expressions

strip white space from EUI only

force EUI to uppercase

For more information on smart meter eligibility support via API see https://api.glowmarkt.com/api-docs/v0-1/eligibility/

Terms and Conditions

At some point prior to onboarding — either before or after the verification step — the energy consumer must accept or deny the service Terms and Conditions. For a guide on managing this, see our Terms and Conditions APIs and Management documentation.

Onboarding

The Registration API assumes that Terms and Conditions have been presented through the user interface, the postcode and EUI information has been validated and the tcId is for the Terms and Conditions that were presented (which should be the current version).

The username will be the unique identifier within the third party system and can take the form of any string value. This is used in tracing the audit of the natural person associated with the User account and can be used in calls to look up the Glow UserId. It is also displayed and searchable within in the Support Portal. In essence this is a foreign key.

Normally the username is set to be an email address, and if it is, then emails can be sent to renew consent and provide a user login using the Glow identity and access management (IAM) services. In this tutorial it is assumed that this functionality is not being used.

A successful response, will have a 200 status code, and the payload looks like this:

{
  "userId": "UUID",
  "applicationId": "3e3e5463-afbd-4f7a-b57f-365e886cf914",
  "virtualEntity": {
    "veId": "4447b17c-ab62-491c-8085-9ac2b6206346"
  }
}

The API requires the API keys which can be found in the Development Portal. For more information on how to authenticate, please refer to the Authentication section below.

With regards to the payload, the full explanation of each field is provided here:

Field	Required/Optional	Explanation
name	optional	Assume that this will not be used.
email	optional	Assume that this will not be used.
username	required	The username is the unique reference in the Glow Platform. This is the foreign key reference.
directoryId	required	This field describes the IAM directory that will be used by the 3rd party. Log in to the Developer Portal and use the directory listed under the application definition.
postcode	required	This is the postcode that the user submitted along with their IHD/CAD EUI and will be used to identify and verify their meter point.
eui	required	The user's IHD/CAD EUI. As prementioned, along with the postcode this will be used to verify and identify the user's meter point. The EUI in this case can be the full or just the last 4 digits of the EUI.
tcId	required	The UUID indicating the terms and conditions. Use the /current call to obtain the identifier to include.
reference	required	The clear text reference of the terms and conditions
data	optional	Any additional data as a JSON object to be stored against the UserId, that is pertinent to them accepting the terms and conditions.
accepted	required	The datetime the terms and conditions were accepted.

When the API is submitted the system will check all the provided information and if it finds it to be valid, it will register the user. Once completed smart meter data will automatically be requested and the historical data will be stored on Resources against the UserId. The timing of this process is asynchronous.

The UserId should be stored by the third party application, although it can be looked up in the future against the foreign key.

For more API details on onboarding see https://api.glowmarkt.com/api-docs/v0-1/provisioning/

Bonus - determining dual fuel and meter point details

This section describes how the API can be used to determine the type of meter(s) a user has on premises. It is populated once data starts to return from the metering infrastructure. In most cases the API functions within several seconds after registration is complete but should be treated as asynchronous.

The UserId that was created in the registration step must be used in the header along with the API keys turned into Authorization header. For example:

The response of this API is an array of devices. In most cases there will be one or two entries; one entry for the electricity meter and a second for the gas meter. However, if the end user has a CAD device or multiple locations registered to their account, they may have more entries in the array. The following indicate a smart meter sourced by the DCC.

"protocol": "dcc"

"deviceTypeId": "51d5ac18-4f7d-494d-a6b0-371742222d5c" = Electricity Meter

"deviceTypeId": "81825a67-c205-434f-8c56-6fff5faafcde" = Gas Meter

You can use the MPAN or MPRN fields to display which specific meter is in context for device actions.

[
  {
    "protocol": {
      "protocol": "dcc",
      "sensors": [
        {
          "resourceTypeId": "e3a5db34-6e0c-4221-9653-8d33e27511ba",
          "protocolId": "0702:04:00",
          "resourceId": "9bb47086-39b1-4cf7-b973-c914759fdd2c"
        },
        {
          "resourceTypeId": "78859e39-611e-4e84-a402-1d4460abcb56",
          "protocolId": "0702:04:00",
          "resourceId": "9663f171-ba07-499e-9870-4bf2342fae0b"
        }
      ]
    },
    "parentHardwareId": [
    ],
    "tags": [
      "3**************E",
      "1***********7"
    ],
    "hardwareIdNames": [
      "MPAN",
      "EUI"
    ],
    "active": true,
    "deviceTypeId": "51d5ac18-4f7d-494d-a6b0-371742222d5c",
    "ownerId": "3ff6ca6d-e6a4-47cb-afc8-251177130e69",
    "hardwareIds": {
      "MPAN": "1***********7",
      "EUI": "3**************E"
    },
    "hardwareId": "3**************E",
    "description": "Electricity Smart Meter (DCC sourced)",
    "deviceId": "8ce0ab80-b0f1-4bd2-a6cd-49beb0d42517",
    "updatedAt": "2020-11-11T18:46:59.804Z",
    "createdAt": "2020-11-11T18:46:59.804Z"
  },
  {
    "protocol": {
      "protocol": "dcc",
      "sensors": [
        {
          "resourceTypeId": "a6b95f41-771d-4bd2-99f4-93ee43c38f5a",
          "protocolId": "0702:04:00",
          "resourceId": "19c0f2b4-cea7-4c4e-aba2-76472dc478d8"
        },
        {
          "resourceTypeId": "08ab415f-d851-423f-adf4-c2b1e0529e27",
          "protocolId": "0702:04:00",
          "resourceId": "be5dfe71-8f53-4a03-ad23-1bde5a63afea"
        }
      ]
    },
    "parentHardwareId": [
    ],
    "tags": [
      "3**************F",
      "3********3",
      "1***********7"
    ],
    "hardwareIdNames": [
      "MPRN",
      "MPAN",
      "EUI"
    ],
    "active": true,
    "deviceTypeId": "81825a67-c205-434f-8c56-6fff5faafcde",
    "ownerId": "54091510-4eaa-43d5-b33b-e9fc2f7d576d",
    "hardwareIds": {
      "MPRN": "3********3",
      "MPAN": "1***********7",
      "EUI": "30EB5AFFFF325DCF"
    },
    "hardwareId": "3**************F",
    "description": "Gas Meter (DCC sourced)",
    "deviceId": "6bf647e2-aeee-4795-8804-c8bf48748dc7",
    "updatedAt": "2020-11-11T18:47:14.100Z",
    "createdAt": "2020-11-11T18:47:14.100Z"
  }
]

EUI/Postcode Check

Introduction#

Definitions#

Background#

Limitations#

High-level Process#

Verification via EUI/Postcode#

Capture EUI and Postcode#

Run an eligibility check#

Terms and Conditions#

Onboarding#

Bonus - determining dual fuel and meter point details#