Requests

Detailed information on how to invoke the API is available in the specification section.

Retrieve Consented MPxNs

Customer API resource that allow a customer to obtain a list of all his consented properties.

Endpoint GET Retrieve-Consented-MPxNs

This endpoint has X-API-Key as Header Parameter and the user can submit query parameters, that are described further below.

The validations described in the Authentication section will apply.

Request Query parameters

The URL can contain two optionals query parameters - startAt and maxResults.

startAt : Optional. Index of the first element of the list of MPxNs to be included in the response. Default is 0.
maxResults : Optional. Maximum number of MPxNs to be included in the response. Default is 100 and maximum value allowed is 100.

Response body

If the request passes the authentication and syntactic validations, a success response is returned.

Success response example - Customer has active consents

JSON "resource": "/", "responseTimestamp": "2022-04-10T17:07:01.580Z", "startAt": 0, "maxResults": 100, "total": 13, "entries": [ "1234567891026", "1234567891000", "1234567891016", "1234567891018", "1234567891022", "1234567891012", "1234567891024", "1234567891004", "1234567891034", "1234567891032", "1234567891008", "1234567891002", "1234567891010" ]

Success response example - Customer has NO active consents

JSON "resource": "/", "responseTimestamp": "2022-04-10T17:07:01.580Z", "startAt": 0, "maxResults": 100, "total": 0, "entries": []

Errors in authorization or general validation for all inputs will result in a response with an error code and informative message.

Error response

JSON "errors": [ { "code": 400, "message": "Parameter startAt must be an integer." } ]

Processing

The request is authenticated and the query parameters validated. If any of these authentication and validation rules fail, an error is returned and the process ends here.

Otherwise, the system will retrieve an up-to-date list of all active consent's MPxNs ordered by consent's date (from the most recent to the least recent).

For the response, this information is organized in a list ordered in the same way, being the first MPxN shown correspondent to the index, specified by startAt query parameter, of the retrieved system's list. If startAt parameter is not specified, the list starts with the first MPxN returned by the system. The reponse list is up to the number specified in maxResults or its default value, if the query parameter was not specified.

Error scenarios

Possible errors and corresponding messages are included in the following table.

Scenario	Error Code	Message
Absent or invalid API Key	403	User is not authorized to access this resource with an explicit deny.
startAt is specified, but it is not an integer	400	Parameter startAt must be an integer.
maxResults is specified, but it is not an integer	400	Parameter maxResults must be an integer.

Retrieve Available Utilities

Customer API resource that allow a customer to obtain a list of the utilities (electricity and/or gas) with associated smart meters in one of his consented properties.

Endpoint GET Retrieve-Available-Utilities

This endpoint has X-API-Key as Header Parameter and the user can submit a path parameter, that is described further below.

The validations described in the Authentication section will apply.

Warning

When making this request, please keep in mind that when ALL the update frequency fields were specified as "never" in the consent process, a 403 error will occur and the data cannot be obtained. If this was the case, the user can change the choices made in consent process, by using the set-meter-update-frequency endpoint.

Tip

The user only needs to change, in set-meter-update-frequency endpoint, the update frequency corresponding to the utility from which he wants to get info.

Request Path parameter

The URL must contain the mandatory path parameter - MPxN.

mpxn : Mandatory. MPxN (MPAN or MPRN) associated with the target HAN. Must be a value between 1 and 13 digits.

Response body

If the request passes the authentication and syntactic validation, a success response is returned.

Success response

JSON "resource": "/mpxn/1234567891012", "responseTimestamp": "2022-04-10T17:07:01.580Z", "entries": [ "electricity", "gas" ]

Errors in authorization or validation of path parameter will result in a response with an error code and informative message.

Error response

JSON "errors": [ { "code": 400, "message": "An MPxN must be provided, and must be a value between 1 and 13 digits." } ]

Processing

The request is authenticated and the path parameter validated. If any of these authentication and validation rules fail, an error is returned and the process ends here.

Otherwise, the corresponding HAN is obtained, based in the provided MPxN. Then, an active consent record is search for the corresponding HAN. If there is no active consent for this HAN, an error will returned and the process ends here.

Else, the process continues and ends successfuly returning a list of the utilities associated with the devices (ESMES and GSMES) in that HAN.

Error scenarios

Possible errors and corresponding messages are included in the following table.

Scenario	Error Code	Message
Absent or invalid API Key	403	User is not authorized to access this resource with an explicit deny.
Absent MPxN or not a value between 1 and 13 digits.	400	An MPxN must be provided, and must be a value between 1 and 13.
No record of a consent with status active for the HAN of the specified MPxN to this customer	403	Consent for the given MPxN not found.
Absent update frequencies for all the fields.	403	Consent for the given MPxN does not have update frequencies set.

Tip

For this last Error, check warning to see how to solve it.

Retrieve Reading Types

Customer API resource that allow a customer to obtain a list of types of data (consumption, production, tariff) available for a specific utility (electricity or gas) in one of their consented properties.

Endpoint GET Retrieve-Reading-Types

This endpoint has X-API-Key as Header Parameter and the user can submit path parameters, that are described further below.

The validations described in the Authentication section will apply.

Warning

When making this request, please kepp in mind that when ALL the update frequency fields were specified as "never" in the consent process, a 403 error will occur and the data cannot be obtained. If this was the case, the user can change the choices made in consent process, by using the set-meter-update-frequency endpoint.

Tip

The user only needs to change, in set-meter-update-frequency endpoint, the update frequency corresponding to the reading type from which he wants to get info.

Request Path parameters

The URL must contain the mandatory path parameters - MPxN and Utility type.

mpxn : Mandatory. MPxN (MPAN or MPRN) associated with the target HAN. Must be a value between 1 and 13 digits.

Note that, this mpxn is only used to identify the corresponding HAN. This means the Customer may use, for example, an MPRN when requesting information for the utility 'electricity'.

utility : Mandatory. Type of utility for which the available type(s) of data is being requested. One of: electricity; gas.

Response body

If the request passes the authentication and syntactic validations, a success response is returned.

Success example for utility type - Electricity

JSON "resource": "/mpxn/1234567891012/utility/electricity", "responseTimestamp": "2022-04-10T17:07:01.580Z", "devices": [ { "deviceId": "01-0A-00-00-00-00-FF-03", "availableDataTypes": [ "consumption", "tariff" ] }, { "deviceId": "90-B3-D5-1F-30-01-00-00", "availableDataTypes": [ "production" ] } ]

Success example for utility type - Gas

JSON "resource": "/mpxn/1234567891012/utility/gas", "responseTimestamp": "2022-04-10T17:07:01.580Z", "devices": [ { "deviceId": "01-0A-00-00-00-00-FF-03", "availableDataTypes": [ "consumption", "tariff" ] } ]

Errors in authorization or validation of path parameters will result in a response with an error code and informative message.

Error response

JSON "errors": [ { "code": 400, "message": "A utility type must be provided and must be one of: electricity, gas." } ]

Processing

The request is authenticated and the path parameters validated. If any of these authentication and validation rules fail, an error is returned and the process ends here.

Otherwise, the corresponding HAN is obtained, based in the provided MPxN. Then, an active consent record is search for the corresponding HAN. If there is no active consent for this HAN, an error will be returned and the process ends here.

Else, the process continues and reading type records are searched for the devices (ESMES and GSMES) in that HAN for the utility type provided in request. If no record is found for the HAN + utility, an error is returned and the process ends here.

Otherwise, the process ends successfully by returning a list of the reading types associated with the devices in that HAN for the given utility type.

Error scenarios

Possible errors and corresponding messages are included in the following table.

Scenario	Error Code	Message
Absent or invalid API Key	403	User is not authorized to access this resource with an explicit deny.
Absent MPxN or not a value between 1 and 13 digits.	400	An MPxN must be provided, and must be a value between 1 and 13.
No record of a consent with status active for the HAN of the specified MPxN to this customer	403	Consent for the given MPxN not found.
The specified utility is not available for the requested HAN	404	There is no available information for the specified utility in the HAN associated with the received MPxN.
Absent update frequencies for all the fields.	403	Consent for the given MPxN does not have update frequencies set.

Tip

For this last Error, check warning to see how to solve it.

Set Meter Update Frequency

Customer API resource that allow a customer to set, for specific meter in one of their consented HANs, frequency of the update of the import (in case of an electricity/gas meter) and export (in case of an electricity meter) data .

Important Info

If during consent of a specific MPXN, the customer did not indicate any value for getHistoryData parameter or chose it to be false, but later wants to change this parameter and get data prior to the consent:

There is no specific endpoint for this, however the customer just have to re-consent the MPXN ( ATTENTION - It is NOT necessary to withdraw consent before this), but now with the value getHistoryData to true.

This action will be enough to trigger the process of getting historical data.

Endpoint PUT set-meter-update-frequency

This endpoint has X-API-Key as Header Parameter and the user must submit at least the mandatory body parameter, all body parameters are described further below.

The validations described in the Authentication section will apply.

Request Body parameters

The JSON request body must contain the mandatory body parameter - deviceID - and at least one of the optional ones - importUpdateFrequency and exportUpdateFrequency.

deviceID : Mandatory. Device ID of the meter whose update frequencies are to be set.
importUpdateFrequency : Optional. Determines the frequency of data updates for electric/gas meters in a consented HAN. One of: never, 3h, 6h, 12h, daily, weekly, monthly.
exportUpdateFrequency : Optional. Determines the frequency of data updates for electric meters in a consented HAN. One of: never, 3h, 6h, 12h, daily, weekly, monthly.

Example

JSON "deviceID": "01-02-03-04-05-06-07-08", "importUpdateFrequency": "12h"

Response body

If the request passes the authentication and syntactic validations, a success response is returned.

Success response example

JSON "resource": "/set-meter-update-frequency", "responseTimestamp": "2021-04-10T17:07:01.580Z", "status": { "code": "OK", "message": "Request to reset update frequency for the meter was successful." }

Errors in authorization, validation of body parameters or in the process of the request will result in a response with an error code and informative message.

Error response

JSON "errors": [ { "code": 400, "message": "The specified deviceID is not associated with a valid MPxN for the requested update frequency type." } ]

Processing

The request is authenticated and the body parameters validated. If any of these authentication and validation rules fail, an error is returned and the process ends here.

Otherwise, the process continues and validates if the deviceID is a meter, and depending on the update frequency specified in body validates if the target meter has an associated import_mpxn (if importUpdateFrequency was specified) or has an associated export_mpan (if exportUpdateFrequency was specified). If any of these validations fails, an error is returned and the process ends here.

Otherwise, the process ends successfuly and the system will set the specified update frequency for the update type requested.

Error scenarios

Possible errors and corresponding messages are included in the following table.

Scenario	Error Code	Message
Absent or invalid API Key	403	User is not authorized to access this resource with an explicit deny.
Customer is not authorized to change update frequencies	403	User is not authorized to access this resource with an explicit deny.
Empty request body or deviceID missing or no update frequency specified	400	One device ID and at least one update frequency must be provided.
There is no record of a device with the specified deviceID	404	There is no available information of meters associated with the given device ID.
Specified deviceID does not correspond to a meter	400	The specified deviceID does not correspond to a meter.
Target meter does not have an associated MPxN (import_mpxn or export_mpan) corresponding to the requested update frequency (importUpdateFrequency or exportUpdateFrequency)	404	The specified deviceID is not associated with a valid MPxN for the requested update frequency type.
There is no record of an active consent for the HAN of the specified meter	403	Consent for the property of the target meter not found.
ImportUpdateFrequency or exportUpdateFrequency is specified and is not one of: never, 3h, 6h, 12h, daily, weekly, monthly	400	Parameter "parameter-name" must be one of: never, 2h, 3h, 6h, 12h, daily, weekly, monthly.

Find MPxN, Retrieve MPxN availability

This API resource is used to verify the accessibility of a given MPxN (MPAN or MPRN). For SMETS meters, the MPxN(MPAN or MPRN) is used to determine whether the Home Area Network (HAN) and its connected devices are accessible via the DCC or Secure. For AMR/HH meters, the MPxN is checked against the n3rgy inventory to confirm whether devices are registered, indicating that data is accessible via n3rgy.

Endpoint GET Retrieve-MPxN-availability

This endpoint has X-API-Key as Header Parameter and the user can submit a path parameter, that is described further below.

The validations described in the Authentication section will apply.

Request Path parameter

The URL must contain the mandatory path parameter - MPxN.

mpxn : Mandatory. MPxN (MPAN or MPRN) whose accessibility is to be verified. It must be a value between 1 and 13 digits.

Response body

If the request passes the authentication and syntactic validations, a success response is returned.

DCC success example

JSON "resource": "/find-mpxn/1234567891000", "responseTimestamp": "2022-04-10T17:07:01.580Z", "mpxn": "1234567891000", "deviceType": "ESME", "deviceId": "1C-23-4F-00-00-00-A9-00", "deviceStatus": "Commissioned", "deviceManufacturer": "106C", "deviceModel": "10E2A100", "deviceGbcsVersion": "3.2", "deviceFirmwareVersion": "0314B600", "smetsChtsVersion": "V4.2", "propertyFilter": { "postCode": "C2A 2EE", "addressIdentifier": "Address" }

AMR success example

JSON "resource": "/find-mpxn/1234567891000", "responseTimestamp": "2022-04-10T17:07:01.580Z", "mpxn": "1234567891000", "deviceId": "1580000279222_H14C03484", "deviceType": "ESME", "deviceManufacturer": "Horstmann S123A03 20-100a Single Phase R", "smso": "ENERGYASSETS", "meterSerialNumber": "H14C03484", "deviceModel": "Horstmann S123A03 20-100a Single Phase R", "exportMPAN": "1580000279222", "importMPxN": "1580000279223", "postCode": "AB12 3CD", "address": "123 Example Street, Sampletown", "deviceStatus": "Commissioned", "hanId": "HAN123456789", "commissionedDate": "2023-05-10T08:15:30Z", "firmwareVersion": "FW-1.0.0"

Secure success example

JSON "resource": "/find-mpxn/1234567891002", "responseTimestamp": "2022-04-10T17:07:01.580Z", "mpxn": "1234567891002", "deviceType": "ESME", "deviceId": "1C-23-4F-00-00-00-A9-01", "deviceStatus": "N/A" "deviceManufacturer": "Secure" "deviceModel": "N/A" "deviceGbcsVersion": "N/A" "deviceFirmwareVersion": see Note further below , "smetsChtsVersion": "V1.2" "propertyFilter": { "postCode": "N/A", "addressIdentifier": "N/A" }

Note

The message allowing to check the availability of the meter in Secure's environment will return the information AppVersion that will be displayed in the property deviceFirmwareVersion.

Errors in authorization or validation of path parameter will result in a response with an error code and informative message.

Error response

JSON "errors": [ { "code": 404, "message": "There is no available information of meters associated with the received MPxN." } ]

Processing

The request is authenticated and the path parameter validated. If any of these authentication and validation rules fail, an error is returned and the process ends here.

Otherwise, the system will retrieve up-to-date information on the submitted MPxN from one of the SMSOs. If no record of the MPxN exists, or if it is not associated with a meter in a HAN, an error is returned and the process ends here.

If the system successfully receives data of a HAN containing the submitted MPxN, but only with one device associated, an error is returned and the process ends here.

Else, returns the essential device information associated with the given MPxN.

Error scenarios

Possible errors and corresponding messages are included in the following table.

Scenario	Error Code	Message
Absent or invalid API Key	403	User is not authorized to access this resource with an explicit deny.
Absent MPxN or not a value between 1 and 13 digits.	400	An MPxN must be provided, and must be a value between 1 and 13.
There's information in SMSO but is only associated with one device	404	The received MPxN is associated with a device that is not associated to any premises.
No record of the MPxN associated with a meter in a HAN in SMSOs	404	There is no available information of meters associated with the received MPxN.
No record of the MPxN exists in SMSOs	404	It was not possible at the time to recover any information of meters associated with the received MPxN.

Find MPxN, Retrieve Address availability

This API resource enables the verification of meter accessibility at a specific location, identified by a postcode and partial address. Upon request, the API returns the details of the most recently commissioned Electricity Smart Meter (ESME) associated with the address. If no ESME is available, it will return the details of the most recently commissioned Gas Smart Meter (GSME) instead.

Endpoint GET Retrieve-address-availability

This endpoint has X-API-Key as Header Parameter and the user can submit a path parameter, that is described further below.

The validations described in the Authentication section will apply.

Request Path parameter

The URL must contain the mandatory path parameters - PostCode and PartialAddress.

PostCode : Mandatory.Must be a valid UK postcode. Use '+' signs instead of spaces.
PartialAddress : Mandatory.Must be less than 30 characters. Use '+' signs instead of spaces.

Response body

If the request passes the authentication and syntactic validations, a success response is returned.

SMETS success example

JSON "resource": "/find-mpxn/C2A+2EE/22A", "responseTimestamp": "2022-04-10T17:07:01.580Z", "mpxn": "1234567891000", "deviceType": "ESME", "deviceId": "1C-23-4F-00-00-00-A9-00", "deviceStatus": "Commissioned", "deviceManufacturer": "106C", "deviceModel": "10E2A100", "deviceGbcsVersion": "3.2", "deviceFirmwareVersion": "0314B600", "smetsChtsVersion": "V4.2", "propertyFilter": { "postCode": "C2A 2EE", "addressIdentifier": "Some Str,22A,Someones house" }

??? success "AMR/HH success example

``` JSON
"resource": "/find-mpxn/C2A+2EE/22A",
"responseTimestamp": "2025-09-17T17:07:01.580Z",
"mpxn": "12345678901_A12BC34567",
"deviceType": "ESME",
"deviceId": "1C-23-4F-00-00-00-A9-00",
"deviceStatus": "Commissioned",
"deviceManufacturer": "106C",
"deviceModel": "N_A",
"deviceGbcsVersion": "N_A",
"deviceFirmwareVersion": "0314B600",
"smetsChtsVersion": "N_A",
"propertyFilter": {
    "postCode": "C2A 2EE",
    "addressIdentifier": "Some Str,22A,Someones house"
}
```

Errors in authorization or validation of path parameter will result in a response with an error code and informative message.

Error response

JSON "errors": [ { "code": 404, "message": "There is no available information of meters associated with the received partial address." } ]

Processing

The request undergoes authentication and path parameter validation. If either of these checks fails, an error is returned and the process terminates. If authentication and validation succeed, the system retrieves the latest information for the submitted postcode and partial address from DCC inventories.

If no matching record is found, or if multiple results are returned, an error is generated and the process ends. If there is more than one meter type for the provided han id, the system will return the data from the last commissioned meter, and the flag "multipleMatchingResults" will be shown on the response.

If the retrieved HAN (Home Area Network) contains more than one meter of the same type, the system returns data from the most recently commissioned meter. In this case, the response will include the flag "multipleMatchingResults": true to indicate that multiple meters were found.

If the HAN contains only one associated device, the system considers this insufficient and returns an error, terminating the process. If all conditions are met and the HAN includes multiple associated devices,

The system returns all relevant smart meter data for the matched partial address from DCC inventory.

Example of values that can be used on Sandbox

Postcode	Address
SW1A 1BA	SOMEONES STREET,7H,YORK
SW1A 1BB	SOMEONES STREET,6,YORK
C2A 2EE	22A, SOMEWHERE
M24 2LX	88,JUBILEE ROAD,MIDDLETON,MANC
GU51 1DF	4,,,Ovington Drive,,FLEET
Further values available on Sandbox Read Inventory

Address matching multiple premises:

The request is not processed internally, but forwarded to a DCC interface that will search its internal inventory. If the query results match multiple premises, an error will occur.

Error response

JSON "errors": [ { "code": 400, "message": "The Request does not uniquely identify a Premises." } ]

To avoid the error the query must be refined, constraining the address.

E.g., The Request does not uniquely identify a Premises Error

``` SH curl -iX 'GET' 'https://api-v2.data.n3rgy.com/find-mpxn/GU51+1DF/4,' -H 'accept: application/json' -H 'x-api-key: ********-****-****-****-************' HTTP/2 400 content-type: application/json content-length: 88 date: Fri, 05 Apr 2024 15:38:13 GMT

{"errors":[{"code":400,"message":"The Request does not uniquely identify a Premises."}]}

```

E.g., Refining the query...

``` SH curl -iX 'GET' 'https://api-v2.data.n3rgy.com/find-mpxn/GU51+1DF/4,,,OVIN' -H 'accept: application/json' -H 'x-api-key: ********-****-****-****-************' HTTP/2 200 content-type: application/json content-length: 434 date: Fri, 05 Apr 2024 15:38:47 GMT

{"resource":"/find-mpxn/GU51+1DF/4,,,OVIN","responseTimestamp":"2024-04-05T15:38:47.957Z","mpxn":"200*********4","deviceType":"ESME","deviceId":"30-**-**-FF-FF-**-**-**","deviceStatus":"COMMISSIONED","deviceManufacturer":"****","deviceModel":"000****","deviceGbcsVersion":"3.2","deviceFirmwareVersion":"*****","smetsChtsVersion":"V4.2","propertyFilter":{"postCode":"GU51 1DF","addressIdentifier":"4,OVINGTON DRIVE,FLEET,HAMPSHI"}}

```

Errors in authorization or general validation for all inputs will result in a response with an error code and informative message.

Error scenarios

Possible errors and corresponding messages are included in the following table.

Scenario	Error Code	Message
Absent or invalid API Key	403	User is not authorized to access this resource with an explicit deny.
Absent post code/partial address.	400	Valid UK post code and partial address with less than 30 characters must be provided.
More than a single result returned.	400	The Request does not uniquely identify a Premises.
Device Found but Not Linked to Any Premises	404	The received post code/partial address is associated with a device that is not associated to any premises.
No record of the MPxN associated with a meter in a HAN in SMSOs	404	There is no available information of meters associated with the received post code and partial address.
No record of the MPxN exists in SMSOs	404	It was not possible at the time to recover any information of meters associated with the received post code and partial address.

Get Update Frequencies, Retrieve Data Update Frequencies

Customer API resource that allow a customer to obtain the values of the data update frequency for the utility types in one of their consented HANs, specifically, the frequency of update of the import and export data for electricity meters and import data for gas meters.

Endpoint GET Get-Update-Frequencies

This endpoint has X-API-Key as Header Parameter and the user can submit a path parameter, that is described further below.

The validations described in the Authentication section will apply.

Request Path parameter

The URL must contain the mandatory path parameter - MPxN.

mpxn : Mandatory. MPxN (MPAN or MPRN) associated with the target HAN. Must be a value between 1 and 13 digits.

Response body

If the request passes the authentication and syntactic validations, a success response is returned.

Success response

JSON "resource": "get-update-frequencies/1234567891001", "responseTimestamp": "2020-11-10T17:07:01.580Z", "status": 200, "utilities": { "gas": [ { "deviceId": "01-0A-00-00-00-00-FF-03", "updateType": "gas#import", "updateFrequency": "24h" }, { "deviceId": "01-0A-00-00-00-00-FF-03", "updateType": "gas#tariff", "updateFrequency": "weekly" } ], "electricity": [ { "deviceId": "01-0A-00-00-00-00-FF-00", "updateType": "electricity#import", "updateFrequency": "24h" }, { "deviceId": "01-0A-00-00-00-00-FF-00", "updateType": "electricity#export", "updateFrequency": "3h" }, { "deviceId": "01-0A-00-00-00-00-FF-00", "updateType": "electricity#tariff", "updateFrequency": "weekly" } ] }

Errors in authorization or validation of path parameter will result in a response with an error code and informative message.

Error response

JSON "errors": [ { "code": 403, "message": "Consent for the given MPxN not found." } ]

Processing

The request is authenticated and the path parameter validated. If any of these authentication and validation rules fail, an error is returned and the process ends here.

Otherwise, the corresponding HAN is obtained, based in the provided MPxN. Then, an active consent record is search for the corresponding HAN. If there is no active consent for this HAN, an error will returned and the process ends here.

Else, the process continues and ends successfuly by returning the update frequency for each meter associated to the recovered HAN.

Error scenarios

Possible errors and corresponding messages are included in the following table.

Scenario	Error Code	Message
Absent or invalid API Key	403	User is not authorized to access this resource with an explicit deny.
Absent MPxN or not a value between 1 and 13 digits.	400	An MPxN must be provided, and must be a value between 1 and 13.
No record of a consent with status active for the HAN of the specified MPxN to this customer	403	Consent for the given MPxN not found.

Retrieve Data for Reading Type

Customer API resource that allow a customer to obtain data (consumption, production or tariff) available for a specific utility (electricity or gas) in one of their consented properties.

Endpoint GET Retrieve-Data-for-Reading-Type

This endpoint has X-API-Key as Header Parameter and the user can submit path parameters and query parameters, that are described further below.

The validations described in the Authentication section will apply.

Warning

When one or more of the update frequency fields were specified as "never" in the consent process, a 403 error will occur for a data request for those pairs of utility/readingType. If this was the case, the user can change the choices made in consent process, by using the set-meter-update-frequency endpoint.

Tip

The user only needs to change, in set-meter-update-frequency endpoint, the update frequency corresponding to the pair utility/readingType from which he wants to get data.

Request Path parameters

The URL must contain the mandatory path parameters - mpxn, utility and readingType.

mpxn : Mandatory. MPxN (MPAN or MPRN) associated with the target HAN. Must be a value between 1 and 13 digits.

Note

Please note that, this mpxn is only used to identify the corresponding HAN. This means the Customer may use, for example, an MPRN when requesting information for the utility 'electricity'.

utility : Mandatory. Utility of which data is to be retrieved. One of: electricity; gas.
readingType : Mandatory. Type of data to be recovered. One of: import, consumption, export, production, tariff, READ_INSTANTANEOUS_IMPORT_REGISTERS, READ_INSTANTANEOUS_EXPORT_REGISTERS, RETRIEVE_IMPORT_DAILY_READ_LOG, RETRIEVE_EXPORT_DAILY_READ_LOG (electricity only), RETRIEVE_DAILY_CONSUMPTION_LOG.

Request Query parameters

The URL can contain the optionals query parameters - start, end, granularity and outputFormat.

start : Optional. Start is the start date to be considered for the data retrieving.

The valid formats are yyyyMMddHHmmss, yyyyMMddHHmm and yyyyMMdd. If no value is specified the default value considered is yesterday at 00:30.

end : Optional. End is the end date to be considered for the data retrieving.

The valid formats are yyyyMMddHHmmss, yyyyMMddHHmm and yyyyMMdd. If no value is specified the default value considered is today at 00:00.

granularity : Optional. Time range to be considered for data retrieving.

This must be one of halfhour or day. If no value is specified the default value considered is halfhour.

outputFormat : Optional. The response output format.

For tariff must be one of json or raw. If no value is specified the default value considered is json.

Attention

The query parameters start, end, granularity are not applicable if the reading type is tariff.

The query parameter outputFormat is only applicable to the reading type tariff. The rest of the reading types will be output with json format.

Response body

If the request passes the authentication and syntactic validations, a success response is returned.

This response is based on the data received from the SMSO. Please consult this page to get to know all the used concepts in tariff's responses.

Note

For Twin-Element meters a secondaryValue entry will be present and will contain the values for the other element of the meter.

Note

The start of the cache is based on the most recent of the following: - Move in date - Commissioned date - Consent date minus 13 months

This means a meter consented today and commissioned last month will only contain the last month of data, for instance.

Success responses

The output of these success responses depends on the reading type requested - if it is tariff or not. Below is shown examples for considering this.
- consumption, import, production and export
  
  Success response example with two devices in the same HAN
  
  JSON "resource": "/mpxn/1234567891000/utility/electricity/readingType/consumption", "responseTimestamp": "2022-04-27T17:52:06.088Z", "availableCacheRange": { "start": "202104262300", "end": "202204270000" }, "start": "202204260030", "end": "202204270000", "granularity": "halfhour", "unit": "kWh", "devices": [ { "deviceId": "01-0A-00-00-00-00-FF-03", "values": [ { "primaryValue": 384, "timestamp": "2022-04-26 08:30" }, { "primaryValue": 365, "timestamp": "2022-04-26 09:00" }, { "primaryValue": 211, "timestamp": "2022-04-26 09:30" }, { "primaryValue": 212, "timestamp": "2022-04-26 10:00" } ] }, { "deviceId": "01-0A-00-00-00-00-FF-02", "values": [ { "primaryValue": 203, "timestamp": "2022-04-26 22:30" }, { "primaryValue": 46, "timestamp": "2022-04-26 23:00" }, { "primaryValue": 199, "timestamp": "2022-04-26 23:30" }, { "primaryValue": 152, "timestamp": "2022-04-27 00:00" } ] } ]
  
  Success response example with twin ESME
  
  JSON "resource": "/mpxn/1234567891000/utility/electricity/readingType/consumption?start=202112100015&end=202112102015", "responseTimestamp": "2022-04-27T17:52:06.088Z", "availableCacheRange": { "start": "202104262300", "end": "202204270000" }, "start": "202112100030", "end": "202112102000", "granularity": "halfhour", "unit": "kWh", "devices": [ { "deviceId": "01-0A-00-00-00-00-FF-03", "values": [ { "primaryValue": 384, "secondaryValue": 203, "timestamp": "2021-12-10 00:30" }, { "primaryValue": 365, "secondaryValue": 46, "timestamp": "2021-12-10 01:00" }, { "primaryValue": 211, "secondaryValue": 199, "timestamp": "2021-12-10 01:30" }, { "primaryValue": 212, "secondaryValue": 152, "timestamp": "2021-12-10 02:00" } ] } ]
  
  Success response example with day as granularity
  
  JSON "resource": "/mpxn/1234567891000/utility/electricity/readingType/consumption?start=202203100830&end=202203111230", "responseTimestamp": "2022-04-27T17:52:06.088Z", "availableCacheRange": { "start": "202104262300", "end": "202204260000" }, "start": "202203100830", "end": "202203111230", "granularity": "day", "unit": "kWh", "devices": [ { "deviceId": "01-0A-00-00-00-00-FF-03", "values": [ { "primaryValue": 11.183, "timestamp": "2022-03-10", "totalHHBlocks": 48 }, { "primaryValue": 9.703, "timestamp": "2022-03-11", "totalHHBlocks": 43 } ] } ]
  Attention
  While these responses are successful, meaning the meter is communicating, sometimes invalid data or no data may be received. In such cases, an additionalInformation parameter appears in the response and can have the following values:
  - "invalid value": When the value returned by the meter exceeds the maximum reading value allowed.
  - "value not available in SMSO": This means that, although meter responds, for a reason not identified, at that timestamp data is missing.
    Until the 17th of April 2024, this value is not automatically recoverable (see the Update Now feature for further information).
    After the 31st of July 2024, "value not available in SMSO" will not be added to the readings, and you may find gaps.
    Values previously added will remain and appear in the readings' requests.
    A low-priority background process will try to recover the missing readings.
  - "invalid timestamp": Every time is identified an invalid timestamp returned by the meter (invalid format or date in the future for example).
- READ_INSTANTANEOUS_IMPORT_REGISTERS and READ_INSTANTANEOUS_EXPORT_REGISTERS
??? success "Success response example for Electricity and raw as outputFormat - HAN with 1 AMR (ESME)"
```
``` JSON
    "resource": "/mpxn/1800060552643/utility/electricity/readingtype/READ_INSTANTANEOUS_IMPORT_REGISTERS?start=20251211170701&granularity=day&includeCheckMeter=false&end=20251213170701",
    "responseTimestamp": "2026-01-13T13:10:33.829Z",
    "availableCacheRange": {
        "start": "202405260000",
        "end": "202512170000"
    },
    "start": "202512111707",
    "end": "202512131707",
    "granularity": "day",
    "unit": "kWh",
    "devices": [
        {
            "deviceId": "1800060552643_L23UP00153",
            "values": [
                {
                    "primaryValue": 0.55,
                    "timestamp": "2025-12-12",
                    "totalHHBlocks": 1,
                    "type": "TOTAL"
                }
            ]
        }
    ]
    ```
```
- tariff
  
  As said before, the output format for a tariff response can either be raw or json (by request or assumed as default value).
  
  If the outputFormat is json, or if it's not specified, the response will include the tariff for the current day and the day before for each applicable device in the HAN, if available.
  
  Else, if the outputFormat is raw, the response will include the tariff specification corresponding to the most recent record obtained for each applicable device in the HAN, if available.
  
  Attention
  
  The start and end query parameters can also be used with tariffs. However, they shouldn't be used with the JSON output format.
  When not used the RAW output format will return the latest tariff data collected.
  
  Only the latest tariff data will be returned when multiple tariff data between the start and end dates.
  Like the other readings, the availableCacheRange tells us about the tariff data period. We know that within that period we have tariff data, but we don't know how many.
  Since we always get the latest tariff data available, to get the previous one the end should be before the firstReading of the tariff data we are reading. I.e., the start and end periods should not include the firstReading of the tariff data we are reading, otherwise, it becomes the latest tariff available within the defined period, and we will receive the same data.
  
  Below, is shown examples for both utilities and output formats.
  
  Success response example for Electricity and raw as outputFormat - HAN with 1 ESME
  
  JSON "resource": "/mpxn/9876580000001/utility/electricity/readingType/tariff?outputFormat=raw", "responseTimestamp": "2023-10-23T14:04:59.419Z", "devices": [ { "deviceId": "76-C5-A5-43-28-11-11-11", "tariffs": [ { "firstReading": "2023-09-23 15:46:03.728", "lastReading": "2023-10-17 04:01:56.461", "tariffDetails": { "currencyUnitsLabel": "GB Pounds", "currencyUnitsName": "Millipence", "standingCharge": 20000.0, "standingChargeScale": -3, "priceScale": -3, "primaryActiveTariffPrice": 1, "switchingTable": { "dayProfiles": [ { "day": 1, "profileSchedule": [ { "startTime": "07:00", "touTariffIndex": null, "blockTariffIndex": 1 }, { "startTime": "23:00", "touTariffIndex": null, "blockTariffIndex": 2 } ] }, { "day": 2, "profileSchedule": [ { "startTime": "00:00", "touTariffIndex": 1, "blockTariffIndex": null } ] } ], "weekProfiles": [ { "weekName": 1, "referencedDays": [ { "index": 1, "value": 1 }, { "index": 2, "value": 1 }, { "index": 3, "value": 1 }, { "index": 4, "value": 1 }, { "index": 5, "value": 1 }, { "index": 6, "value": 2 }, { "index": 7, "value": 2 } ] } ], "seasons": [ { "seasonName": "all", "seasonStartDate": { "year": { "value": 2015, "nonSpecified": false }, "month": { "value": 1, "nonSpecified": false }, "dayOfMonth": { "value": 1, "lastDayOfMonth": false, "secondLastDayOfMonth": false, "nonSpecifiedDayOfMonth": false }, "dayOfWeek": { "value": null, "nonSpecified": true } }, "referencedWeekName": 1 } ] }, "specialDays": [ { "date": { "year": { "value": 2015, "nonSpecified": false }, "month": { "value": 5, "nonSpecified": false }, "dayOfMonth": { "value": 1, "lastDayOfMonth": false, "secondLastDayOfMonth": false, "nonSpecifiedDayOfMonth": false }, "dayOfWeek": { "value": null, "nonSpecified": true } }, "referencedDay": 2 }, { "date": { "year": { "value": 2015, "nonSpecified": false }, "month": { "value": 12, "nonSpecified": false }, "dayOfMonth": { "value": 25, "lastDayOfMonth": false, "secondLastDayOfMonth": false, "nonSpecifiedDayOfMonth": false }, "dayOfWeek": { "value": null, "nonSpecified": true } }, "referencedDay": 2 } ], "touPrices": [ { "index": 1, "value": 2121.0 }, { "index": 2, "value": 0.0 }, { "index": 3, "value": 0.0 }, { "index": 4, "value": 0.0 }, { "index": 5, "value": 0.0 }, { "index": 6, "value": 0.0 }, { "index": 7, "value": 0.0 }, { "index": 8, "value": 0.0 }, { "index": 9, "value": 0.0 }, { "index": 10, "value": 0.0 }, { "index": 11, "value": 0.0 }, { "index": 12, "value": 0.0 }, { "index": 13, "value": 0.0 }, { "index": 14, "value": 0.0 }, { "index": 15, "value": 0.0 }, { "index": 16, "value": 0.0 }, { "index": 17, "value": 0.0 }, { "index": 18, "value": 0.0 }, { "index": 19, "value": 0.0 }, { "index": 20, "value": 0.0 }, { "index": 21, "value": 0.0 }, { "index": 22, "value": 0.0 }, { "index": 23, "value": 0.0 }, { "index": 24, "value": 0.0 }, { "index": 25, "value": 0.0 }, { "index": 26, "value": 0.0 }, { "index": 27, "value": 0.0 }, { "index": 28, "value": 0.0 }, { "index": 29, "value": 0.0 }, { "index": 30, "value": 0.0 }, { "index": 31, "value": 0.0 }, { "index": 32, "value": 0.0 }, { "index": 33, "value": 0.0 }, { "index": 34, "value": 0.0 }, { "index": 35, "value": 0.0 }, { "index": 36, "value": 0.0 }, { "index": 37, "value": 0.0 }, { "index": 38, "value": 0.0 }, { "index": 39, "value": 0.0 }, { "index": 40, "value": 0.0 }, { "index": 41, "value": 0.0 }, { "index": 42, "value": 0.0 }, { "index": 43, "value": 0.0 }, { "index": 44, "value": 0.0 }, { "index": 45, "value": 0.0 }, { "index": 46, "value": 0.0 }, { "index": 47, "value": 0.0 }, { "index": 48, "value": 0.0 } ], "blockPriceMatrix": [ { "index": 1, "prices": [ { "index": 1, "value": 2289 }, { "index": 2, "value": 3546 }, { "index": 3, "value": 0 }, { "index": 4, "value": 0 } ] }, { "index": 2, "prices": [ { "index": 1, "value": 4002 }, { "index": 2, "value": 6969 }, { "index": 3, "value": 0 }, { "index": 4, "value": 0 } ] }, { "index": 3, "prices": [ { "index": 1, "value": 0 }, { "index": 2, "value": 0 }, { "index": 3, "value": 0 }, { "index": 4, "value": 0 } ] }, { "index": 4, "prices": [ { "index": 1, "value": 0 }, { "index": 2, "value": 0 }, { "index": 3, "value": 0 }, { "index": 4, "value": 0 } ] }, { "index": 5, "prices": [ { "index": 1, "value": 0 }, { "index": 2, "value": 0 }, { "index": 3, "value": 0 }, { "index": 4, "value": 0 } ] }, { "index": 6, "prices": [ { "index": 1, "value": 0 }, { "index": 2, "value": 0 }, { "index": 3, "value": 0 }, { "index": 4, "value": 0 } ] }, { "index": 7, "prices": [ { "index": 1, "value": 0 }, { "index": 2, "value": 0 }, { "index": 3, "value": 0 }, { "index": 4, "value": 0 } ] }, { "index": 8, "prices": [ { "index": 1, "value": 0 }, { "index": 2, "value": 0 }, { "index": 3, "value": 0 }, { "index": 4, "value": 0 } ] } ], "blockThresholdMatrix": [ { "index": 1, "thresholds": [ { "index": 1, "value": 10.000 }, { "index": 2, "value": 10.000 }, { "index": 3, "value": 0.000 } ] }, { "index": 2, "thresholds": [ { "index": 1, "value": 10.000 }, { "index": 2, "value": 10.000 }, { "index": 3, "value": 0.000 } ] }, { "index": 3, "thresholds": [ { "index": 1, "value": 10.000 }, { "index": 2, "value": 10.000 }, { "index": 3, "value": 0.000 } ] }, { "index": 4, "thresholds": [ { "index": 1, "value": 0.000 }, { "index": 2, "value": 0.000 }, { "index": 3, "value": 0.000 } ] }, { "index": 5, "thresholds": [ { "index": 1, "value": 0.000 }, { "index": 2, "value": 0.000 }, { "index": 3, "value": 0.000 } ] }, { "index": 6, "thresholds": [ { "index": 1, "value": 0.000 }, { "index": 2, "value": 0.000 }, { "index": 3, "value": 0.000 } ] }, { "index": 7, "thresholds": [ { "index": 1, "value": 0.000 }, { "index": 2, "value": 0.000 }, { "index": 3, "value": 0.000 } ] }, { "index": 8, "thresholds": [ { "index": 1, "value": 0.000 }, { "index": 2, "value": 0.000 }, { "index": 3, "value": 0.000 } ] } ] } } ], "availableCacheRange": { "start": "202308251546", "end": "202310231404" } } ]
  
  Success response example for Electricity and json as outputFormat - HAN with 2 ESMEs, no tariff data for one of them
  
  JSON "resource": "/mpxn/9876580000001/utility/electricity/readingType/tariff", "responseTimestamp": "2023-10-23T14:09:41.065Z", "devices": [ { "deviceId": "76-C5-A5-43-28-11-11-11", "tariffs": [ { "firstReading": "20230923154603", "lastReading": "20231017040156", "primaryActiveTariffPrice": 0.001, "currencyUnitsName": "Millipence", "currencyUnitsLabel": "GB Pounds", "standingCharge": 20.0 } ], "months": [ { "monthName": "October", "days": [ { "dayNumber": 22, "timePeriods": [ { "start": "00:00", "end": "23:59", "prices": [ { "type": "TOU", "value": 2.121 } ] } ] }, { "dayNumber": 23, "timePeriods": [ { "start": "00:00", "end": "07:00", "prices": [ { "type": "TOU", "value": 2.121 } ] }, { "start": "07:00", "end": "23:00", "prices": [ { "type": "Block", "limit": "10.000", "value": 2.289 }, { "type": "Block", "limit": "10.000", "value": 3.546 } ] }, { "start": "23:00", "end": "23:59", "prices": [ { "type": "Block", "limit": "10.000", "value": 4.002 }, { "type": "Block", "limit": "10.000", "value": 6.969 } ] } ] } ] } ], "availableCacheRange": { "start": "202308251546", "end": "202310191004" } }, { "deviceId": "76-C5-A5-43-28-11-11-99", "information": "No tariff data available for this device.", "availableCacheRange": { "start": "202309231546", "end": "202310191004" } } ]
  
  Success response example for Gas and raw as outputFormat - HAN with 1 GSME
  
  JSON "resource": "/mpxn/9876580000003/utility/gas/readingType/tariff?outputFormat=raw", "responseTimestamp": "2023-10-23T14:17:56.001Z", "devices": [ { "deviceId": "76-85-65-43-28-11-11-13", "tariffs": [ { "firstReading": "2023-07-24 17:25:36.105987", "lastReading": "2023-10-17 02:07:24.599538", "tariffDetails": { "currencyUnitsLabel": "GB Pounds", "currencyUnitsName": "Millipence", "standingCharge": 0.0, "standingChargeScale": -3, "priceScale": -3, "primaryActiveTariffPrice": 11, "switchingTable": { "dayProfiles": [ { "day": 1, "profileSchedule": [ { "startTime": "00:00:00", "touTariffIndex": 1, "blockTariffIndex": null } ] } ], "weekProfiles": [ { "weekName": 1, "referencedDay": [ { "index": 1, "value": 1 }, { "index": 2, "value": 1 }, { "index": 3, "value": 1 }, { "index": 4, "value": 1 }, { "index": 5, "value": 1 }, { "index": 6, "value": 1 }, { "index": 7, "value": 1 } ] } ], "seasons": [ { "seasonName": null, "seasonStartDate": { "year": { "value": 2015, "nonSpecified": false }, "month": { "value": 1, "nonSpecified": false }, "dayOfMonth": { "value": 1, "lastDayOfMonth": false, "secondLastDayOfMonth": false, "nonSpecifiedDayOfMonth" : false }, "dayOfWeek": { "value": null, "nonSpecified": true } }, "referencedWeekName": 1 } ] }, "specialDays": [ { "date": { "year": { "value": 2017, "nonSpecified": false }, "month": { "value": 9, "nonSpecified": false }, "dayOfMonth": { "value": 29, "lastDayOfMonth": false, "secondLastDayOfMonth": false, "nonSpecifiedDayOfMonth": false }, "dayOfWeek": { "value": 5, "nonSpecified": false } }, "referencedDay": 1 } ], "touPrices": [ { "index": 1, "value": 1.0 }, { "index": 2, "value": 0.0 }, { "index": 3, "value": 0.0 }, { "index": 4, "value": 0.0 } ], "blockPriceMatrix": [ { "index": 1, "prices": [ { "index": 1, "value": 0 }, { "index": 2, "value": 0 }, { "index": 3, "value": 0 }, { "index": 4, "value": 0 } ] } ], "blockThresholdMatrix": [ { "index": 1, "thresholds": [ { "index": 1, "value": 0.000 }, { "index": 2, "value": 0.000 }, { "index": 3, "value": 0.000 } ] } ] } } ], "availableCacheRange": { "start": "202307241725", "end": "202310231417" } } ]
  
  Success response example for Gas and json as outputFormat - TOU, HAN with 1 GSME
  
  JSON "resource": "/mpxn/9876580000003/utility/gas/readingType/tariff", "responseTimestamp": "2023-10-23T14:20:02.763Z", "devices": [ { "deviceId": "76-85-65-43-28-11-11-13", "tariffs": [ { "firstReading": "20230724172536", "lastReading": "20231017020724", "primaryActiveTariffPrice": 0.011, "currencyUnitsName": "Millipence", "currencyUnitsLabel": "GB Pounds", "standingCharge": 0.0 } ], "months": [ { "monthName": "October", "days": [ { "dayNumber": 22, "timePeriods": [ { "start": "00:00:00", "end": "23:59", "prices": [ { "type": "TOU", "value": 0.001 } ] } ] }, { "dayNumber": 23, "timePeriods": [ { "start": "00:00:00", "end": "23:59", "prices": [ { "type": "TOU", "value": 0.001 } ] } ] } ] } ], "availableCacheRange": { "start": "202307241725", "end": "202310231420" } } ]
Error responses

Errors in authorization or validation of path and query parameters will result in a response with an error code and informative message.

Error response example

JSON "errors": [ { "code": 403, "message": "Consent for the given MPxN not found." } ]

Processing

The request is authenticated and the path parameters validated. If any of these authentication and validation rules fail, an error is returned and the process ends here. Otherwise, the corresponding HAN is obtained, based in the provided MPxN. Then, an active consent record is search for the corresponding HAN. If there is no active consent for this HAN, an error is returned and the process ends here.

Else, the process continues and can be processed in two different ways depending on the reading type provided :

For import, consumption, export or production, READ_INSTANTANEOUS_IMPORT_REGISTERS, READ_INSTANTANEOUS_EXPORT_REGISTERS, RETRIEVE_IMPORT_DAILY_READ_LOG, RETRIEVE_EXPORT_DAILY_READ_LOG (electricity only), RETRIEVE_DAILY_CONSUMPTION_LOG

The query parameters (start, end, granularity and outputFormat), if given, are validated. If any of these validation rules fail then an error is returned and the process ends here.

Otherwise, the process continues and is searched the data records for the recovered HAN and update type (utility + readingType) provided. If no record is found, an error is returned and the process ends here.

Else, it is determined the start and end date times for the data to be included in the response and the process ends successfully by returning the data for each HAN meter for the given update type.

For tariff

The query parameter (outputFormat), if given, is validated. If this validation rule fail then an error is returned and the process ends here.

Otherwise, the process continues and is obtained the devices in the recovered HAN of the applicable type (ESME or GSME, according to the utility specified in the request). For each one of these devices, the data from the SMSO is obtained. If the SMSO has no record at all of this device, an error is returned and the process ends here.

If the SMSO detects incoherent data, an error is returned and the process ends here.

Else, if the SMSO detects that, for this device, the tariff has not been set or could not be parsed, the response include the information "No tariff data available for this device.". Or, if the SMSO returns data, the response is constructed and the process ends successfuly by returning the response with the data for each device.

Collecting tariffs data

Tariffs are not attached to a timestamp and there is no history. When the supplier uploads a new tariff the old one is updated.
The tariff data presented was collected using a lookup methodology. I.e., there is a (weekly) scheduled request that gets the tariff from the device, setting the value firstReading and the lastReading to the current timestamp when new tariff data is collected. When the collected tariff data is the same as the last one only the lastReading is updated.
There is no exact date when the tariff was changed just the knowledge of the first time it was collected and the last time it was read.
From a tariff data list, we would know that the tariff has changed between the lastReading from a tariff and the firstReading for the next one.

Error scenarios

Possible errors and corresponding messages are included in the following table.

Note

Please note that, some errors are only applied when the requested reading data type is consumption (import) or production (export), because only in these requests are validated the query parameters start, end and granularity.

Likewise, only some errors are only applied when the requested reading type is tariff.

Requested Data Type	Scenario	Error Code	Message
One of : import, consumption, export, production, tariff, READ_INSTANTANEOUS_IMPORT_REGISTERS, READ_INSTANTANEOUS_EXPORT_REGISTERS, RETRIEVE_IMPORT_DAILY_READ_LOG, RETRIEVE_EXPORT_DAILY_READ_LOG, RETRIEVE_DAILY_CONSUMPTION_LOG	Absent or invalid API Key	403	User is not authorized to access this resource with an explicit deny.
One of : import, consumption, export, production, tariff, READ_INSTANTANEOUS_IMPORT_REGISTERS, READ_INSTANTANEOUS_EXPORT_REGISTERS, RETRIEVE_IMPORT_DAILY_READ_LOG, RETRIEVE_EXPORT_DAILY_READ_LOG, RETRIEVE_DAILY_CONSUMPTION_LOG	Absent MPxN or not a value between 1 and 13 digits.	400	An MPxN must be provided, and must be a value between 1 and 13.
One of : import, consumption, export, production, tariff, READ_INSTANTANEOUS_IMPORT_REGISTERS, READ_INSTANTANEOUS_EXPORT_REGISTERS, RETRIEVE_IMPORT_DAILY_READ_LOG, RETRIEVE_EXPORT_DAILY_READ_LOG, RETRIEVE_DAILY_CONSUMPTION_LOG	Absent utility or its value is not electricity or gas	400	A utility type must be provided and must be one of: electricity, gas.
One of : import, consumption, export, production, tariff, READ_INSTANTANEOUS_IMPORT_REGISTERS, READ_INSTANTANEOUS_EXPORT_REGISTERS, RETRIEVE_IMPORT_DAILY_READ_LOG, RETRIEVE_EXPORT_DAILY_READ_LOG, RETRIEVE_DAILY_CONSUMPTION_LOG	Absent readingType or its value is not one of: import, consumption, export, production, tariff	400	A type of data must be provided and must be one of: import, consumption, export, production, tariff.
One of : import, consumption, export, production, tariff, READ_INSTANTANEOUS_IMPORT_REGISTERS, READ_INSTANTANEOUS_EXPORT_REGISTERS, RETRIEVE_IMPORT_DAILY_READ_LOG, RETRIEVE_EXPORT_DAILY_READ_LOG, RETRIEVE_DAILY_CONSUMPTION_LOG	outputFormat is specified and is not one of: json, csv	400	Parameter 'outputFormat' must be one of: json, csv.
One of : import, consumption, export, production, READ_INSTANTANEOUS_IMPORT_REGISTERS, READ_INSTANTANEOUS_EXPORT_REGISTERS, RETRIEVE_IMPORT_DAILY_READ_LOG, RETRIEVE_EXPORT_DAILY_READ_LOG, RETRIEVE_DAILY_CONSUMPTION_LOG	start is specified and its format is not one of: yyyyMMddHHmmss, yyyyMMddHHmm or yyyyMMdd	400	Parameter 'start' format must be one of: yyyyMMddHHmm, yyyyMMdd. Note that midnight of day DD must be specified as 00h of the next day.
One of : import, consumption, export, production, READ_INSTANTANEOUS_IMPORT_REGISTERS, READ_INSTANTANEOUS_EXPORT_REGISTERS, RETRIEVE_IMPORT_DAILY_READ_LOG, RETRIEVE_EXPORT_DAILY_READ_LOG, RETRIEVE_DAILY_CONSUMPTION_LOG	end is specified and its format is not one of: yyyyMMddHHmmss, yyyyMMddHHmm or yyyyMMdd	400	Parameter 'end' format must be one of: yyyyMMddHHmm, yyyyMMdd. Note that midnight of day DD must be specified as 00h of the next day.
One of : import, consumption, export, production, READ_INSTANTANEOUS_IMPORT_REGISTERS, READ_INSTANTANEOUS_EXPORT_REGISTERS, RETRIEVE_IMPORT_DAILY_READ_LOG, RETRIEVE_EXPORT_DAILY_READ_LOG, RETRIEVE_DAILY_CONSUMPTION_LOG	The time period between start and end is more than 3 months	400	The time period between start and end dates can not be more than 3 months.
One of : import, consumption, export, production, READ_INSTANTANEOUS_IMPORT_REGISTERS, READ_INSTANTANEOUS_EXPORT_REGISTERS, RETRIEVE_IMPORT_DAILY_READ_LOG, RETRIEVE_EXPORT_DAILY_READ_LOG, RETRIEVE_DAILY_CONSUMPTION_LOG	granularity is specified and is not one of: halfhour, day	400	Parameter 'granularity' must be one of: halfhour, day.
One of : import, consumption, export, production, tariff, READ_INSTANTANEOUS_IMPORT_REGISTERS, READ_INSTANTANEOUS_EXPORT_REGISTERS, RETRIEVE_IMPORT_DAILY_READ_LOG, RETRIEVE_EXPORT_DAILY_READ_LOG, RETRIEVE_DAILY_CONSUMPTION_LOG	No record of a consent with status active for the HAN of the specified MPxN to this customer	403	Consent for the given MPxN not found.
One of : import, consumption, export, production, tariff, READ_INSTANTANEOUS_IMPORT_REGISTERS, READ_INSTANTANEOUS_EXPORT_REGISTERS, RETRIEVE_IMPORT_DAILY_READ_LOG, RETRIEVE_EXPORT_DAILY_READ_LOG, RETRIEVE_DAILY_CONSUMPTION_LOG	No record for the requested HAN and update type (utility + readingType)	404	There is no available data for the specified combination of utility and type of data in the HAN associated with the received MPxN.
tariff	No record of the devices of the applicable type (ESME or GSME) in the target HAN	404	There are no devices for the specified utility in the HAN associated with the received MPxN.
tariff	Incoherent data received : Tariff has not been set or could not be parsed for all records obtained from the device of the HAN	404	There is no available data for the specified combination of utility and type of data in the HAN associated with the received MPxN.
One of : import, consumption, export, production, READ_INSTANTANEOUS_IMPORT_REGISTERS, READ_INSTANTANEOUS_EXPORT_REGISTERS, RETRIEVE_IMPORT_DAILY_READ_LOG, RETRIEVE_EXPORT_DAILY_READ_LOG, RETRIEVE_DAILY_CONSUMPTION_LOG	Absent update frequencies for one or more fields.	403	Consent for the given MPxN does not have update frequencies set.

Tip

For this last Error, check warning to see how to solve it.

Set Defaults

Customer API resource that allow a customer to set their defaults for future consented HANs for getting historic data and frequency of update of data for the electricity and gas meters.

Endpoint PUT Set-Defaults

This endpoint has X-API-Key as Header Parameter and the user must submit one of the optionals body parameters, that are described further below.

The validations described in the Authentication section will apply.

Request Body parameters

The JSON request body must contain one of the optionals body parameters - getHistoryData, electricityImportUpdateFrequency, electricityExportUpdateFrequency and gasUpdateFrequency.

getHistoricData : Optional. Indicates if historic data should be obtained from the meters in a consented HAN. One of: true, false.
electricityImportUpdateFrequency : Optional. Determines the frequency of data updates for electric meters in a consented HAN. One of: never, 3h, 6h, 12h, daily, weekly, monthly.
electricityExportUpdateFrequency : Optional. Determines the frequency of data updates for electric meters in a consented HAN. One of: never, 3h, 6h, 12h, daily, weekly, monthly.
gasUpdateFrequency : Optional. Determines the frequency of data updates for gas meters in a consented HAN. One of: never, 3h, 6h, 12h, daily, weekly, monthly.

Example

JSON "getHistoryData": "true", "electricityExportUpdateFrequency": "daily", "electricityImportUpdateFrequency": "12h", "gasUpdateFrequency": "never"

Response body

If the request passes the authentication and syntactic validations, a success response is returned.

Success response

JSON "resource": "/set-defaults", "responseTimestamp": "2021-04-10T17:07:01.580Z", "status": { "code": "OK", "message": "Request to reset default(s) in customer profile was successful." }

Errors in authorization or validation of body parameters will result in a response with an error code and informative message.

Error response

JSON "errors": [ { "code": 400, "message": "Parameter 'electricityExportUpdateFrequency' must be one of: NEVER, H_2, H_6, H_12, DAILY, WEEKLY, MONTHLY. " } ]

Processing

The request is authenticated and the body parameters validated. If any of these authentication and validation rules fail, an error is returned and the process ends here.

Otherwise, the system will set the specified values for getHistoricData, electricityImportUpdateFrequency, electricityExportUpdateFrequency and/or gasUpdateFrequency provided in request body, in the customer profile.

Warning

These new values will only be applied to new consents.

Error scenarios

Possible errors and corresponding messages are included in the following table.

Scenario	Error Code	Message
Absent or invalid API Key	403	User is not authorized to access this resource with an explicit deny.
Customer is not allowed to change update frequencies	403	User is not authorized to access this resource with an explicit deny.
Empty request body	400	At least one body parameter must be provided.
electricityImportUpdateFrequency or electricityExportUpdateFrequency or gasUpdateFrequency is specified and is not one of: never, 3h, 6h, 12h, daily, weekly, monthly	400	Parameter "parameter-name" must be one of: NEVER, H_2, H_6, H_12, DAILY, WEEKLY, MONTHLY.
getHistoryData is specified and is not one of: true, false	400	Parameter 'getHistoryData' must be one of: true, false.

Reset Update Frequencies for all consented HANs

Customer API resource that allow a customer to set their defaults and force the change of update frequencies (for electricity and gas meters) for all the already consented HANs.

Endpoint PUT Reset-Update-Frequencies-for-all-consented-HANs

This endpoint has X-API-Key as Header Parameter and the user must submit one of the optionals body parameters, that are described further below.

The validations described in the Authentication section will apply.

Request Body parameters

The JSON request body must contain one of the optionals body parameters - electricityImportUpdateFrequency, electricityExportUpdateFrequency and gasUpdateFrequency.

electricityImportUpdateFrequency : Optional. Determines the frequency of data updates for electric meters in a consented HAN. One of: NEVER, H_2, H_6, H_12, DAILY, WEEKLY, MONTHLY.
electricityExportUpdateFrequency : Optional. Determines the frequency of data updates for electric meters in a consented HAN. One of: NEVER, H_2, H_6, H_12, DAILY, WEEKLY, MONTHLY.
gasUpdateFrequency : Optional. Determines the frequency of data updates for gas meters in a consented HAN. One of: NEVER, H_2, H_6, H_12, DAILY, WEEKLY, MONTHLY.

Example

JSON "electricityExportUpdateFrequency": "DAILY", "electricityImportUpdateFrequency": "H_12", "gasUpdateFrequency": "NEVER"

Response body

If the request passes the authentication and syntactic validations, a success response is returned.

Success response

JSON "resource": "/reset-all-update-frequencies", "responseTimestamp": "2021-04-10T17:07:01.580Z", "status": { "code": "OK", "message": "Request to reset update frequencies was successful." }

Errors in authorization or validation of body parameters will result in a response with an error code and informative message.

Error response

JSON "errors": [ { "code": 400, "message": "Parameter 'electricityExportUpdateFrequency' must be one of: NEVER, H_2, H_6, H_12, DAILY, WEEKLY, MONTHLY. " } ]

Processing

The request is authenticated and the body parameters validated. If any of these authentication and validation rules fail, an error is returned and the process ends here.

Otherwise, the system will set the specified values for electricityImportUpdateFrequency, electricityExportUpdateFrequency and/or gasUpdateFrequency provided in request body, in the customer profile.

Warning

These new values will not only be applied to new consents, but also to those already requested.

Error scenarios

Possible errors and corresponding messages are included in the following table.

Scenario	Error Code	Message
Absent or invalid API Key	403	User is not authorized to access this resource with an explicit deny.
Customer is not allowed to change update frequencies	403	User is not authorized to access this resource with an explicit deny.
Empty request body	400	At least one body parameter must be provided.
electricityImportUpdateFrequency or electricityExportUpdateFrequency or gasUpdateFrequency is specified and is not one of: NEVER, H_2, H_6, H_12, DAILY, WEEKLY, MONTHLY	400	Parameter "parameter-name" must be one of: NEVER, H_2, H_6, H_12, DAILY, WEEKLY, MONTHLY.

Read Inventory

Customer API resource that returns DCC’s device inventory (device data and WAN matrix) associated with the given MPxN, Device ID or UPRN by searching n3rgy data database. When the information is outdated the API will update it against the DCC inventory.

The request will return an URI in order to access the data in JSON format.

The request is asynchronous, and a successful response means that your request was successfully processed, and all the information collected will be placed in the JSON file whose URI was provided in the response.
The access to the file will return a CloudFront error (403, Access Denied) if no information is available.
For simple read inventory requests (no Last Communications or Check Firmware set) the request might take 1 second to respond but might take up to 10 For simple read inventory requests (no Last Communications or Check Firmware set) the file might take 1 second to become available but might take up to 10 seconds per requested MPxN. Requests with Last Communications or Check Firmware will need information from the devices and the file generation might take longer, up to 1 hour.
After 1 hour the system will timeout the request, and no answer will be provided, i.e., the file will not be updated and a new request should be made.

The system will cache the responses. To update the cache the request should have the Last Communications or Check Firmware set (forcing a request to the devices).

When the content of the file is an error, means the error occurred during the data collection.
The files will be kept for two days, then they will be deleted.

Last Communications

Adding this query parameter (last-communications=true) will force the Read Inventory Service to go to the SMSO to gather the lastUpdateDate parameter and add it to the response.

Check Firmware

Adding this query parameter (check-firmware=true) will force the Read Inventory Service to go to the SMSO to gather the firmwareVersionValue parameter and add it to the response.

When checking firmware there is a need to specify the device type, from which the firmware is checked. This query parameter also allows the deviceType={deviceType} to choose the device to retrieve the firmware version. This query parameter is mandatory when check-firmware=true.

Endpoint POST Read-Inventory

This endpoint has X-API-Key as Header Parameter and the user must submit at least one of the optionals body parameters and can also submit the optionals query parameters, these parameters are described further below.

The validations described in the Authentication section will apply.

Request Body parameters

The JSON request body must contain at least one of the optionals body parameters - mpxns, uprns and deviceIds.

mpxns : Optional. List of MPXNs values. Each value must be between 1 and 13 digits.
uprns : Optional. List of UPRN values. Each value must be an number with up to 12 digits.
deviceIds : Optional. List of Device IDs. Each value must match the pattern of an EUI-64 identifier (XX-XX-XX-XX-XX-XX-XX-XX, where X is an hexadecimal character (a digit 0 to 9 or a letter a to f, or A to F).

Warning

Each request can contain up to 200 entries of each of the elements (mpxns, uprns and/or deviceIds).

Warning

There is a daily threeshold for processed entries (sum of all entries of each elements (mpxns, uprns and/or deviceIds) in all requests) - 1000000. This value cannot be exceeded, otherwise an error message is returned.

Example with all three possible lists

JSON "mpxns": [ "9876580000307" ], "uprns": [ "893213120003" ], "deviceIds": [ "00-00-00-00-00-00-00-00" ]

Example with only mpxns

JSON "mpxns": [ "9876580000048" ], "uprns": [ ], "deviceIds": [ ]

Request Query parameters

The URL can contain the optionals query parameters - last-communications, check-firmware and deviceType.

last-communications : Optional. Triggers a last communications request. The asynchronous data received by the json file will contain the information about the last communications date for each device in a HAN. One of: true, false. Default value is false.
check-firmware : Optional. Triggers a check firmware version request. If no device type is specified the request will consider both device types (ESME and GSME). The asynchronous data received by the json file will contain the information about the device firmware. One of: true, false. Default value is false.
deviceType : Optional. Specifies a device type for the check firmware request. . One of : ESME, GSME (case insensitive).

Warning

If the check-firmware parameter is not specified and the device type is, that request will result in error. This way when deviceType is specified, check-firmware has to be true.

Warning

When using the check-firmware option there will be a request to the meter and the response might mismatch with the one on the DCC Inventory. The response will present both.

Response body

If the request passes the authentication and syntactic validations, a success response is returned with a uri to access data in JSON format.

IMPORTANT

The file at the referred uri will only be available for download after the processing has been finished. It's normal to have to wait a few minutes for the process to complete.

In uri it is possible to access data about the requested devices, in table below this data received is explained in more detailed.

For each element requested (MPxN/DeviceID/UPRN) the uri contains:

Element	Description	Notes
Devices	List containing all the devices associated to the device identified with the MPxN/DeviceID/UPRN used in the request	-
deviceId	Device ID of a Device in the Smart Metering System (EUI-64)	Mandatory
deviceType	The Type of device. Valid set: ESME, GSME, GPF, CHF, HCALCS, PPMID, IHD and CAD	Mandatory
deviceStatus	An indicator giving the status of the device. Valid set: PENDING, WHITELISTED, INSTALLEDNOTCOMMISSIONED, COMMISSIONED, DECOMMISSIONED, WITHDRAWN, SUSPENDED, RECOVERY and RECOVERED	NA for IHD,CAD; mandatory otherwise
deviceManufacturer	The name of the Device’s Manufacturer. With the exception of IHD and CAD: The Device Manufacturer is the device model manufacturer identifier from the CPL and presented in the format XXXX where each X is one of the characters 0 to 9 or A to F.	Mandatory
deviceModel	The specific model of the device, as used by the manufacturer. With the exception of IHD and CAD, the device model is the concatenation of : the first 4 characters are the model identifier + the next 2 characters are the hardware version.version + the final 2 characters are the hardware version.revision.	Mandatory
smetsChtsVersion	The version of SMETS or CHTS that the device complies with. This should align with the SMETS_CHTS version value contained on the CPL.	NA for IHD,CAD; mandatory otherwise
deviceFirmwareVersion	The operational version of Firmware of the Device. The Firmware version as held in the CPL and presented in the format XXXXXXXX where each X is one of the characters 0 to 9 or A to F.	mandatory for ESME, GSME, CHF, GPF, PPMID, HCALCS; NA otherwise
deviceFirmwareVersionStatus	The status of the Firmware Version. Valid set: ACTIVE, CANCELLED, EXPIRED and WITHDRAWN	mandatory for ESME, GSME, CHF, GPF, PPMID, HCALCS; NA otherwise
cplStatus	The CPL Assurance Certificate Status. Valid set: ACTIVE, CANCELLED, EXPIRED and WITHDRAWN	mandatory for ESME, GSME, CHF, GPF, PPMID, HCALCS; NA otherwise
dateCommissioned	Where applicable, the date when the Device was commissioned.	NA for IHD, CAD; mandatory for commissioned devices,otherwise no.
importMpxn	The reference number identifying an import electricity or a gas metering point.	Applicable to ESME, GSME. Otherwise NA
exportMpan	The reference number identifying a Twin Element Import electricity secondary metering point.	Applicable to ESME w/ export capability; otherwise NA
secondaryImportMpan	TThe reference number identifying a Twin Element Import electricity secondary metering point.	Applicable to ESME and ESME Variant B; otherwise NA
esmeVariant	The Electricity Smart Meter Variant. Valid set: A - Single Element B - Twin Element C - Polyphase AD - Single Element with ALCS BD - Twin Element with ALCS CD - Polyphase with ALCS ADE - Single Element with ALCS and Boost Function BDE - Twin Element with ALCS and Boost Function CDE - Polyphase with ALCS and Boost Function	Mandatory for ESME; otherwise NA
uprn	Unique Property Reference Number	Not mandatory
propertyFilter	Post Code and Address Identifier that uniquely identifies an address.	Not mandatory; however, if present both postCode and addressIdentifier are expected.
cspRegion	The CSP Region the Smart Meter System is associated with. Valid set: NORTH, CENTRAL, SOUTH and UNKNOWN	Not mandatory
deviceGbcsVersion	The operational version of GBCS as recorded in the SMI for the Device. The version number format will align with the CPL. For example 1.0 or 2.0	Mandatory for ESME, GSME, CHF, GPF, PPMID, HCALCS; NA otherwise
hanVariant	The Device’s HAN Variant. Valid Set: Single Band (2.4GHz only), Dual Band (868MHz and 2.4GHz) and Unknown HAN Variant	Mandatory for CHF, otherwise NA
s1sp	Identifier of the SMETS1 Service Provider the Smart Metering System is associated with.	Applicable to SMETS1 devices only; NA to SMETS2 or later devices
wanMatrix	This element contains the WAN Matrix information retrieved based on either UPRN or address (if UPRN is not available) of the element used as request (MPxN/DeviceID/UPRN)	-
wanMatrix → status	Status of the query for WAN Matrix Information related to the input submitted. 200 means that info was found, otherwise an error code is returned together with the error "message".	-
wanMatrix → cspRegion	The CSP Region the address is associated with. Valid set: NORTH, CENTRAL, SOUTH and UNKNOWN	Mandatory (on success)
wanMatrix → coverageAvailability	Coverage Availability. Valid set: true or false	Mandatory (on success)
wanMatrix → anticipatedCoverageDate	If Coverage Availability is set to false, the anticipated date when Coverage will be available. If no Coverage is planned then this date will be set to '3000-12-31Z'	Mandatory (on success) if Coverage Availability = false; Otherwise NA
wanMatrix → wanTechnology	The WAN technology to be used for this location.	Mandatory (on success)
connectivityLikelihood	The likely Connectivity strength. Valid set: HIGH, MEDIUM and LOW	Mandatory (on success)
wanMatrix → auxiliaryEquipmentRequired	Free text with details of any required auxiliary equipment, if any.	Not mandatory
wanMatrix → additionalInformation	Free text providing additional information.	Not mandatory
lastUpdate	This represents when the information was retrieved from DCC.	Mandatory

Success response example

``` JSON "status": 200, "uuid": "ce831180-8bd2-415a-ac07-085386356b9b", "uri": "https://read-inventory.stagedata.n3rgy.com/files/ce831180-8bd2-415a-ac07-085386356b9b.json"

```

Success response uri example

JSON "result": [ { "mpxn": "9876580000307", "status": 200, "devices": [ { "deviceId": "76-85-65-43-28-11-14-20", "deviceType": "CHF", "deviceStatus": "COMMISSIONED", "deviceManufacturer": "CD04", "deviceModel": "B74F5E32", "smetsChtsVersion": "V2.0", "deviceFirmwareVersion": "1100EEFF", "deviceFirmwareVersionStatus": "ACTIVE", "cplStatus": "ACTIVE", "dateCommissioned": "2020-01-16Z", "uprn": "898900062", "propertyFilter": { "postCode": "A9A 9BB", "addressIdentifier": "17" }, "cspRegion": "CENTRAL", "deviceGbcsVersion": "1.46", "hanVariant": "Single Band (2.4GHz only)" }, { "deviceId": "76-85-65-43-28-11-14-17", "deviceType": "ESME", "deviceStatus": "COMMISSIONED", "deviceManufacturer": "CD04", "deviceModel": "B74F5E32", "smetsChtsVersion": "V2.0", "deviceFirmwareVersion": "1100EEFF", "deviceFirmwareVersionStatus": "ACTIVE", "cplStatus": "ACTIVE", "dateCommissioned": "2020-01-16Z", "importMpxn": "9876580000307", "exportMpan": "9876581111307", "esmeVariant": "A", "uprn": "898900062", "propertyFilter": { "postCode": "A9A 9BB", "addressIdentifier": "17" }, "cspRegion": "CENTRAL", "deviceGbcsVersion": "1.46", "lastCommunicationsDateTime": { "status": 200, "statusMessage": "SUCCESS", "value": "2022-11-03T00:00:00.000Z", "lastUpdate": "2022-11-04T13:36:19.242Z" } }, { "deviceId": "76-85-65-43-28-11-14-19", "deviceType": "GPF", "deviceStatus": "COMMISSIONED", "deviceManufacturer": "CD04", "deviceModel": "B74F5E32", "smetsChtsVersion": "V2.0", "deviceFirmwareVersion": "1100EEFF", "deviceFirmwareVersionStatus": "ACTIVE", "cplStatus": "ACTIVE", "dateCommissioned": "2020-01-16Z", "uprn": "898900062", "propertyFilter": { "postCode": "A9A 9BB", "addressIdentifier": "17" }, "cspRegion": "CENTRAL", "deviceGbcsVersion": "1.46", "lastCommunicationsDateTime": { "status": 200, "statusMessage": "SUCCESS", "value": "2022-11-03T00:00:00.000Z", "lastUpdate": "2022-11-04T13:36:19.724Z" } }, { "deviceId": "76-85-65-43-28-11-14-18", "deviceType": "GSME", "deviceStatus": "COMMISSIONED", "deviceManufacturer": "CD04", "deviceModel": "B74F5E32", "smetsChtsVersion": "V2.0", "deviceFirmwareVersion": "1100EEFF", "deviceFirmwareVersionStatus": "ACTIVE", "cplStatus": "ACTIVE", "dateCommissioned": "2020-01-16Z", "importMpxn": "9876580000308", "uprn": "898900062", "propertyFilter": { "postCode": "A9A 9BB", "addressIdentifier": "17" }, "cspRegion": "CENTRAL", "deviceGbcsVersion": "1.46", "lastCommunicationsDateTime": { "status": 200, "statusMessage": "SUCCESS", "value": "2022-11-03T00:00:00.000Z", "lastUpdate": "2022-11-04T13:36:19.763Z" }, "checkFirmware": { "status": 200, "statusMessage": "SUCCESS", "firmwareVersionValue": "1100EEFF", "lastUpdate": "2022-11-04T13:36:18.819Z" } } ], "wanMatrix": { "status": 200, "cspRegion": "CENTRAL", "coverageAvailability": "true", "wanTechnology": "Cellular", "connectivityLikelihood": "MEDIUM" }, "lastUpdate": "2022-11-04T13:35:57.397Z" }, { "uprn": "893213120003", "status": 404, "message": "UPRN not found" }, { "deviceId": "00-00-00-00-00-00-00-00", "status": 404, "message": "Device ID not found" } ]

Success response with invalid body entry example

JSON "status": 200, "uuid": "4f368374-5567-4df0-84b9-b45d03a16e42", "uri": "https://read-inventory.stagedata.n3rgy.com/files/4f368374-5567-4df0-84b9-b45d03a16e42.json", "invalidEntries": { "deviceIds": null, "uprns": [ "893213120003111" ], "mpxns": null

Success response with invalid body entry uri example

JSON "result": [ { "mpxn": "9876580000307", "status": 200, "devices": [ { "deviceId": "76-85-65-43-28-11-14-20", "deviceType": "CHF", "deviceStatus": "COMMISSIONED", "deviceManufacturer": "CD04", "deviceModel": "B74F5E32", "smetsChtsVersion": "V2.0", "deviceFirmwareVersion": "1100EEFF", "deviceFirmwareVersionStatus": "ACTIVE", "cplStatus": "ACTIVE", "dateCommissioned": "2020-01-16Z", "uprn": "898900062", "propertyFilter": { "postCode": "A9A 9BB", "addressIdentifier": "17" }, "cspRegion": "CENTRAL", "deviceGbcsVersion": "1.46", "hanVariant": "Single Band (2.4GHz only)" }, { "deviceId": "76-85-65-43-28-11-14-17", "deviceType": "ESME", "deviceStatus": "COMMISSIONED", "deviceManufacturer": "CD04", "deviceModel": "B74F5E32", "smetsChtsVersion": "V2.0", "deviceFirmwareVersion": "1100EEFF", "deviceFirmwareVersionStatus": "ACTIVE", "cplStatus": "ACTIVE", "dateCommissioned": "2020-01-16Z", "importMpxn": "9876580000307", "exportMpan": "9876581111307", "esmeVariant": "A", "uprn": "898900062", "propertyFilter": { "postCode": "A9A 9BB", "addressIdentifier": "17" }, "cspRegion": "CENTRAL", "deviceGbcsVersion": "1.46", "lastCommunicationsDateTime": { "status": 200, "statusMessage": "SUCCESS", "value": "2022-11-03T00:00:00.000Z", "lastUpdate": "2022-11-04T13:44:06.059Z" } }, { "deviceId": "76-85-65-43-28-11-14-19", "deviceType": "GPF", "deviceStatus": "COMMISSIONED", "deviceManufacturer": "CD04", "deviceModel": "B74F5E32", "smetsChtsVersion": "V2.0", "deviceFirmwareVersion": "1100EEFF", "deviceFirmwareVersionStatus": "ACTIVE", "cplStatus": "ACTIVE", "dateCommissioned": "2020-01-16Z", "uprn": "898900062", "propertyFilter": { "postCode": "A9A 9BB", "addressIdentifier": "17" }, "cspRegion": "CENTRAL", "deviceGbcsVersion": "1.46", "lastCommunicationsDateTime": { "status": 200, "statusMessage": "SUCCESS", "value": "2022-11-03T00:00:00.000Z", "lastUpdate": "2022-11-04T13:44:06.475Z" } }, { "deviceId": "76-85-65-43-28-11-14-18", "deviceType": "GSME", "deviceStatus": "COMMISSIONED", "deviceManufacturer": "CD04", "deviceModel": "B74F5E32", "smetsChtsVersion": "V2.0", "deviceFirmwareVersion": "1100EEFF", "deviceFirmwareVersionStatus": "ACTIVE", "cplStatus": "ACTIVE", "dateCommissioned": "2020-01-16Z", "importMpxn": "9876580000308", "uprn": "898900062", "propertyFilter": { "postCode": "A9A 9BB", "addressIdentifier": "17" }, "cspRegion": "CENTRAL", "deviceGbcsVersion": "1.46", "lastCommunicationsDateTime": { "status": 200, "statusMessage": "SUCCESS", "value": "2022-11-03T00:00:00.000Z", "lastUpdate": "2022-11-04T13:44:06.534Z" }, "checkFirmware": { "status": 200, "statusMessage": "SUCCESS", "firmwareVersionValue": "1100EEFF", "lastUpdate": "2022-11-04T13:43:58.086Z" } } ], "wanMatrix": { "status": 200, "cspRegion": "CENTRAL", "coverageAvailability": "true", "wanTechnology": "Cellular", "connectivityLikelihood": "MEDIUM" }, "lastUpdate": "2022-11-04T13:43:44.514Z" }, { "deviceId": "00-00-00-00-00-00-00-00", "status": 404, "message": "Device ID not found" } ]

IMPORTANT

If the query parameters were not filled in the request, and it was noticed that the data received may be outdated, please redo the request but this time with at least with one of the query parameters set to true.

Errors in authorization or validation of body/query parameters will result in a response with an error code and informative message.

Error response example

JSON "errors": [ { "code": 403, "message": "User is not authorized to access this resource with an explicit deny." } ]

Processing

The request is authenticated and the body/query parameters validated. If any of these authentication and validation rules for query parameters fail, an error is returned and the process ends here.

If the entire body is invalid, an error is returned and the process ends here. If only a few entries are invalid, they are highlighted in the response and the process continues to the valid entries.

After passing authentication and validation, the request size is validated. If exceeds the maximum number of entries for each entries or the daily threeshold an error message is returned.

Otherwise, the system will search in n3rgy BD for the requested mpxns, uprns and/or deviceIds. If there is no data in n3rgy BD, a request is made to DCC.

Data is returned in the response URI, asynchronously.

Error scenarios

Possible errors and corresponding messages are included in the following table.

Scenario	Error Code	Message
Absent or invalid API Key	403	User is not authorized to access this resource with an explicit deny.
Empty request body	400	The request's body is empty.
The element specified in the body needs to be filled	400	There are no inputs on the request.
Each element (mpxn/uprn/deviceId) in request cannot exceed 200 itens	429	The list of element chosen in request (mpxn/uprn/deviceId) exceeds the maximum items allowed (200).
The daily threeshold (1000000) is being hit with the request	429	Too many inputs on the request. You are still allowed to process "allowed value" valid inputs, however the total of valid inputs is equal to "inputs requested".

Update Now

Customer API resource that allows a customer to request a reading request for the meter with a given MPxN for a given utility and reading type in one of their consented HANs. It will request data from the latest end cache date.

Endpoint GET Update-Now

This endpoint has X-API-Key as Header Parameter and the user can submit path parameters, that are described further below.

The validations described in the Authentication section will apply.

Request Path parameters

The URL must contain the mandatory path parameters - mpxn, utility and readingType.

mpxn : Mandatory. MPxN (MPAN or MPRN) associated with the target HAN. Must be a value between 1 and 13 digits.

Note

Please note that, this mpxn is only used to identify the corresponding HAN. This means the Customer may use, for example, an MPRN when requesting information for the utility 'electricity'.

utility : Mandatory. Utility of which data is to be retrieved. One of: electricity; gas.
readingType : Mandatory. Type of data to be recovered. One of: import, export, tariff.

Processing

The request is authenticated and the path parameter validated. If any of these authentication and validation rules fail, an error is returned and the process ends here.

Otherwise, the corresponding HAN is obtained, based in the provided MPxN. Then, an active consent record is search for the corresponding HAN. If there is no active consent for this HAN, an error will returned and the process ends here.

A request accepted response is returned, if the request passes the authentication and syntactic validations.

Error scenarios

Possible errors and corresponding messages are included in the following table.

Scenario	Error Code	Message
Absent or invalid API Key	403	User is not authorized to access this resource with an explicit deny.
Absent MPxN or not a value between 1 and 13 digits.	400	An MPxN must be provided, and must be a value between 1 and 13.
No record of a consent with status active for the HAN of the specified MPxN to this customer	403	Consent for the given MPxN not found.
The customer has reached the configured number of requests for the utility/reading type requested.	429	Available request daily counter reached 0. You are not allowed to make more data requests for the given combination.

Push Notification

Customer API resource that allows a customer to request their push notification configurations.

Endpoint GET Push-Configuration

This endpoint has X-API-Key as Header Parameter.

The validations described in the Authentication section will apply.

Processing

The request is authenticated. If the authentication fails, an error is returned and the process ends here.

Otherwise, the corresponding Push Notification configurations are obtained.

A request accepted response is returned, if the request passes the authentication and syntactic validations.

Response Body

Success response example

JSON "pushNotificationURL": "endpoint.com", "deviceConfigurations": { "ELECTRICITY": [ "IMPORT", "TARIFF" ] }

Errors in authorization will result in a response with an error code and informative message.

Error response example

JSON "errors": [ { "code": 403, "message": "User is not authorized to access this resource with an explicit deny." } ]

Error scenarios

Possible errors and corresponding messages are included in the following table.

Scenario	Error Code	Message
Absent or invalid API Key	403	User is not authorized to access this resource with an explicit deny.

Endpoint POST Push-Configuration

This endpoint has X-API-Key as Header Parameter and the user must submit one of the optionals body parameters and can also submit the optionals query parameters, these parameters are described further below.

The validations described in the Authentication section will apply.

Request Body parameters

The JSON request body can be sent either with the desired properties to be updated or empty.

uri : Optional. String representing the URL endpoint. Values on this field will override existing URL, unless empty.
esme : Optional. List of Utility Type values ['IMPORT', 'EXPORT', 'TARIFF']. Values on this field will override existing configurations even when empty.
gsme : Optional. List of Utility Type values ['IMPORT', 'TARIFF']. Values on this field will override existing configurations even when empty.

Warning

Setting the uri field to empty will not result in removing the endpoint from the system.

Warning

Sending an empty request body will reset both configurations for ['esme', 'gsme'].

Warning

This request removes all existing configurations and saves the ones present on the request body (settting one of the ['esme', 'gsme'] properties to empty will result in removing those configurations from the system).

Example with all three possible lists

JSON "uri":"www.dummy.url.com", "esme": ["IMPORT", "TARIFF"], "gsme": ["IMPORT"]

Response body

If the request passes the authentication and syntactic validations, a success response is returned with status code 204.

Errors in authorization or validation of body/query parameters will result in a response with an error code and informative message.

Error response example

JSON "errors": [ { "code": 403, "message": "User is not authorized to access this resource with an explicit deny." } ]

Processing

The request is authenticated and the body validated. If any of these authentication and validation rules fail, an error is returned and the process ends here.

If the entire body is invalid, an error is returned and the process ends here. If only a few entries are invalid, they are highlighted in the response and the process continues to the valid entries.

After passing authentication and validation, shall update the configurations.

Error scenarios

Possible errors and corresponding messages are included in the following table.

Scenario	Error Code	Message
Absent or invalid API Key	403	User is not authorized to access this resource with an explicit deny.

Endpoint DELETE Push-Configuration

This endpoint has X-API-Key as Header Parameter.

The validations described in the Authentication section will apply.

Processing

The request is authenticated. If the authentication fails, an error is returned and the process ends here.

Otherwise, the corresponding Push Notification configurations are deleter.

A request accepted response is returned if the request passes the authentication and syntactic validations.

Response Body

Errors in authorisation will result in a response with an error code and informative message.

Error response example

JSON "errors": [ { "code": 403, "message": "User is not authorized to access this resource with an explicit deny." } ]

Endpoint GET Push-Status

This endpoint has X-API-Key as Header Parameter.

The validations described in the Authentication section will apply.

Processing

The request is authenticated. If the authentication fails, an error is returned and the process ends here.

Otherwise, the corresponding Push Notification Status are obtained.

A request accepted response is returned, if the request passes the authentication and syntactic validations.

Response Body

Success response example

JSON "lastHttpStatus": "200", "lastResponse": "Response Body obtained if any exists.", "date": "2024-06-02T12:00:00.0000"

Errors in authorization will result in a response with an error code and informative message.

Error response example

JSON "errors": [ { "code": 403, "message": "User is not authorized to access this resource with an explicit deny." } ]

Error scenarios

Possible errors and corresponding messages are included in the following table.

Scenario	Error Code	Message
Absent or invalid API Key	403	User is not authorized to access this resource with an explicit deny.
No Response Recorded	404	No records for push notification status found at this time.