MultiDrive Web API User Guide

EDMI Limited

Version 2.87
Revision 2.30
21/06/2023
 MultiDrive Web API 2.8 User Guide

Revision History
Date Synopsis of change Author Revision
11/07/2013 Added notes on how comms server is assigned for new sites TP 1.10
31/07/2013 Added MultiDrive permission information DY 1.20
15/08/2013 Modify Register Data touRate from "T" to "TOTAL" DY 1.21
19/08/2013 Making sure all IDs are Integer (deviceId, deviceConfigurationId, siteId, DY 1.22
deviceGroupId,
parentDeviceGroupId, deliveryId, scheduleId, executionId, executionJobId,
eventLogId)
28/08/2013 • Data Delivery API DY 1.23
o Added deviceGroupName URI to all functions
• Diagnostic API
o Added plantNumber URI to "Read diagnostic register" and
"write diagnostic register"
• Fleet Management API/Commissioning API
o Added plantNumber URI to "Commission a device in the
system", "Decomission a device in the system"
• Fleet Management API/Device Configurations API
o Added deviceConfigurationName URI to "Get Device
Configuration"
• Fleet Management API/Device Group API
o Added deviceGroupName URI to "Get Device Group", "Update
Device Group", "Delete DeviceGroup", "List / Search Devices in
Device Group", "Add Devices to Device Group", "Remove Device
From Device Group"
• Fleet Management API/Devices API
o Corrected URI for "create device"
o Added plantNumber URI to "update device", "delete device",
"Last Device Access Time", "Next Schedule Device Access Time"
o Added limit and offset to "List / Search Devices"
• Fleet Management API/Sites API
o Added siteCode URI to "Delete Site"
o Added limit and offset to "List / Search Sites"
• Measured Data API
o Added plantNumber URI to "GetProfileData", "Get Time of Use
Register Data", "Get Event Log Data", "Get Voltage Sag/Swell,
THD or Unbalance Event Data", "Rollback data to a specific
date/time"
o Remove DeviceId parameter from "GetProfileData", "Get Time
of Use Register Data", "Get Event Log Data", "Get Voltage
Sag/Swell, THD or Unbalance Event Data", "Rollback data to a
specific date/time"
• Schedule API
o Added limit and offset to "List Schedule Executions", "Search for
Schedule Execution Jobs"
o Added scheduleName URI to "Get Schedule", "Trigger Regular
Schedule As Configured", "Trigger Adhoc Schedule for particular
devices", "List Schedule Executions", "Search for Schedule
Execution Jobs"
o Remove name parameter from "List Schedule Executions"
• Supply Control API
o Added deviceGroupName URI to "Get Main Supply status for a
device group"
11/10/2013 • Fleet Management API DY 1.24
o Added Modem API and SIM Card API
• Fleet Management API/Commissioning API
o Added "Commission a SMETS Device in the System", "Request
ZigBee Pairing for SMETS Gas Device", "Request ZigBee Pairing

Page ii
 MultiDrive Web API 2.8 User Guide

for SMETS IHD Device", "Request ZigBee Unpairing for SMETS

Device"
o Added deviceGroupId parameter to "Commission a Device in the
System", Decommission a Device in the System"
• Fleet Management API/Device Groups API
o Added plantNumber payload to "Add Devices to Device Group"
o Added deviceId and plantNumber payload to "Remove Device
from Device Group"
• Prepayment API
o Modified items in payload for "Write Misc. Prepayment Info to
Meter"
o Added 400 Bad Request return value for "Write Misc.
Prepayment Info to Meter", "Request Prepayment Information
for a Device"
12/10/2013 • Fleet Management API DY 1.25
o Added Gas Calorific Value API
o Include Calorific Value to Device Object
08/11/2013 • Fleet Management CB 1.26
o Added "List / Search Gas Device Pairing Events", "List / Search
IHD Device Pairing Events"
o Modified "List / Search Commissioning Events"
• Data Delivery API
o Modified "Trigger export of existing Load Profile data", "Trigger
export of existing Time of Use/Register data", "Trigger export of
existing Event Log data" parameters and return value
o Removed "Trigger export of existing voltage sag/swell data"
o Added MDX Object - Data Deliveries
12/11/2013 • Fleet Management API JC 1.27
o Added "Request ZigBee Un-pairing for SMETS Gas Device",
"Request ZigBee Un-pairing for SMETS IHD Device"
16/12/2013 • Data Delivery API AF 1.28
o Updated all data export requests to return a 202 instead of 200
on success
20/05/2014 • System API WT 1.29
o Added "Decrypt Device Password"
27/05/2014 • Fleet Management API AF 1.30
o Updated device password to be encrypted for mdx files
23/07/2014 • System API WT 1.31
o Added permission requirement for "Decrypt Device Password"
04/09/2014 • Measured Data API WT 1.32
o Added optional parameter "logNumber" in "Get Event Log Data"
15/09/2014 • Fleet Management API WT 1.33
o Updated payload format for "Get Device Configuration"
22/09/2014 • Measured Data AOU WT 1.34
o Updated "Valid values" for "logNumber" parameter in "Get
Event Log Data"
o Added "billingResetTime" property to "registerDataSets"
payload of "Get Time of Use Register Data"
o Added optional parameters "loadSurveyNumber" and
"dataTypeId" in "Get Profile Data"
o Updated comments on "Data Gaps" under "Get Profile Data"
10/11/2014 • Measured Data API WT 1.35
o Removed "Rollback data to a specific date/time".
(http://mantis.edmi.com.au/view.php?id=7812#c30232)
05/02/2015 • Prepayment API WT 1.36
o Updated payload for "Pass prepayment token to meter" to
support sending of multiple tokens to device
11/02/2015 • Fleet Management API WT 1.37
o Updated return payload for "Last Device Access Time (Scheduled
and Adhoc Communications)"

Page iii
 MultiDrive Web API 2.8 User Guide

09/09/2015 • Supply Control API WT 1.38

o Added new optional parameter "mainsControlDuration" for
"Change Main Supply Status"
17/11/2015 • Updated this specification to conform to MDX 0.48. WT 1.39
o Added support for new meter series and models.
• API Error Codes
o Added new error codes to indicate a device not linked to a site.
01/12/2015 • Added sample settings for “MainsControlDuration” WT 1.39b
15/01/2016 • FleetManagement API WT 1.39c
o Fixed URL of "Request ZigBee un-pairing for SMETS IHD device".
o Added notes to "Commission a SMETS device in the system",
"Commission a device in the system" and "List / Search
Commissioning Events".
02/03/2016 • Fleet Management API SM 1.43
o Added method to configure Device to Leave and/or Join Device
Group
o Added new API Error Codes for Device and Device Group
28/03/2016 • API Error Codes JC 1.44
o Added new error codes to indicate a Write Device Setup.
o Updated DeviceConfig-404 error message spelling exit to exist.
o Synchronize Limit and offset error message for invalid values.

04/04/2016 • FleetManagementAPI SM 1.45

o Added method to write Atlas 2 Device Setup
• Diagnostic API
o Added “Read diagnostic register”
o Added “Get Diagnostic register value read out”
o Added “Write Diagnostic Register”

15/04/2015 • API Error Codes SM 1.46

o Updated error code for Write Device Setup
o Added new error codes for Diagnostic API

23/06/2016 • API Error Codes SM 2.00

o Updated error code for Write Device Setup, Diagnostic and
Scheduling
o Added error code for Notification
• Fleet Management API
o Added “Get Last Read Device Setup”
o Added “Create Device Setup Template”
o Added “Delete Device Setup Template”
o Added “Apply Device Setup Template”
• Scheduling API
o Updated “Search for Schedule Execution Jobs”
• Updated numbering according to WEB API Spec
• Added Notification API
o Added “Acknowledge Notifications in System”
o Added “Set Notification Callback Address”

04/07/2016 • Scheduling API SM 2.01

o Added “Cancel Schedule Execution”
o Added Additional properties for schedule execution payload
• Fleet Management API
o Added support of template name to "Apply Device Setup
Template"

05/07/2016 • Notification API WT 2.02

o Added alarmId property to notification payload
• Diagnostic API
o Updated Valid Data Types for Read/Write Diagnostic Registers.
Page iv
 MultiDrive Web API 2.8 User Guide

o Added "409 Conflict" as one of the returned responses.

11/07/2016 • Update dynamic schedule settings for Pass Prepayment token to meter SM 2.03
and Supply Control API
15/07/2016 • Diagnostic API SM 2.04
o Added maximum limit in total number of registers
18/07/2016 • Scheduling API SM 2.05
o Update permission
29/07/2016 • Update “create device setup emplate” SM 2.06
15/09/2016 • Device Setup API SM 2.07
o Added Schedule Read Device Setup Stages
• Scheduling API
o Updated additional properties for schedule job payload
• API Error Codes
o Added new error codes
20/10/2016 • Device Setup API YM 2.08
o Removed “Delete Device Setup Template” as this is not
currently supported
• Added Device Setup Template sample
11/11/2016 • Data Delivery API SM 2.09
o Added new method “Trigger all-in-one export of available data”
14/02/2017 • Update test task in appendix C.2. SM 2.10
23/02/2017 • Prepayment API YM 2.11
o Added new method “Generate UTRN token”
26/04/2017 • MDDCS Configuration API SM 2.12
o Added new method “Suppress Load Profile downloads on
MDDCS”
o Added new method “Re-enable Load Profile downloads on
MDDCS”
16/05/2017 • Rename MDDCS Configuration API to MDDCS API SM 2.13
• Added new method “Request Load Profile Download”
03/07/2017 • Added setup stages for FUL’s GAS API implementation CM 2.14
02/07/2017 • API Error Codes SM 2.15
o Added new error codes
• Added optional payoad sections in 9.4.7, 9.4.8, 9.4.9, 15.1, 15.2
30/01/2018 • Updated this guide for MD Web API 2.2 WT 2.16
• System API
o Added description on auto-purging of expired authentication
tokens in section 14.1
13/07/2018 • Updated this guide for MD Web API 2.3 WT 2.17
• Prepayment API
o Added “Get Token Transfer History of 3rd-Party Vending System”
29/08/2018 • Measured Data API WT 2.18
o Added "accumulationPolicy" to returned payload of "Get Profile
Data"
o Added "billingSystem" to returned payload of "Get Time of Use
Register Data"
27/11/2018 • Devices API SM 2.19
o Added "Request Pinging a Device"
o Added "Get Ping Status"
12/12/2018 • Prepayment API WT 2.20
o Updated descriptions for "Write misc. prepayment info to
meter"
26/02/2019 • Scheduling API SM, 2.21
o Added "Get Schedule Execution Job Log By Device" NM
o Added "Get Schedule Execution Communications Log By Device"
• Supply Control API
o Added "Set Load Limiting Control”

Page v
 MultiDrive Web API 2.8 User Guide

27/02/2019 • Prepayment API SM 2.22

o Renamed "Request prepayment information for a device" to
"Request prepayment information for a device (with EDMI Atlas
Proprietary Prepayment System)".
o Renamed "Get prepayment information for a device" to "Get
prepayment information for a device (with EDMI Atlas
Proprietary Prepayment System)".
o Added "Request prepayment information of a device".
o Added "Get prepayment information of a device".
o Added "Set prepayment mode for a device".
07/09/2020 • Fleet Management API WT 2.23
o Added new device types Mk6Es and GW32P
15/10/2020 • Scheduling API SM 2.24
o Added plant number support for "Trigger Adhoc Schedule for
particular devices"
• Supply Control API
o Added "Change Main Supply Status (connect / disconnect) for
Multiple Devices"
o Added "Get Main Supply Status for Multiple Devices"
o Added "Set Load Limiting Control for Multiple Devices"
• Prepayment API
o Added "Pass prepayment token to multiple meters"
o Added "Request prepayment information of multiple devices"
o Added "Get prepayment information of multiple devices”
22/10/2020 • Fixed payload structure of schedule status callback, and WT 2.25
• Updated schedule status callback to support RabbitMQ/Kafka and for
o "Change Main Supply Status"
o "Set Load Limiting Control"
o "Request Pinging a Device"
o "Schedule Write Device Setup Stages"
o "Schedule Read Device Setup Stages"
o "Apply Device Setup Template"
o "Trigger Regular Schedule as Configured"
o "Trigger Adhoc Schedule for particular devices"
o "Top-up prepayment credit"
o "Write misc. prepayment info to meter"
o "Pass prepayment token to meter"
o "Request prepayment information"
o "Read diagnostic register"
o "Write diagnostic register"
• Updated alarm callback to support RabbitMQ/Kafka
o "Set Notification Callback Address”
• Updated non-async callback to support RabbitMQ/Kafka
o "Add Devices to Device Group"
o "Remove Device from Device Group"
o "Configure Device to Leave and/or Join Device Groups"
o "Suppress Load Profile downloads on MDDCS"
o "Re-enable Load Profile downloads on MDDCS"

11/01/2021 • Updates version number from 2.5 to 2.6 SM 2.26

• Updates revision number from 2.25 to 2.26

8/02/2021 • Fleet Management API SM 2.27

o Updated error code

16/08/2021 • Fleet Management API WT 2.28

o Added device models Mk7MDC and Mk10MCT
18/02/2022 • Added back the missing section in user guide document SM 2.29
o "Get Schedule Execution Job Log By Device"

Page vi
 MultiDrive Web API 2.8 User Guide

o "Get Schedule Execution Communications Log By Device"

21/06/2023 • Fleet Management API NY 2.30

o Added “Decommission multiple devices in the system”
• API Error Codes
o Added new error codes for Multiple Devices Decommission

Page vii
 MultiDrive Web API 2.8 User Guide

Table of Contents
Chapter 1 Overview ........................................................................................................................................ 1
1.1. MultiDrive Web APIs ................................................................................................................................... 1
1.2. REST Background ......................................................................................................................................... 3
1.3. API Patterns ................................................................................................................................................. 3
Chapter 2 API Versioning ................................................................................................................................ 5
Chapter 3 API Security .................................................................................................................................... 7
Chapter 4 API Success Responses.................................................................................................................... 8
4.1. 200 OK ......................................................................................................................................................... 8
4.2. 201 Created ................................................................................................................................................. 8
4.3. 202 Accepted ............................................................................................................................................... 8
Chapter 5 API Error Responses........................................................................................................................ 9
5.1. 400 Bad Request.......................................................................................................................................... 9
5.2. 401 Unauthorized ...................................................................................................................................... 10
5.3. 403 Forbidden ........................................................................................................................................... 10
5.4. 404 Not Found ........................................................................................................................................... 10
5.5. 405 Method Not Allowed .......................................................................................................................... 11
5.6. 409 Conflict ............................................................................................................................................... 11
5.7. 500 Internal Server Error ........................................................................................................................... 11
5.8. 501 Not Implemented ............................................................................................................................... 12
5.9. 503 Service Not Available .......................................................................................................................... 13
Chapter 6 Data Delivery API .......................................................................................................................... 14
6.1. Trigger export of any available data .......................................................................................................... 14
6.2. Trigger export of existing load profile data ............................................................................................... 15
6.3. Trigger export of existing Time of Use/Register data................................................................................ 15
6.4. Trigger export of existing event log data .................................................................................................. 16
6.5. Trigger all-in-one export of available data ................................................................................................ 16
6.6. Get data delivery status ............................................................................................................................ 17
Chapter 7 Measured Data API ....................................................................................................................... 19
7.1. Get Data Types .......................................................................................................................................... 19
7.2. Get Profile Data ......................................................................................................................................... 20
7.3. Get Time of Use Register Data .................................................................................................................. 23
7.4. Get Event Log Data .................................................................................................................................... 27
7.5. Get Voltage Sag/Swell, THD or Unbalance Event Data ............................................................................. 28
Chapter 8 Supply Control API ........................................................................................................................ 31
8.1. Change Main Supply Status (connect / disconnect) .................................................................................. 31
8.2. Get Main Supply status ............................................................................................................................. 33
8.3. Get Main Supply status for a device group ............................................................................................... 33
Page viii
 MultiDrive Web API 2.8 User Guide

8.4. Set Load Limiting Control .......................................................................................................................... 34

8.5. Change Main Supply Status (connect / disconnect) for Multiple Devices................................................. 36
8.6. Get Main Supply Status for Multiple Devices ............................................................................................ 39
8.7. Set Load Limiting Control for Multiple Devices ......................................................................................... 40
Chapter 9 Fleet Management API ................................................................................................................. 43
9.1. Devices ...................................................................................................................................................... 43
9.1.1. List / Search Devices ......................................................................................................................... 43
9.1.2. Get Device .......................................................................................................................................... 44
9.1.3. Protocols ............................................................................................................................................ 48
9.1.4. Device Statuses .................................................................................................................................. 49
9.1.5. Meter Series ....................................................................................................................................... 49
9.1.6. Create Device ..................................................................................................................................... 50
9.1.7. Delete Device ..................................................................................................................................... 50
9.1.8. Last Device Access Time (Scheduled and Adhoc Communications) .................................................. 51
9.1.9. Next Schedule Device Access Time .................................................................................................... 51
9.1.10. Request Pining a Device ................................................................................................................... 51
9.1.11. Get Ping Status ................................................................................................................................. 53
9.2. Sites ........................................................................................................................................................... 54
9.2.1. List / Search Sites ............................................................................................................................... 54
9.2.2. Get Site............................................................................................................................................... 54
9.2.3. Create Site .......................................................................................................................................... 57
9.2.4. Delete Site .......................................................................................................................................... 57
9.2.5. Update Site ........................................................................................................................................ 58
9.3. Device Configurations ............................................................................................................................... 58
9.3.1. List / Search Device Configurations ................................................................................................... 58
9.3.2. Get Device Configuration ................................................................................................................... 58
9.4. Device Groups ........................................................................................................................................... 59
9.4.1. List / Search Device Groups ............................................................................................................... 59
9.4.2. Get Device Group ............................................................................................................................... 60
9.4.3. Create Device Group .......................................................................................................................... 60
9.4.4. Update Device Group ......................................................................................................................... 60
9.4.5. Delete Device Group .......................................................................................................................... 61
9.4.6. List / Search Devices in Device Group ................................................................................................ 61
9.4.7. Add Devices to Device Group............................................................................................................. 61
9.4.8. Remove Device From Device Group .................................................................................................. 63
9.4.9. Configure Device to Leave and/or Join Device Groups ...................................................................... 64
9.5. Commissioning .......................................................................................................................................... 67
9.5.1. Commission a SMETS device in the system ....................................................................................... 67

Page ix
 MultiDrive Web API 2.8 User Guide

9.5.2. Request ZigBee paring for SMETS Gas Device ................................................................................... 67

9.5.3. Request ZigBee pairing for SMETS IHD device ................................................................................... 67
9.5.4. Request ZigBee un-pairing for SMETS Gas Device ............................................................................. 68
9.5.5. Request ZigBee un-pairing for SMETS IHD device.............................................................................. 68
9.5.6. Commission a device in the system ................................................................................................... 68
9.5.7. Decommission a device in the system ............................................................................................... 69
9.5.8. Decommission multiple devices in the system .................................................................................. 69
9.5.9. List / Search Commissioning Events ................................................................................................... 70
9.5.10. List / Search Gas Device Pairing Events ........................................................................................... 71
9.5.11. List / Search IHD Device Pairing Events............................................................................................ 72
9.6. Modems .................................................................................................................................................... 73
9.6.1. List / Search Modems ........................................................................................................................ 73
9.6.2. Create Modem ................................................................................................................................... 74
9.6.3. Delete Modem ................................................................................................................................... 74
9.6.4. Update Modem .................................................................................................................................. 74
9.7. SIM Cards .................................................................................................................................................. 74
9.7.1. List / Search SIMs ............................................................................................................................... 74
9.7.2. Create SIM ......................................................................................................................................... 75
9.7.3. Update SIM ........................................................................................................................................ 76
9.7.4. Delete SIM.......................................................................................................................................... 76
9.8. Gas Clorific Value....................................................................................................................................... 76
9.8.1. List / Search Gas Calorific Value ......................................................................................................... 76
9.8.2. Create Gas Calorific Value .................................................................................................................. 77
9.8.3. Delete Gas Calorific Value .................................................................................................................. 77
9.8.4. Update Gas Calorific Value ................................................................................................................ 77
9.9. Device Setups ............................................................................................................................................ 77
9.9.1. Schedule Write Device Setup Stages ................................................................................................. 77
9.9.2. Schedule Read Device Setup Stages .................................................................................................. 81
9.9.3. Get Last Read Device Setup ............................................................................................................... 83
9.9.4. Create Device Setup Template........................................................................................................... 83
9.9.5. Apply Device Setup Template ............................................................................................................ 84
Chapter 10 Scheduling API ............................................................................................................................ 86
10.1 Schedules ................................................................................................................................................. 86
10.1.1. List / Search Schedules..................................................................................................................... 86
10.1.2. Get Schedule .................................................................................................................................... 87
10.2. Executions ............................................................................................................................................... 88
10.2.1. Trigger Regular Schedule As Configured .......................................................................................... 88
10.2.2. Trigger Adhoc Schedule for particular devices ................................................................................ 89

Page x
 MultiDrive Web API 2.8 User Guide

10.2.3. List Schedule Executions .................................................................................................................. 90

10.2.4. Get Schedule Execution ................................................................................................................... 91
10.2.5. Cancel Schedule Execution .............................................................................................................. 91
10.3. Execution Jobs ......................................................................................................................................... 92
10.3.1. Search for Schedule Execution Jobs ................................................................................................. 92
10.3.2. Get Schedule Execution Job ............................................................................................................. 93
10.3.3. Get Schedule Execution Job Log ...................................................................................................... 93
10.3.4. Get Schedule Execution Job Log By Device ...................................................................................... 94
10.3.5. Get Schedule Execution Communications Log ................................................................................. 94
10.3.6. Get Schedule Execution Communications Log By Device ................................................................ 95
Chapter 11 Prepayment API .......................................................................................................................... 97
11.1. Top-up prepayment credit ...................................................................................................................... 97
11.2. Request prepayment information for a device (with EDMI Atlas Proprietary Prepayment System) ...... 98
11.3. Get prepayment information for a device (with EDMI Atlas Proprietary Prepayment System) ........... 100
11.4. Write misc. prepayment info to meter ................................................................................................. 100
11.5. Pass prepayment token to meter .......................................................................................................... 102
11.6. Generate UTRN token ........................................................................................................................... 104
11.7. Get token transfer history of 3rd-party vending system ........................................................................ 104
11.8. Request prepayment information of a device ...................................................................................... 105
11.9. Get prepayment information of a device .............................................................................................. 107
11.10. Set prepayment mode for a device ..................................................................................................... 108
11.11. Pass prepayment token to multiple meters ........................................................................................ 110
11.12. Request prepayment information of multiple devices ....................................................................... 112
11.13. Get prepayment information of multiple devices ............................................................................... 114
Chapter 12 Diagnostic API ........................................................................................................................... 116
12.1. Read Diagnostic Register ....................................................................................................................... 116
12.2. Get Diagnostic Register Value read out ................................................................................................ 119
12.3. Write Diagnostic Register ...................................................................................................................... 120
Chapter 13 Notification API ........................................................................................................................ 124
13.1. Set Notification Callback Address.......................................................................................................... 124
13.2. Acknowledge Notifications in System ................................................................................................... 125
Chapter 14 System API ................................................................................................................................ 126
14.1. Request an authentication token for the system .................................................................................. 126
14.2. Delete Authentication Token ................................................................................................................ 126
14.3. Decrypt Device Password ...................................................................................................................... 127
Chapter 15 MDDCS Configurations API ....................................................................................................... 128
15.1 Suppress Load Profile downloads on MDDCS ........................................................................................ 128
15.2 Re-enable Load Profile downloads on MDDCS....................................................................................... 130

Page xi
 MultiDrive Web API 2.8 User Guide

15.3 Request Load Profile downloads ............................................................................................................ 131

Chapter 16 API Error Codes ......................................................................................................................... 133
Chapter 17 MDX Constants ......................................................................................................................... 147
B.1. MDX – Flow Direction ............................................................................................................................. 147
B.2. MDX – Apportion Policy .......................................................................................................................... 147
B.3. MDX - Phase ............................................................................................................................................ 148
B.4. MDX – Unit Types (UOM) ........................................................................................................................ 148
B.5. MDX – Accumulation Policy .................................................................................................................... 149
Chapter 18 Device Setup Template ............................................................................................................. 150
C.1. Electric meter setup template : Change of Supplier ............................................................................... 150
C.2. Gas meter setup template : Change of Supplier ..................................................................................... 150

Page xii
 MultiDrive Web API 2.8 User Guide

Chapter

1.1. MultiDrive Web APIs

ter1
p
a
h
C

1
Overview

The MultiDrive Web APIs are divided into different components for different roles. APIs are intended to be
consistent in design and return responses in the MDX format.

Page 1
MultiDrive Web API 2.8 User Guide

Page 2
 MultiDrive Web API 2.8 User Guide

1.2. REST Background

MultiDrive Web API is adapting the "standard" RESTful web service concept. A RESTful web service (also called
a RESTful Web API) is a web service implemented using HTTP and the principles of REST. It is a collection of
resources, with four defined aspects:

• the base URI for the web service, such as http://example.com/resources/

• the Internet media type of the data supported by the web service. This is often JSON but can be any
other valid Internet media type provided that it is a valid hypertext standard.
• the set of operations supported by the web service using HTTP methods (e.g., GET, PUT, POST, or
DELETE).
• the API must be hypertext driven.

The following table shows how the HTTP methods are typically used to implement a web service.

Resource GET PUT POST DELETE

Collection URI, such as List the URIs and Replace the entire Create a new entry Delete the
http://example.com/resources/ perhaps other details collection with in the collection. entire
of the collection's another collection. The new entry's collection.
members. URI is assigned
automatically and
is usually returned
by the operation.

Element URI, such as Retrieve a Replace the Not generally used. Delete the
http://example.com/resources/i representation of the addressed member Treat the addressed
tem17 addressed member of of the collection addressed member member of
the collection, as a collection in its the
expressed in an own right collection.
appropriate Internet and create a new
media type. entry in it.

The PUT and DELETE methods are idempotent methods. The GET method is a safe method (or nullipotent),
meaning that calling it produces no side-effects.

Reference:

• http://www.codeproject.com/Articles/21258/Everything-about-REST-web-services-what-and-how-Pa
• http://rest.elkstein.org/
• http://www.peej.co.uk/articles/restfully-delicious.html
• http://en.wikipedia.org/wiki/Representational_State_Transfer#RESTful_web_services
• http://msdn.microsoft.com/en-us/library/system.web.mvc.httpverbs(v=vs.108).aspx
• http://www.thebuzzmedia.com/designing-a-secure-rest-api-without-oauth-authentication/

1.3. API Patterns

• TimeZone - All dates returned will be in UTC. All dates as parameters must be in ISO8601. As per this
format, if no time zone is specified then it will interpret dates in the server's time zone.
• Collection end points - Most documents will need to be represented within a collection element for listing
and searching. The document will often contain a subset of document attributes to reduce the response.
Collection results may need to be pagenated when there are a large number of results. If the number of
documents returned in a collection will always be minimal, the collection document may be sufficient to

Page 3
 MultiDrive Web API 2.8 User Guide

display the complete contents of all child documents. For ease of use, the collection endpoint may be
provided, without providing a separate endpoint for displaying child elements.
• Update / Create with PUT, Delete with DELETE - Where the URI is known in advance then creation is
performed using PUT. This is convenient when the element has a unique code of reference provided by
the client, as the server does not need to pass back a reference to the new document. Modification and
deletion is performed with PUT and DELETE respectively to the same endpoint address. When the URI
contains a component which is not predefined by the user (e.g. when an ID is included within the URI),
then a POST is required, and a 201 Created response is returned along with a reference to the new
document.
• Processing functions with POST - If processing functions are required a endpoint using POST is required.
• Including collection elements within documents. For ease of use, when possible the contents of a
collection for a document should be included within it's parent's document. In this case when creating or
modifying the document with PUT the contents of the collection can also be included.
• Modifying big collections with POST. If a collection could be too large to be included within a parent's
document then it is separated into a collection document. To modify elements the user can POST a set of
elements to a processing end point to add or remove items. The processing end point could be at the
collection documents end point itself.
• Id - where present, the data base ID is named \{x\}Id where \{x\} is the type of object.
• Including codes / names when referencing objects - When including the ID of a referenced element, the
related name or code is included for ease of the consumer.
• Creating objects - Objects are typically created with a PUT to the location of the desired document. For
example a site which has a unique site code would be PUT to /sites/{siteCode}. The object is passed as
JSON, XML or HTML and must correspond to the MDX specification for the object. However when creating
and modifying objects there will be attributes which cannot be set, for example IDs and collections of
related objects which are returned for ease of use. These attributes are marked as read-only in the API.

Page 4
 MultiDrive Web API 2.8 User Guide

Chapter

All APIs will be versioned.

API Versioning
ter2
p
a
h
C

Versioning is handled at the URI level. All resources will have a version number before them and will be
2
indicated as the version number alone. For example:

Measured Data API, loadProfile data, API version 1:

/measuredData/v1/loadProfile

Anything after the /v1/ is considered version 1 of the API.

There is only one version per base resource, even if accessing sub-resources, for instance.

If you are accessing list of devices in a device group:

This is a valid URI:

/fleetManagement/v1/deviceGroups/{deviceGroupId}/devices

This is not a valid URI:

/fleetManagement/v2/deviceGroups/{deviceGroupId}/v1/devices

In this case trying to use version 2 of the device groups API and then version 1 of the devices objects is not
valid. You must accept the version of devices that is used in version 2 of the entire API for device groups.

Versioning will follow these rules:

Changes That Don't Require a New Version

• New resources
• New HTTP methods on existing resources
• New data formats
• New attributes or elements on existing data types

Change That Require a New Version

• Removed or renamed URIs

• Different data returned for same URI
• Removal of support for HTTP methods on existing URIs

Page 5
 MultiDrive Web API 2.8 User Guide

Any older version may be marked for deprecation once it becomes unused.

It will be general practice to do this once it becomes two versions out of date (so once get to version 3, mark
version 1 as deprecated).

Any APIs marked as deprecated will be removed in the next major release.

Page 6
 MultiDrive Web API 2.8 User Guide

Chapter

ter3
p
a
h
C

3
API Security
The API is secured through the the use of SSL and proper certificates to secure the connection and basic HTTP
authentication to authorize users.

Basic HTTP authentication is done using the username/password of the user as current stored in
MultiDrive. This also provides the access capabilities for the user.

All users must first request an access token from the System Management API. That token then must be
passed in with all API calls.

The token is entered as part of the HTTP Authorization header:

Authorization: AuthToken “Token = <token>”

Example: Authorization: AuthToken “Token = c1a0d63e-18b6-46df-bbda-5cb0282cecdb”

All API calls must validate the token in the system before allowing any request.

• Any request for which the token does not exist (or has been deleted) will respond with a “HTTP 401
Unauthorised” response.
• Any request for which the token indicates that the user is not allowed to access will respond with a “HTTP
403 Forbidden” response.

Page 7
 MultiDrive Web API 2.8 User Guide

Chapter

API Success Responses

ter4
p
a
h
C

4
For successful operations, the API can respond with a number of different success responses. These responses
and their payloads are detailed below.

4.1. 200 OK
This indicates that the request was completed successfully.

For a GET operation, this will return the object requested.

For a PUT operation, this will return the updated object.

For a DELETE operation, this will return an empty payload.

4.2. 201 Created

This indicates that the request to create a new resource was successful.

The URN/URI to the new resource is indicated in the HTTP header Location field.

The payload will be the newly created object.

4.3. 202 Accepted

This indicates that the request has been accepted for processing.

A URN/URI to access the status of the request is indicated in the HTTP header Location field.

The payload will contain the current copy of the status (same format as would be requested via the URI given
in the location field). This is different depending on the resource.

Page 8
 MultiDrive Web API 2.8 User Guide

Chapter

API Error Responses

ter5
p
a
h
C

5
The API can respond with a number of errors. The format of the responses provided with the errors is detailed
below.

5.1. 400 Bad Request

This error indicates that the request was invalid. The errors list will contain details on any element which is
invalid.
{
"errorMessage": {
"status" : "409",
"dateTime" : "2013-01-21T10:00:00",
"message" : "The device you try to create already exists",
"errorCode" : "Device-400",
"errors" : [
{
"message" : "The device already exists",
"errorCode" : "Device-400",
"detail" : "fleetManagement/device/123",
}
],
}
}
Description
Property Optional/ Format Description
Mandatory
errorMessage
status Mandatory Text HTTP status code associated with error
dateTime Mandatory Text Date and Time of error
message Mandatory Text User friendly error message
errorCode Mandatory Text A unique numeric code for the
error. See API Error Codes for more
info.
errors This contains any items which are
associated with the error.
For example a 409 error would contain
a list of the ids which conflict here.
message Mandatory Text This contains a individual error
message
errorCode Mandatory Text A unique numeric code for the
individual error. See API Error Codes
for more info.
detail Optional Text This contains any detail (ie. URI,
identifiers etc) associated with the
individual error

Page 9
 MultiDrive Web API 2.8 User Guide

5.2. 401 Unauthorized

This error indicates that the token provided is indicated or not found. No error message is given.

For operations which request or delete a token, this indicates that the username or password provided via basic
authentication was not found or invalid.

5.3. 403 Forbidden

This error indicates that the user is not allowed to access this resource via this operation. No error message is
given.

For operations which request or delete a token, this indicates that the username provided has been disabled in
the system.

5.4. 404 Not Found

This error indicates that the requested resource was not found. The errors list will contain details on any
element which has not been found with the detail value containing the URI of the not found resource.

{
"errorMessage": {
"status" : "409",
"dateTime" : "2013-01-21T10:00:00",
"message" : "The device you try to create already exists",
"errorCode" : "Device-400",
"errors" : [
{
"message" : "The device already exists",
"errorCode" : "Device-400",
"detail" : "fleetManagement/device/123",
}
],
}
}

Description
Property Optional/ Format Description
Mandatory
errorMessage
status Mandatory Text HTTP status code associated with error
dateTime Mandatory Text Date and Time of error
message Mandatory Text User friendly error message
errorCode Mandatory Text A unique numeric code for the error. See API
Error Codes for more info.
errors This contains any items which are associated
with the error.
For example a 409 error would contain a list
of the ids which conflict here.
message Mandatory Text This contains a individual error message
errorCode Mandatory Text A unique numeric code for the individual
error. See API Error Codes for more info.
detail Optional Text This contains any detail (ie. URI, identifiers
etc) associated with the individual error

Page 10
 MultiDrive Web API 2.8 User Guide

5.5. 405 Method Not Allowed

This indicates that the resource does not support the HTTP method specified by the request e.g. if you try a
PUT on a resource that only supports GETs. No error message is given with this error.

5.6. 409 Conflict

This error indicates that the resource the user is trying to create conflicts with an existing resource. The errors
list will contain details on any element which is conflicting with the detail value containing the URI of the
conflicting resource.

{
"errorMessage": {
"status" : "409",
"dateTime" : "2013-01-21T10:00:00",
"message" : "The device you try to create already exists",
"errorCode" : "Device-400",
"errors" : [
{
"message" : "The device already exists",
"errorCode" : "Device-400",
"detail" : "fleetManagement/device/123",
}
],
}
}

Description
Property Optional/ Format Description
Mandatory
errorMessage
status Mandatory Text HTTP status code associated with error
dateTime Mandatory Text Date and Time of error
message Mandatory Text User friendly error message
errorCode Mandatory Text A unique numeric code for the error. See API
Error Codes for more info.
errors This contains any items which are associated
with the error.
For example a 409 error would contain a list
of the ids which conflict here.
message Mandatory Text This contains a individual error message
errorCode Mandatory Text A unique numeric code for the individual
error. See API Error Codes for more info.
detail Optional Text This contains any detail (ie. URI, identifiers
etc) associated with the individual error

5.7. 500 Internal Server Error

This error indicates an internal problem with the system and the request cannot be completed. The error
response contains the related error message and any individual errors (if multiple errors occur). The detail
may contain developer information.

{
"errorMessage": {
"status" : "409",
"dateTime" : "2013-01-21T10:00:00",
"message" : "The device you try to create already exists",
"errorCode" : "Device-400",
"errors" : [
{
"message" : "The device already exists",

Page 11
 MultiDrive Web API 2.8 User Guide

"errorCode" : "Device-400",
"detail" : "fleetManagement/device/123",
}
],
}
}

Description
Property Optional/ Format Description
Mandatory
errorMessage
status Mandatory Text HTTP status code associated with error
dateTime Mandatory Text Date and Time of error
message Mandatory Text User friendly error message
errorCode Mandatory Text A unique numeric code for the error. See API
Error Codes for more info.
errors This contains any items which are associated
with the error.
For example a 409 error would contain a list
of the ids which conflict here.
message Mandatory Text This contains a individual error message
errorCode Mandatory Text A unique numeric code for the individual
error. See API Error Codes for more info.
detail Optional Text This contains any detail (ie. URI, identifiers
etc) associated with the individual error

5.8. 501 Not Implemented

This error indicates that API called is not implemented with the current version of MultiDrive deployed. The
error response contains the related error message and any individual errors (if multiple errors occur). The
detail may contain developer information.

{
"errorMessage": {
"status" : "409",
"dateTime" : "2013-01-21T10:00:00",
"message" : "The device you try to create already exists",
"errorCode" : "Device-400",
"errors" : [
{
"message" : "The device already exists",
"errorCode" : "Device-400",
"detail" : "fleetManagement/device/123",
}
],
}
}

Description
Property Optional/ Format Description
Mandatory
errorMessage
status Mandatory Text HTTP status code associated with error
dateTime Mandatory Text Date and Time of error
message Mandatory Text User friendly error message
errorCode Mandatory Text A unique numeric code for the error. See API
Error Codes for more info.
errors This contains any items which are associated
with the error.
For example a 409 error would contain a list of
the ids which conflict here.

Page 12
 MultiDrive Web API 2.8 User Guide

message Mandatory Text This contains a individual error message

errorCode Mandatory Text A unique numeric code for the individual
error. See API Error Codes for more info.
detail Optional Text This contains any detail (ie. URI, identifiers etc)
associated with the individual error

5.9. 503 Service Not Available

This error indicates a timeout has occurred. No error message is given with this error.
A retry time may be indicated in the Retry-After field in the HTTP header.

Page 13
 MultiDrive Web API 2.8 User Guide

Chapter

6.1. Trigger export of any available data

Data Delivery API
ter6
p
a
h
C

6
URL /dataDelivery/all/{deviceId}
/dataDelivery/all/plantNumber/{plantNumber}
/dataDelivery/all/deviceGroup/{deviceGroupId}
/dataDelivery/all/deviceGroup/name/{deviceGroupName}
Method POST
Permission Permission checking will vary depending on the dataType specified:
LOADPROFILE : mdpProfileData [View]
TOU : mdpTOUData [View]
EVENTLOG : mdpDeviceEventLog [View]
Parameters Name Description Type Optional/ Valid values Default
Mandatory
startDate Inclusive start date of load date Mandatory
profile data to export
endDate Inclusive end date of load date Mandatory
profile data to export
dataType The types of data to export, string Optional LOAD_PROFILE, TOU, *
values seperated by commas. EVENT_LOG
If not specified, then any data
from the list is exported
Returns 202 Accepted
401 Unauthorized (Token invalid)
403 Forbidden (Access not allowed)
404 Not Found (Device Id, plant number or device group Id does not exist)
500 Internal Server Error
{
"dataDeliveries" : [
{
"deviceId" : 1,
"deliveryId" : 8867,
"dataType" : "LOAD_PROFILE",
"data": "LOAD_PROFILE1"
},
{
"deviceId" : 2,
"deliveryId" : 8868,
"dataType" : "TOU",
"data": "BILLING_TOTAL"
},
{
"deviceId" : 3,
"dataType" : "LOAD_PROFILE",
"data": "LOAD_PROFILE2",
"errorMessage":
{
"status":"400",
"dateTime":"2013-11-08T08:18:32.6348671Z",
"message":"No associated data mapping for selected Load Profiles",
"errorCode":"DataDelivery-012"
}
},
{
"deviceId" : 4,

Page 14
 MultiDrive Web API 2.8 User Guide

"dataType": "EVENT_LOG",
"data" : "TAMPER",
"errorMessage":
{
"status":"400",
"dateTime":"2013-11-08T08:24:01.796Z",
"message":"Selected Event Type is not supported",
"errorCode":"DataDelivery-009"
}
}
]
}

6.2. Trigger export of existing load profile data

URL /dataDelivery/loadProfile/{deviceId}
/dataDelivery/loadProfile/plantNumber/{plantNumber}
/dataDelivery/loadProfile/deviceGroup/{deviceGroupId}
/dataDelivery/loadProfile/deviceGroup/name/{deviceGroupName}
Method POST
Permission mdpProfileData [View]
Parameters Name Description Type Optional/ Valid values Default
Mandatory
startDate Inclusive start date of date Mandatory
load profile data to
export
endDate Inclusive end date of date Mandatory
load profile data to
export
profileNumber Load Profile(s) to string Optional SPECIAL_PROFILE,
export, values LOAD_PROFILE1,
separated by commas LOAD_PROFILE2 ...
LOAD_PROFILE10
Returns 202 Accepted - same as in Export of Any Available Data operation
400 Bad Request (no associated data mapping for selected Load Profiles, more than 1 associated data
mapping for selected Load Profiles, no associated manual mapping, no Quantity Channels for selected
Load Profiles, no devices under the selected group )
401 Unauthorized (Token invalid)
403 Forbidden (Access not allowed)
404 Not Found (Device Id, plant number or device group Id does not exist)
500 Internal Server Error

6.3. Trigger export of existing Time of Use/Register data

URL /dataDelivery/timeOfUse/{deviceId}
/dataDelivery/timeOfUse/plantNumber/{plantNumber}
/dataDelivery/timeOfUse/deviceGroup/{deviceGroupId}
/dataDelivery/timeOfUse/deviceGroup/name/{deviceGroupName}
Method POST
Permission mdpTOUData [View]
Parameters Name Description Type Optional/ Valid values Default
Mandatory
startDate Inclusive start date of load date Mandatory
profile data to export
endDate Inclusive end date of load date Mandatory
profile data to export
periodType The type of Time of Use string Optional TOTAL, *
register to fetch, values BILLING_TOTAL,
separated by commas CURRENT,
PREVIOUS_1
Returns 202 Accepted - same as in Export of Any Available Data operation

Page 15
 MultiDrive Web API 2.8 User Guide

400 Bad Request (selected Period Type is not supported, no associated data mapping for selected TOU,
no associated manual mapping, no Quantity Channels for selected TOU, no devices under the selected
group )
401 Unauthorized (Token invalid)
403 Forbidden (Access not allowed)
404 Not Found (Device Id, plant number or device group Id does not exist)
500 Internal Server Error

6.4. Trigger export of existing event log data

URL /dataDelivery/eventLog/{deviceId}
/dataDelivery/eventLog/plantNumber/{plantNumber}
/dataDelivery/eventLog/deviceGroup/{deviceGroupId}
/dataDelivery/eventLog/deviceGroup/name/{deviceGroupName}
Method POST
Permission Permission checking will vary depending on the eventType specified:
mdpDeviceEventLog [View]
SAGSWELL : mdpSagSwellLog [View]
TAMPER : mdpDeviceTamperLog [View]
Parameters Name Description Type Optional/ Valid values Default
Mandatory
startDate Inclusive start date of date Mandatory
load profile data to
export
endDate Inclusive end date of load date Mandatory
profile data to export
eventType The type of event to string Optional SYSTEM, ACCESS,
export TAMPER,
SAG_SWELL, ALARM
Returns 202 Accepted - same as in Export of Any Available Data operation
400 Bad Request (selected Event Type is not supported, no devices under the selected group )
401 Unauthorized (Token invalid)
403 Forbidden (Access not allowed)
404 Not Found (Device Id, plant number or device group Id does not exist)
500 Internal Server Error

6.5. Trigger all-in-one export of available data

URL /dataDelivery/all-in-one/{deviceId}
/dataDelivery/all-in-one/plantNumber/{plantNumber}
/dataDelivery/all-in-one/deviceGroup/{deviceGroupId}
/dataDelivery/all-in-one/deviceGroup/name/{deviceGroupName}
Method POST
Permission Permission checking will vary depending on the dataType specified:
LOADPROFILE : mdpProfileData [View]
TOU : mdpTOUData [View]
EVENTLOG : mdpDeviceEventLog [View]
Parameters Name Description Type Optional/ Valid values Default
Mandatory
startDate Inclusive start date of date Mandatory
load profile data to
export
endDate Inclusive end date of load date Mandatory
profile data to export
dataType The types of data to string Optional LOAD_PROFILE, TOU, *
export, values seperated EVENT_LOG
by commas.

Page 16
 MultiDrive Web API 2.8 User Guide

If not specified, then any

data from the list is
exported
Returns 202 Accepted
401 Unauthorized (Token invalid)
403 Forbidden (Access not allowed)
404 Not Found (Device Id, plant number or device group Id does not exist)
500 Internal Server Error
The 202 Accepted response will be accompanied by the following payload.
{
"dataDeliveries" : [
{
"deviceId" : 1,
"deliveryId" : 8867,
"dataType" : "LOAD_PROFILE",
"data": "LOAD_PROFILE1"
},
{
"deviceId" : 1,
"deliveryId" : 8867,
"dataType" : "TOU",
"data": "BILLING_TOTAL"
},
{
"deviceId" : 2,
"deliveryId" : 8868,
"dataType" : "LOAD_PROFILE",
"data": "LOAD_PROFILE1"
},
{
"deviceId" : 2,
"dataType" : "LOAD_PROFILE",
"data": "LOAD_PROFILE2",
"errorMessage":
{
"status":"400",
"dateTime":"2013-11-08T08:18:32.6348671Z",
"message":"No associated data mapping for selected Load Profiles",
"errorCode":"DataDelivery-012"
}
},
{
"deviceId" : 3,
"dataType": "EVENT_LOG",
"data" : "TAMPER",
"errorMessage":
{
"status":"400",
"dateTime":"2013-11-08T08:24:01.796Z",
"message":"Selected Event Type is not supported",
"errorCode":"DataDelivery-009"
}
}
]
}

WARNING:
The following variations of the method may suffer from slow response when called for a device
group containing large number of devices.
/dataDelivery/all-in-one/deviceGroup/{deviceGroupId}
/dataDelivery/all-in-one/deviceGroup/name/{deviceGroupName}
Note This method triggers data delivery by generating an all-in-one process job (GUID: 6CAC301F-FFB7-
432C-8ADD-C9E1C8021704).

6.6. Get data delivery status

URL /dataDelivery/status/{deliveryId}
Method GET
Permission NA
Returns 200 OK
401 Unauthorized (Token invalid)
403 Forbidden (Access not allowed)
404 Not Found (Delivery Id does not exist)
Page 17
 MultiDrive Web API 2.8 User Guide

500 Internal Server Error

{
"dataDeliveryStatus" :
{
"deliveryId" : 14,
"createTime" : "2013-01-21T10:00:00",
"statusTime" : "2013-01-21T10:00:00",
"priority" : 1,
"status" : "Successful",
"log" : "Did some stuff\nWent better than expected",
},
}

Description
Property Format Description
dataDeliveryStatus
deliveryId Integer A unique identifier for the data delivery (Map to tblProcessJobs.JobId)
createTime ISO8601 Date/Time job was created
statusTime ISO8601 Date/Time of last status update
priority Integer The current priority of the job
status String Current status of the job.
Valid statuses are:
• Unassigned
• Assigned
• Processing
• Successful
• Failed
• Aborted
log String Log string

Page 18
 MultiDrive Web API 2.8 User Guide

Chapter

7.1. Get Data Types

Measured Data API
ter7
p
a
h
C

7
URL /measuredData/dataTypes
Method GET
Permission None
Parameters Name Description Type Optional/ Valid Default
Mandatory values
name Filter by a match in the data type name string Optional -
Returns 200 OK
400 Bad Request (Hash is not valid or timestamp is too old)
401 Unauthorized (Username/password is invalid)
403 Forbidden (Username has been disabled)
500 Internal Server Error
{
"dataTypes" : [
{
"bitRepresentation" : 4112,
"name" : "Import Wh Phase A",
"units" : "Wh",
"flowDirection" : "Consumption",
"phase" : "A"
"apportionPolicy" : "SUM" ,
"decimalPlaces" : 3,
"multiplier" : 1000
},...
]
}

Description
Property Optional/ Format Description
Mandatory
bitRepresentation Mandatory Integer Integer for binary representation of data type
name Mandatory Text ( ) Name of the data type
units Mandatory See appendix C Unit of measure.
flowDirection Mandatory Text ( ) Flow direction, e.g. "Consumption", "Absolute" or "Q1"
Flow direction must be valid for UOM. See Appendix C.
phase Mandatory See Appendix E Phase, e.g. "A" or "AB".
apportionPolicy Mandatory See Appendix F The rule to follow when apportioning (for example, when
viewing 15-minute day apportioned to 1-day intervals).
decimalPlaces Mandatory
multiplier Mandatory

Page 19
 MultiDrive Web API 2.8 User Guide

7.2. Get Profile Data

URL /measuredData/loadProfile/{deviceId}
/measuredData/loadProfile/plantNumber/{plantNumber}
Method GET
Permission mdpProfileData [View]
Parameters Name Description Type Optional/ Valid Default
Mandatory values
startDate The date to start the data string Mandatory -
period
endDate The date to end the data string Mandatory -
period (max of 1 month
from startDate)
limit Maximum number of Integer Optional 0 -5000 5000
records to return status for
in response
offset Offset in devices to start Integer Optional * 0
returning records from
loadSurveyNumber Identifier of load survey Integer Optional * 0
from the channels of which
the profile data is retrieved
(0 = all load surveys)
dataTypeId Identifier of data type of Integer Optional * -
the channel from which the
profile data is retrieved
Notes:
1. If both loadSurveyNumber and dataTypeId are specified, data will only be returned if a channel
of the specified data type is defined in the specfied load survey.
2. If only dataTypeId is specified, data will be returned for a channel of the specified data type as
long as it is defined in any of the load surveys.
3. If only loadSurveyNumber is specfied, data will be returned for all the channels defined in the
specified load survey.
Returns 200 OK
400 Bad Request (length of data is invalid or too long)
401 Unauthorised (Token invalid)
403 Forbidden (Access not allowed)
404 Not Found (Device Id Does not exist)
{
"intervalDataSets" : [{
"code" : "LS1",
"description" : "Load survey 1",
"intervalLength" : 30,
"intervalLengthUnits" : "MINUTE",
"channels" : [{
"name":"E1",
"units":"Wh",
"flowDirection":"DELIVERED",
"apportionPolicy":"SUM",
"phase":"NONE",
"accumulationPolicy":"CUMULATIVE"
},{
"name":"Q1",
"units":"Varh",
"flowDirection":"DELIVERED",
"apportionPolicy":"SUM",
"phase":"NONE"
},{
"name":"E2",
"units":"Wh",
"flowDirection":"DELIVERED",
"apportionPolicy":"SUM",
"phase":"NONE"
}],
"intervals" : [{
"endOfInterval" : "2013-01-22T00:00:00+0000",
"values" : [ 2042.32, 3401.3, 34 ]
},{
"endOfInterval" : "2013-01-22T00:00:00+0000",
"values" : [ 2142.32, 2201.2, 23 ]
},{

Page 20
 MultiDrive Web API 2.8 User Guide

"endOfInterval" : "2013-01-22T00:00:00+0000",
"values" : [ 3352, 3301.3, 56.6 ]
},{
"endOfInterval" : "2013-01-22T00:00:00+0000",
"values" : [ 2022.11, 3014.3, 23 ]
},{
"endOfInterval" : "2013-01-22T00:00:00+0000",
"values" : [ 2342.2, 3441.3, 23.1 ]
},{
"endOfInterval" : "2013-01-22T00:00:00+0000",
"values" : [ 2344.31, 2591.07, 80.33 ],
"statuses" : ["AR"]
}]
}]
}

Description – intervalDataSet
Mandatory. Each intervalDataSet normally corresponds to the data (values and per-interval status flags) read for a
particular load survey. All intervals within it must share the same length. However, different intervalDataSet elements
may have different interval lengths, different channels, etc. Where a meter has more than one load survey, the data for
each load survey should be supplied in a separate intervalDataSet.

Property Optional/ Format Description

Mandatory
Mandatory - Each intervalDataSet normally
corresponds to the data (values
and per-interval status flags) read
for a particular load survey. All
intervals within it must share the
same length. However, different
intervalDataSet elements may
have different interval lengths,
different channels, etc. Where a
meter has more than one load
survey, the data for each load
survey should be supplied in a
separate intervalDataSet.
code Optional Text (20) Optional short identifier for the
data set, e.g. "LS2"
description Optional Text (100) Optional text description of the
intervalDataSet, e.g. "Load Survey
2".
intervalLength Mandatory Integer Length of each interval in the set.
Supported values (for minutes or
seconds) are 1, 5, 10, 15, 20, 30,
60.
intervalLengthUnits Mandatory See Calendar The unit the interval length is
Interval expressed in. At the moment only
Length Units SECOND and MINUTE are
supported.
channel Mandatory Defines an interval (load survey)
channel as accurately as possible.
name Optional Text (50) A custom label for the channel.
units Mandatory See MDX - Unit of measure.
Unit Types
(UOM)
flowDirection Mandatory See MDX - Flow direction, e.g. "DELIVERED",
Flow "ABSOLUTE" or "Q1".
Direction Flow direction must be valid for
UOM (See MDX - Unit Types
(UOM))
phase Mandatory See MDX - Phase, e.g. "A" or "AB".
Phase
Page 21
 MultiDrive Web API 2.8 User Guide

apportionPolicy Mandatory See MDX - The rule to follow when

Apportion apportioning (for example, when
Policy viewing 15-minute day
apportioned to 1-day intervals).
accumulationPolicy Optional See MDX – Default "INTERVAL"
Accumulation
Policy Indicate how values have been
accumulated during the
measurement period
interval Mandatory - Contains one value for each
channel for a particular interval.
endOfInterval Mandatory ISO8601 The end date & time of the
interval. Timezones accept only
numeric values. 1200 equates to
GMT+12:00.
values Mandatory - All channel values for this interval
value Mandatory Numeric The value of the channel for the
containing interval.
For missing data, set the status
flag to "AR", or use a blank value,
i.e. <value></value> or null in
json
statuses Optional - Holds the collection of statuses
that apply to the
interval. Examples of statuses
include power cut and equipment
failure alarms. Statuses are not
specific to individual channels.
status Optional See Interval This holds a code for a particular
Status Codes interval status that applies to the
containing interval, for example
"AP" for "Asymmetric Power".

Data Gaps
MultiDrive may export reads containing gaps - these will NOT be filled in automatically. Gaps between reads (i.e. between
data in separate files) can occur when a meter has been reset or when there is a sufficiently large gap between reads.

Calendar Interval Length Units

Units that time is measured in, as opposed to rates that events occur at (see PeriodType below).

Unit Description
MILLISECOND Milliseconds.
SECOND Seconds.
MINUTE Minutes.
HOUR Hours.
DAY Days.
WEEK Weeks.
MONTH Months.
YEAR Years.

Interval Status Codes

Device Flag in Description Atlas Profile Genius Profile MD Profile status
MDM ( GUI) Status Status Bit Field
AR Absent Reading - Filled entry - no data. All data A A 10
values to be ignored (they will generally be zero)
II Incomplete interval. I I 12
Normally this specifies any interval where the
interval was short or long, whether due to a time

Page 22
 MultiDrive Web API 2.8 User Guide

change or power outage, or the very first

interval.
When the Load Survey I Flag on all Intervals with
a Time Change option is set (See Figure 16-2)
then the I flag only flags intervals where a time
change occurred (or that a time change skipped
over). Usually used with the P flag option on the
same page, this separates the P and I flags to
indicate short/long intervals due to time
changes, or short/long intervals due to power
outage.
PL Power failed during interval. This is set in the P P 9
interval where power was lost, not where it just
continued to be lost or was restored.
The operation can be changed to indicate the P
flag in all intervals where power was lost,
restored, or continued to be lost, using the Load
Survey P Flag on all Intervals with a Power
Outage setting.
UD1 User programmable flag derived from the active L L 13
EFA status.
MV90 labels this as a critical error using interval
bit 5.
UD2 User programmable flag derived from the active W 14
EFA status.
MV90 labels this as a clock error using channel
bit 7.
UD3 User programmable flag derived from the active U 15
EFA status.
MV90 labels this as a VT failure using channel bit
9.
May also be configured to indicate a setup
change using the Load Survey U Flag Records
Setup Changes.
MF Memory Failure or data check-sum error. This B 8
record should be treated with caution.
MD Data was manually modified using MultiDrive 0
System
ED Data was manually estimated using MultiDrive 1
System
SD Data was manually substituted using MultiDrive 2
System
ID Data was marked invalid in MultiDrive System 3
UF1 Data was marked as user flag 1 in MultiDrive 4
System
UF2 Data was marked as user flag 2 in MultiDrive 5
System
UF3 Data was marked as user flag 3 in MultiDrive 6
System
UF4 Data was marked as user flag 4 in MultiDrive 7
System

7.3. Get Time of Use Register Data

URL /measuredData/timeOfUse/{deviceId}
/measuredData/timeOfUse/plantNumber/{plantNumber}
Method GET
Permission mdpTOUData [View]

Page 23
 MultiDrive Web API 2.8 User Guide

Parameters Name Description Type Optional/ Valid values Default

Mandatory
startDate The date to start the data string Mandatory -
period
endDate The date to end the data string Mandatory -
period (max of 1 month
from startDate)
periodType The type of TOU register to string Optional TOTAL, CURRENT, *
fetch, values separated by BILLING_TOTAL,
commas PREVIOUS,
PREVIOUS_{X}
limit Maximum number of Integer Optional 0 - 5000 5000
records to return status for
in response
offset Offset in devices to start Integer Optional * 0
returning records from
Returns 200 OK
400 Bad Request (parameters are not valid)
401 Unauthorised (Token invalid)
403 Forbidden (Access not allowed)
404 Not Found (Device Id Does not exist)
Fetches Time of Use register values between the query dates. May filter on the periodType if supplied, if
not then all period types returned.

{
"registerDataSets": [{
"recordDateTime": "2012-06-10T12:30:00.000+0000",
"periodType": "PREVIOUS",
“billingSystem”: 1,
"billingResetCount": 2,
"billingResetTime": "2012-06-09T12:30:00.000+0000",
"registers": [{
"units": "WH",
"flowDirection": "DELIVERED",
"phase": "TOTAL",
"apportionPolicy": "SUM",
"touRate": "TOTAL",
"registerValue": {
"value": 123,
}
},{
"units": "WH",
"flowDirection": "DELIVERED",
"phase": "TOTAL",
"apportionPolicy": "SUM",
"touRate": "1",
"registerValue": {
"value": 100
}
},{
"units": "WH",
"flowDirection": "DELIVERED",
"phase": "TOTAL",
"apportionPolicy": "SUM",
"touRate": "2",
"registerValue": {
"value": 23
}
},{
"units": "varh",
"flowDirection": "DELIVERED",
"phase": "TOTAL",
"apportionPolicy": "SUM",
"touRate": "TOTAL",
"registerValue": {
"value": 345
}
},{
"units": "W",
"flowDirection": "NONE",
"phase": "TOTAL",
"apportionPolicy": "MAX", // value recorded is MAXIMUM demand
"touRate": "TOTAL",
"registerValue": {
"value": 567,
"dateTime": "2012-06-10T12:42:00.000+0000", // time of max demand

Page 24
 MultiDrive Web API 2.8 User Guide

}
},{
"units": "var",
"flowDirection": "NONE",
"phase": "TOTAL",
"apportionPolicy": "MAX",
"touRate": "TOTAL",
"registerValue": {
"value": 890,
"dateTime": "2012-06-10T12:45:04.000+0000", // time of max demand
}
}]
}]

Description – registerDataSet
Mandatory. All the (tou) registers for a single billing reset.

Property Optional/ Format Description

Mandatory
recordDateTime Mandatory ISO8601 The date and time at which the
register data was recorded.
periodType Mandatory See Period Type of period the energy and/or
Types maximum demand channels have
been computed over.
billingSystem Optional Numeric To differentiate 2 different billing
systems being supported:
1: Generic TOU (Default, normally
configured as Monthly)
2: Daily TOU Snapshot
billingResetCount Optional Numeric The number of billing resets that
have been performed since the
meter was installed.
billingResetTime Optional ISO8601 The date and time at which the last
billing reset was performed.
register Mandatory - Describes a single TOU register and
(1..* its value
Occurances)
units Mandatory See MDX - Unit of measure.
Unit Types
(UOM)
flowDirection Mandatory See MDX - Flow direction, e.g. "DELIVERED",
Flow "ABSOLUTE" or "Q1"
Direction Flow direction must be valid for
UOM. (See MDX - Unit Types
(UOM))
phase Mandatory See MDX - Phase, e.g. "A" or "AB".
Phase
apportion Mandatory See MDX - The rule to follow when
policy Apportion apportioning (for example, when
Policy viewing 15-minute day apportioned
to 1-day intervals).
touRate Mandatory Text The number of the TOU rate
the value is for, or TOTAL if it is not
for a specific TOU band.
block Integer The block number for use when
block tariffs are defined in the
meter
registerValue Mandatory - Wrapper for a register value and its
attributes.
value Mandatory Mandatory Numeric value for the channel, e.g.
energy or demand value.

Page 25
 MultiDrive Web API 2.8 User Guide

dateTime Optional ISO8601 Where the value is for a maximum

demand channel, this is the date
recorded for that value.

Period Types
Type of period a register value relates to.

Period Type Energy Values Maximum Demand Values

TOTAL Values are the total amount of energy Values are the sum of the individual maximum
accumulated since the meter was installed or its demand values recorded since the meter was
registers were reset to 0. installed or its registers were reset to 0 until
now.
BILLING_TOTAL, Values are a snapshot of the cumulative energy Values are the sum of the individual maximum
PREVIOUS values taken at the time of a specific billing demand values recorded since the meter was
reset as given by installed or its registers were reset to 0 up and
the recordDateTimeelement. Depending on the to the last billing reset.
meter configuration, they can be either
• Cumulative - Values are the total amount of
energy accumulated since the meter was
installed until recordDateTime. This is the
most common configuration by far.
• Interval - Values are the amount of energy
used during the billing period
ended recordDateTime. (as depicted in the
diagram below). This means they are like
long intervals (e.g. a day or a month) rather
than cumulative totals.
CURRENT Values are the amount of energy accumulated Values are the maximum demand values
between the last billing reset and the current recorded since the last billing reset until now.
time. (i.e. the amount of energy consumed in
the current billing period.)
CURRENT = TOTAL - BILLING_TOTAL

MDX Register Period Types

Example showing monthly billing reset for an interval based meter configuration.

Page 26
 MultiDrive Web API 2.8 User Guide

Supported Register Channels

The following Register Channel attributes will be supported by default:

Units Directions Apportion Policies Phases Rates Input Period Type

Number
Wh, DELIVERED, RECEIVED SUM NONE TOTAL, 1-8 0, 1, 2 PREVIOUS,
varh, CURRENT, BILLING
VAh TOTAL ,TOTAL
Wh, DELIVERED, RECEIVED SUM A, B, C TOTAL 0 PREVIOUS,
varh, CURRENT, BILLING
VAh TOTAL ,TOTAL
W, NONE, DELIVERED, MIN, MAX, AVG, NONE TOTAL, 1-8 0, 1, 2 PREVIOUS,
VA, RECEIVED INST CURRENT, BILLING
var TOTAL ,TOTAL
W, NONE, DELIVERED, MIN, MAX, AVG, A, B, C TOTAL 0 PREVIOUS,
VA, RECEIVED INST CURRENT, BILLING
var TOTAL ,TOTAL

7.4. Get Event Log Data

URL /measuredData/eventLog/{deviceId}
/measuredData/eventLog/plantNumber/{plantNumber}
Method GET
Permission mdpDeviceEventLog [View]
Parameters Name Description Type Optional/ Valid Default
Mandatory values
startDate The date to start the data period string Mandatory -
endDate The date to end the data period (max string Mandatory -
of 1 month from startDate)
logNumber The identifier for the required event Integer Optional * 0
log (0 = all event logs)
limit Maximum number of records to Integer Optional 0 - 5000 5000
return status for in response
offset Offset in devices to start returning Integer Optional * 0
records from
Returns 200 OK
400 Bad Request (parameters are invalid)
401 Unauthorised (Token invalid)
403 Forbidden (Access not allowed)
404 Not Found (Device Id Does not exist)
All device events are encapsulated into this object. This includes normal device events, voltage sag/swell
events, THD/Unbalance events and tamper events.
{
"events": [{
"code": "1.0.1.1",
"logNumber": 0,
"description": "Power on: connected",
"eventDateTime": "2012-06-11T00:00:00.000+0000",
"parameters": [{
"name": "extremeAmplitude",
"value": "1.00"
}]
},
{
"code": "3.4.17.42",
"description": "Relay connected",
"parameters": [{
"name": "relayNumber",
"value": "Relay 3"
},{
"name": "relayOperationType",
"value": "Disconnect Button"
}]
}]
}

Page 27
 MultiDrive Web API 2.8 User Guide

Description
Property Optional/ Format Description Notes
Mandatory
code Mandatory As per the EndDeviceEvent Codes will be supported
'EndDeviceEvent' category covering all meter
definition in IEC types. iBO will handle
61968-9: translation from MD
"<domain>. codes to iBO's internal
<domainpart>. event types.
<type>.<index>" Parameters will be more
(each of these 4 meter specific to provide
fields are richer detail where this
numeric only) exists
description Optional Text Description of This is useful if the code
type of event, is
e.g. "Power on" not understood/mappabl
e at importion for
context
logNumber Optional Numeric The log in This will be ignored by
which this the importer
event was
recorded in.
eventDateTime Mandatory ISO8601 Date and time
event was
recorded by the
meter.
parameters Optional Defines an
event
parameter
name/value
pair
parameter Optional There could be 0, 1 or
(0..* multiple parameters for
occurrences) each event
name Mandatory Text The name of
the parameter
value Mandatory Text The value of
the parameter

7.5. Get Voltage Sag/Swell, THD or Unbalance Event Data

URL /measuredData/sagSwell/{deviceId}
/measuredData/sagSwell/plantNumber/{plantNumber}
Method GET
Permission mdpSagSwellLog [View]
Parameters Name Description Type Optional/ Valid Default
Mandatory values
startDate The date to start the data period string Mandatory -
endDate The date to end the data period (max of string Mandatory -
1 month from startDate)
limit Maximum number of records to return Integer Optional 0 - 5000 5000
status for in response
offset Offset in devices to start returning Integer Optional * 0
records from
Returns 200 OK
400 Bad Request (parameters are invalid)
401 Unauthorised (Token invalid)
403 Forbidden (Access not allowed)
404 Not Found (Device Id Does not exist)

Page 28
 MultiDrive Web API 2.8 User Guide

All device events are encapsulated into this object. This includes normal device events, voltage sag/swell
events, THD/Unbalance events and tamper events.
{
"events": [{
"code": "1.0.1.1",
"logNumber": 0,
"description": "Power on: connected",
"eventDateTime": "2012-06-11T00:00:00.000+0000",
"parameters": [{
"name": "extremeAmplitude",
"value": "1.00"
}]
},
{
"code": "3.4.17.42",
"description": "Relay connected",
"parameters": [{
"name": "relayNumber",
"value": "Relay 3"
},{
"name": "relayOperationType",
"value": "Disconnect Button"
}]
}]
}

Specific example of a sag/well, THD or unbalance event.

{
"events": [{
"code": "6.0.1.1",
"logNumber": 3,
"description": "Sag event",
"eventDateTime": "2012-06-11T00:00:00.000+0000",
"parameters": [
{
"name": "eventType",
"value": "Voltage"
},
{
"name": "phase",
"value": "phaseA"
},
{
"name": "duration",
"value": 1.00
},
{
"name": "extremeAmplitude",
"value": 270.00
},
{
"name": "averageAmplitude",
"value": 250.00
}
]
}
]
}

Description of Events
Property Optional/ Format Description Notes
Mandatory
code Mandatory As per the EndDeviceEvent Codes will be supported
'EndDeviceEvent' category covering all meter
definition in IEC types. iBO will handle
61968-9: translation from MD
"<domain>. codes to iBO's internal
<domainpart>. event types.
<type>.<index>" Parameters will be more
(each of these 4 meter specific to provide
fields are richer detail where this
numeric only) exists
description Optional Text Description of This is useful if the code
type of event, is
e.g. "Power on" not understood/mappabl

Page 29
 MultiDrive Web API 2.8 User Guide

e at importion for
context
logNumber Optional Numeric The log in This will be ignored by
which this the importer
event was
recorded in.
eventDateTime Mandatory ISO8601 Date and time
event was
recorded by the
meter.
parameters Optional Defines an
event
parameter
name/value
pair
parameter Optional There could be 0, 1 or
(0..* multiple parameters for
occurrences) each event
name Mandatory Text The name of
the parameter
value Mandatory Text The value of
the parameter

Description of parameters
Property Format Description
eventType Text The type of sag/swell event this is.
Valid values:

• Voltage
• THD
• Unbalance
startTime ISO8601 Date and time the sag/swell event started.
phase Text The phase the sag/swell occurred on.
Valid values
• PhaseA
• PhaseB
• PhaseC
• Main
• Load
• Load1
duration Double Total number of seconds the event occurred for
extremeAmplitude Double The worst amplitude for the event (lowest or highest value before returning)
averageAmplitude Double The average amplitude for the event over the duration

Page 30
 MultiDrive Web API 2.8 User Guide

Chapter

8.1. Change Main Supply Status (connect / disconnect)

Supply Control API
ter8
p
a
h
C

8
URL /supplyControl/mainSupply/{deviceid}
/supplyControl/mainSupply/plantNumber/{plantNumber}
Method POST
Permission mdpMainsControl [View]
Parameters Name Description Type Optional/ Valid values Default
Mandato
ry
startDate The date the date Optional -
device should
change it's relay
to the new state
endDate The date the date Optional -
device's relay
should revert to
its previous state.
If empty, then do
not revert.
controlCod The code which string Mandator Connect,
e will be issued to y EnableAndDisconn
the meter to ect,
change the relay DisableAndDisconn
state ect
mainsCont The number of int Optional 5 or greater Value of
rolDuratio seconds to be "MainsControlDuration"
n used as the in web.config (if
duration of the present);
Mains Control
Schedule otherwise 86400
seconds (i.e. 1 day)

Note: To configure a system-wide default (other than 86400 seconds), use the
“MainsControlDuration” key in web.config.

For example, to set the system-wide default to 3600 seconds (i.e. 1 hour), add the
following settings in web.config:

<appSettings>
…
<add key=” MainsControlDuration” value=”3600” />
</appSettings>

Optional Call back notification is an optional element and when present will mean that a notification will be
Payload POSTed to the URI provided. If not requiring notification (using polling instead) then payload can be
Empty.

Page 31
 MultiDrive Web API 2.8 User Guide

Payload
Additional parameter to be added to existing payload if callback is required:
{
"notification":
{
"uri": "<scheme>://someserver/notifyme"
},
"notifyStatus":
{
"status": [ "Complete", "No Jobs" ]
}
}

<scheme> can be "http", "https" or "topic".

Scheme Example Uri Descripion
http http://someserver/notifyme The callback will be posted to the HTTP URL
"http://someserver/notifyme"
https https://someserver/notifyme The callback will be posted to the HTTP URL
"https://someserver/notifyme"
topic topic://schedule-execution- Depending on the "callbackQueueType" setting in Callback Service,
callback the callback will be sent to a RabbitMQ queue or a Kafka topic
callbackQueueType Description
RabbitMQ The callback will be sent to the queue
"schedule-execution-callback" on the
configured RabbitMQ broker
Kafka The callback will be sent to the topic
"schedule-execution-callback" on the
configured Kafka broker

Notification
URI passed in will be called back as a POST request.
Payload will be the same as Get Schedule Execution (/scheduling/executions/{executionId})
{
"execution": {
"executionId" : 14,
"scheduleId" : 12,
"startDate" : "2013-01-21T10:00:00",
"endDate" : "2013-01-21T12:00:00",
"jobsWithSuccess" : 3,
"jobsWithFailure" : 5,
"status" : "Complete",
"hasWarning" : "true",
"totalJobs" : 10,
"queuedJobs" : 2
}
}

Status can be Unknown, Queued, Running, Complete, No Jobs, Cancelled, Paused

Dynamic Schedule Settings
The following payload can optionally be specified to control some aspects of the dynamic schedule being
triggered.
{
"dynamicScheduleSettings": {
"duration": 86400, // seconds
"priority": "Medium",
"retryCount": 2,
"retryDelay": 300000, // milliseconds
"timeToLive": 96 // hours
}
}
Note: The request parameter "mainsControlDuration" and application setting "MainsControlDuraition"
(in web.config) will take precedence over the "duration" property in this payload.
Returns 202 Accepted - includes location header to schedule execution history to determine if it has been sent to
the meter /scheduling/executions/{executionId}, This /scheduling/executions/{executionId} endpoint will
return a 200 OK with a representation of the commands status, or a when the device has successfully
received the command.
401 Unauthorized (Token invalid)
403 Forbidden (Access not allowed)
404 Not Found (Device Id does not exist)
500 Internal Server Error
Description

Page 32
 MultiDrive Web API 2.8 User Guide

Property Format Default Valid Values Description

Value
duration Integer 86400 60 to 2147483647 Number of seconds the schedule is given before failing.
priority String “Medium” "Very High", "High", Priority of the schedule relative to all other MultiDrive
"Medium", "Low", schedules.
"Very Low"
retryCount Integer 2 0 to 255 Maximum number of retries for the schedule.
retryDelay Integer 300000 60000 to 2147483647 Number of milliseconds to wait for the schedule retries.
timeToLive Integer 96 1 to 32767 Number of hours the schedule execution status will
remain in the system.

8.2. Get Main Supply status

URL /supplyControl/mainSupply/{deviceid}
/supplyControl/mainSupply/plantNumber/{plantNumber}
Notes This returns the last known relay status. To get the latest/current status from the meter, a schedule must
be triggered first.
Method GET
Permission mdpDevice [View]
Parameters -
Returns 200 OK
401 Unauthorized (Token invalid)
403 Forbidden (Access not allowed)
404 Not Found (Device Id or plant number does not exist)
5500 Internal Server Error
{
"relayStatus" :
{
"deviceId" : 14,
"statusTime" : "2013-01-21T10:00:00",
"lastCmdStartTime" : "2013-01-21T10:00:00",
"lastCmdEndTime" : "2013-01-21T10:00:00",
"changePending" : "False",
"status" : "Connected",
"info" : "",
}
}

Description
Property Optional/ Format Description
Mandatory
relayStatus
deviceId Mandatory Integer Device Id
statusTime Mandatory ISO8601 Date/Time of when status was read
status Mandatory String Current (or pending) status of the relay.
Valid statuses are:
• Connected
• EnabledAndDisconnected
• DisabledAndDisconnected
• Error
changePending Optional Boolean True if change is still pending
False is already changed
info Optional Text Misc information

8.3. Get Main Supply status for a device group

URL /supplyControl/mainSupply/deviceGroup/{deviceGroupId}
/supplyControl/mainSupply/deviceGroup/name/{deviceGroupName}
Notes This returns the last known relay status for all the devices. To get the latest/current status from the
meters, a schedule must be triggered first.
Page 33
 MultiDrive Web API 2.8 User Guide

Method GET
Permission mdpDevice [View] and mdpMeterGroup [View]
Parameters Name Description Type Optional/ Valid values Default
Mandatory
limit Maximum number of devices to return Integer Optional 0 - 5000 5000
status for in response
offset Offset in devices to start returning Integer Optional * 0
statuses for in response
Returns 200 OK
401 Unauthorized (Token invalid)
403 Forbidden (Access not allowed)
404 Not Found (Device Group Id Does not exist)
500 Internal Server Error
{
"relayStatus" :
{
"deviceId" : 14,
"statusTime" : "2013-01-21T10:00:00",
"lastCmdStartTime" : "2013-01-21T10:00:00",
"lastCmdEndTime" : "2013-01-21T10:00:00",
"changePending" : "False",
"status" : "Connected",
"info" : "",
},
}

Description
Property Optional/ Format Description
Mandatory
relayStatus
deviceId Mandatory Integer Device Id
statusTime Mandatory ISO8601 Date/Time of when status was read
status Mandatory String Current (or pending) status of the relay.
Valid statuses are:
• Connected
• EnabledAndDisconnected
• DisabledAndDisconnected
• Error
changePending Optional Boolean True if change is still pending
False is already changed
info Optional Text Misc information

8.4. Set Load Limiting Control

URL /supplyControl/loadControl/{deviceid}
/supplyControl/loadControl/plantNumber/{plantNumber}
Method POST
Permission mdpMainsControl [View]
Parameters Name Description Type Optional/ Valid values Default
Mandatory
controlMo To disable the load String Mandatory Disable,
de limiting, or enable the ActivePower,
load limiting by one of Current,
the supported ActiveDemand
measurements
startTime The time at which the ISO8601 Optional Now
load limiting control Date
becomes active

Page 34
 MultiDrive Web API 2.8 User Guide

endTime The time at which the ISO8601 Optional Now

load limiting control Date
becomes inactive
controlThr The load limiting Integer Optional 0
eshold threshold
apportionP The apportion policy to String Optional Nothing, SumValue,
olicy be applied to the AverageValue, Nothing
monitored source MaxValue
Optional Call back notification is an optional element and when present will mean that a notification will be
Payload POSTed to the URI provided. If not requiring notification (using polling instead) then payload can be
Empty.

Payload
Additional parameter to be added to existing payload if callback is required:
{
"notification":
{
"uri": "http://someserver/notifyme"
},
"notifyStatus":
{
"status": [ "Complete", "No Jobs" ]
}
}
<scheme> can be "http", "https" or "topic".
Scheme Example Uri Descripion
http http://someserver/notifyme The callback will be posted to the HTTP URL
"http://someserver/notifyme"
https https://someserver/notifyme The callback will be posted to the HTTP URL
"https://someserver/notifyme"
topic topic://schedule-execution- Depending on the "callbackQueueType" setting in Callback Service,
callback the callback will be sent to a RabbitMQ queue or a Kafka topic
callbackQueueType Description
RabbitMQ The callback will be sent to the queue
"schedule-execution-callback" on the
configured RabbitMQ broker
Kafka The callback will be sent to the topic
"schedule-execution-callback" on the
configured Kafka broker

Notification
URI passed in will be called back as a POST request.
Payload will be the same as Get Schedule Execution (/scheduling/executions/{executionId})
{
"execution": {
"executionId": 33,
"scheduleId": 0,
"startDate": "2019-02-15T10:21:00Z",
"endDate": "2019-02-15T10:42:33Z",
"jobsWithSuccess": 0,
"jobsWithFailure": 1,
"status": "Complete",
"hasWarning": false,
"totalJobs": 1,
"queuedJobs": 0
}
}

Status can be Unknown, Queued, Running, Complete, No Jobs, Cancelled, Paused

Dynamic Schedule Settings
The following payload can optionally be specified to control some aspects of the dynamic schedule being
triggered.
{
"dynamicScheduleSettings": {
"duration": 86400, // seconds
"priority": "Medium",
"retryCount": 2,
"retryDelay": 300000, // milliseconds
"timeToLive": 96, // hours
"executionTime": "2016-05-16T16:50:00Z"
}
}

Page 35
 MultiDrive Web API 2.8 User Guide

Note: The request parameter "mainsControlDuration" and application setting "MainsControlDuraition"

(in web.config) will take precedence over the "duration" property in this payload.
Returns 202 Accepted - includes location header with the endpoint “/scheduling/executions/{executionId}” to
determine if schedule has been sent to the meter. This endpoint will return a 200 OK with a
representation of the commands status when the device has successfully received the command.
401 Unauthorized (Token invalid)
403 Forbidden (Access not allowed)
404 Not Found (Device Id does not exist)
500 Internal Server Error

Description
Property Format Default Valid Values Description
Value
duration Integer 86400 60 to 2147483647 Number of seconds the schedule is given
before failing.
priority String “Medium” "Very High", "High", Priority of the schedule relative to all other
"Medium", "Low", MultiDrive schedules.
"Very Low"
retryCount Integer 2 0 to 255 Maximum number of retries for the
schedule.
retryDelay Integer 300000 60000 to 2147483647 Number of milliseconds to wait for the
schedule retries.
timeToLive Integer 96 1 to 32767 Number of hours the schedule execution
status will remain in the system.
executionTime ISO8601 Date - - Date and time when the schedule should
String run. If the specified time has passed when
the request reaches, MultiDrive, the
schedule will be executed immediately.
Note: This property is currently not
supported in
• Supply Control API
• Prepayement API (Pass prepayment
token to meter)

8.5. Change Main Supply Status (connect / disconnect) for Multiple Devices
URL /supplyControl/mainSupply/devices
Method POST
Permission mdpMainsControl [View]
Parameters Name Description Type Optional/ Valid values Default
Mandato
ry
startDate The date the date Optional -
device should
change it's relay
to the new state
endDate The date the date Optional -
device's relay
should revert to
its previous state.
If empty, then do
not revert.
controlCod The code which string Mandator Connect,
e will be issued to y EnableAndDisconn
the meter to ect,
change the relay DisableAndDisconn
state ect

Page 36
 MultiDrive Web API 2.8 User Guide

mainsCont The number of int Optional 5 or greater Value of

rolDuratio seconds to be "MainsControlDuration"
n used as the in web.config (if
duration of the present);
Mains Control
Schedule otherwise 86400
seconds (i.e. 1 day)

Note: To configure a system-wide default (other than 86400 seconds), use the
“MainsControlDuration” key in web.config.

For example, to set the system-wide default to 3600 seconds (i.e. 1 hour), add the
following settings in web.config:

<appSettings>
…
<add key=” MainsControlDuration” value=”3600” />
</appSettings>

Payload by device id
{
"devices" : [
{
"deviceId" : 12
},
{
"deviceId" : 13
},
{
"deviceId" : 14
}, ...
]
}

or by device plant number

{
"devices" : [
{
"plantNumber" : "Meter at Level 1"
},
{
"plantNumber" : "Meter at Level 2"
},
{
"plantNumber" : "Meter at Level 3"
}, ...
]
}
Optional Call back notification is an optional element and when present will mean that a notification will be
Payload POSTed to the URI provided. If not requiring notification (using polling instead) then payload can be
Empty.

Payload
Additional parameter to be added to existing payload if callback is required:
{
"notification":
{
"uri": "http://someserver/notifyme"
},
"notifyStatus":
{
"status": [ "Complete", "No Jobs" ]
}
}
<scheme> can be "http", "https" or "topic".
Scheme Example Uri Descripion
http http://someserver/notifyme The callback will be posted to the HTTP URL
"http://someserver/notifyme"
https https://someserver/notifyme The callback will be posted to the HTTP URL
"https://someserver/notifyme"

Page 37
 MultiDrive Web API 2.8 User Guide

topic topic://schedule-execution- Depending on the "callbackQueueType" setting in Callback Service,

callback the callback will be sent to a RabbitMQ queue or a Kafka topic
callbackQueueType Description
RabbitMQ The callback will be sent to the queue
"schedule-execution-callback" on the
configured RabbitMQ broker
Kafka The callback will be sent to the topic
"schedule-execution-callback" on the
configured Kafka broker

Notification
URI passed in will be called back as a POST request.
Payload will be the same as Get Schedule Execution (/scheduling/executions/{executionId})
{
"execution": {
"executionId" : 14,
"scheduleId" : 12,
"startDate" : "2013-01-21T10:00:00",
"endDate" : "2013-01-21T12:00:00",
"jobsWithSuccess" : 3,
"jobsWithFailure" : 5,
"status" : "Complete",
"hasWarning" : "true",
"totalJobs" : 10,
"queuedJobs" : 2
}
}

Status can be Unknown, Queued, Running, Complete, No Jobs, Cancel, Paused

Dynamic Schedule Settings
The following payload can optionally be specified to control some aspects of the dynamic schedule being
triggered.
{
"dynamicScheduleSettings": {
"duration": 86400, // seconds
"priority": "Medium",
"retryCount": 2,
"retryDelay": 300000, // milliseconds
"timeToLive": 96 // hours
}
}
Note: The request parameter "mainsControlDuration" and application setting "MainsControlDuraition"
(in web.config) will take precedence over the "duration" property in this payload.
Returns 202 Accepted - includes location header to schedule execution history to determine if it has been sent to
the meter /scheduling/executions/{executionId}, This /scheduling/executions/{executionId} endpoint will
return a 200 OK with a representation of the commands status, or a when the device has successfully
received the command.
401 Unauthorized (Token invalid)
403 Forbidden (Access not allowed)
404 Not Found (Device Id does not exist)
500 Internal Server Error

Description

Property Format Default Valid Values Description

Value
duration Integer 86400 60 to 2147483647 Number of seconds the schedule is given before failing.
priority String “Medium” "Very High", "High", Priority of the schedule relative to all other MultiDrive
"Medium", "Low", schedules.
"Very Low"
retryCount Integer 2 0 to 255 Maximum number of retries for the schedule.
retryDelay Integer 300000 60000 to 2147483647 Number of milliseconds to wait for the schedule retries.
timeToLive Integer 96 1 to 32767 Number of hours the schedule execution status will
remain in the system.

Page 38
 MultiDrive Web API 2.8 User Guide

8.6. Get Main Supply Status for Multiple Devices

URL /supplyControl/mainSupply/devices
Notes This returns the last known relay status. To get the latest/current status from the meter, a schedule must
be triggered first.
Method GET
Permission mdpDevice [View]
Payload by device id
{
"devices" : [
{
"deviceId" : 12
},
{
"deviceId" : 13
},
{
"deviceId" : 14
}, ...
]
}

or by device plant number

{
"devices" : [
{
"plantNumber" : "Meter at Level 1"
},
{
"plantNumber" : "Meter at Level 2"
},
{
"plantNumber" : "Meter at Level 3"
}, ...
]
}
Returns 200 OK
401 Unauthorized (Token invalid)
403 Forbidden (Access not allowed)
404 Not Found (Device Id or plant number does not exist)
500 Internal Server Error
{
"relayStatus": [
{
"deviceId" : 14,
"plantNumber" : "Meter at Level 3",
"statusTime" : "2013-01-21T10:00:00",
"lastCmdStartTime" : "2013-01-21T10:00:00",
"lastCmdEndTime" : "2013-01-21T10:00:00",
"changePending" : "False",
"status" : "Connected",
"info" : "",
},
...
]
}
Description
Property Optional/ Format Description
Mandatory
relayStatus
deviceId Mandatory Integer Device Id
plantNumber Mandatory String Device plant number
statusTime Mandatory ISO8601 Date/Time of when status was read
status Mandatory String Current (or pending) status of the relay.
Valid statuses are:
• Connected
• EnabledAndDisconnected
• DisabledAndDisconnected
• Error

Page 39
 MultiDrive Web API 2.8 User Guide

changePending Optional Boolean True if change is still pending

False is already changed
info Optional Text Misc information

8.7. Set Load Limiting Control for Multiple Devices

URL /supplyControl/loadControl/devices
Method POST
Permission mdpMainsControl [View]
Parameters Name Description Type Optional/ Valid values Default
Mandatory
controlMo To disable the load String Mandatory Disable,
de limiting, or enable the ActivePower,
load limiting by one of Current,
the supported ActiveDemand
measurements
startTime The time at which the ISO8601 Optional Now
load limiting control Date
becomes active
endTime The time at which the ISO8601 Optional Now
load limiting control Date
becomes inactive
controlThr The load limiting Integer Optional 0
eshold threshold
apportionP The apportion policy to String Optional Nothing, SumValue,
olicy be applied to the AverageValue, Nothing
monitored source MaxValue
Payload by device id
{
"devices" : [
{
"deviceId" : 12
},
{
"deviceId" : 13
},
{
"deviceId" : 14
}, ...
]
}

or by device plant number

{
"devices" : [
{
"plantNumber" : "Meter at Level 1"
},
{
"plantNumber" : "Meter at Level 2"
},
{
"plantNumber" : "Meter at Level 3"
}, ...
]
}
Optional Call back notification is an optional element and when present will mean that a notification will be
Payload POSTed to the URI provided. If not requiring notification (using polling instead) then payload can be
Empty.

Payload
Additional parameter to be added to existing payload if callback is required:
{
"notification":
{
"uri": "http://someserver/notifyme"

Page 40
 MultiDrive Web API 2.8 User Guide

},
"notifyStatus":
{
"status": [ "Complete", "No Jobs" ]
}
}
<scheme> can be "http", "https" or "topic".
Scheme Example Uri Descripion
http http://someserver/notifyme The callback will be posted to the HTTP URL
"http://someserver/notifyme"
https https://someserver/notifyme The callback will be posted to the HTTP URL
"https://someserver/notifyme"
topic topic://schedule-execution- Depending on the "callbackQueueType" setting in Callback Service,
callback the callback will be sent to a RabbitMQ queue or a Kafka topic
callbackQueueType Description
RabbitMQ The callback will be sent to the queue
"schedule-execution-callback" on the
configured RabbitMQ broker
Kafka The callback will be sent to the topic
"schedule-execution-callback" on the
configured Kafka broker

Notification
URI passed in will be called back as a POST request.
Payload will be the same as Get Schedule Execution (/scheduling/executions/{executionId})

{
"execution": {
"executionId" : 14,
"scheduleId" : 12,
"startDate" : "2013-01-21T10:00:00",
"endDate" : "2013-01-21T12:00:00",
"jobsWithSuccess" : 3,
"jobsWithFailure" : 5,
"status" : "Complete",
"hasWarning" : "true",
"totalJobs" : 10,
"queuedJobs" : 2
}
}
Status can be Unknown, Queued, Running, Complete, No Jobs, Cancel, Paused
Dynamic Schedule Settings
The following payload can optionally be specified to control some aspects of the dynamic schedule being
triggered.
{
"dynamicScheduleSettings": {
"duration": 86400, // seconds
"priority": "Medium",
"retryCount": 2,
"retryDelay": 300000, // milliseconds
"timeToLive": 96, // hours
"executionTime": "2016-05-16T16:50:00Z"
}
}

Note: The request parameter "mainsControlDuration" and application setting "MainsControlDuraition"

(in web.config) will take precedence over the "duration" property in this payload.
Returns 202 Accepted - includes location header with the endpoint “/scheduling/executions/{executionId}” to
determine if schedule has been sent to the meter. This endpoint will return a 200 OK with a
representation of the commands status when the device has successfully received the command.
401 Unauthorized (Token invalid)
403 Forbidden (Access not allowed)
404 Not Found (Device Id does not exist)
500 Internal Server Error

Description
Property Format Default Valid Values Description
Value
duration Integer 86400 60 to 2147483647 Number of seconds the schedule is given
before failing.

Page 41
 MultiDrive Web API 2.8 User Guide

priority String “Medium” "Very High", "High", Priority of the schedule relative to all other
"Medium", "Low", MultiDrive schedules.
"Very Low"
retryCount Integer 2 0 to 255 Maximum number of retries for the
schedule.
retryDelay Integer 300000 60000 to 2147483647 Number of milliseconds to wait for the
schedule retries.
timeToLive Integer 96 1 to 32767 Number of hours the schedule execution
status will remain in the system.
executionTime ISO8601 Date - - Date and time when the schedule should
String run. If the specified time has passed when
the request reaches, MultiDrive, the
schedule will be executed immediately.
Note: This property is currently not
supported in
• Supply Control API
• Prepayement API (Pass prepayment
token to meter)

Page 42
 MultiDrive Web API 2.8 User Guide

Chapter

9.1. Devices
Fleet Management API
ter9
p
a
h
C

9
9.1.1. List / Search Devices
URL /fleetManagement/devices
Method GET
Permission mdpDevice [View]
Parameters Name Description Type Optional/ Valid values Default
Mandatory
serialNumber Filter by serial string Optional *
number
plantNumber Filter by plant string Optional *
number
deviceTypeName Filter by device string Optional *
type name
status Filter by the string Optional AWAITING_INSTALLATI *
meter status ON, INSTALLED,
COMMISSIONED,
NOT_IN_SERVICE
siteAssigned Whether the site boolean Optional true, false *
is assigned.
siteCode Filter by the site string Optional *
code
installDate Date meter was Date Optional *
started to be
read from
commissionDate Date device was Date Optional *
commissioned
decommissionDate Date device was Date Optional *
decommissioned
limit Maximum Integer Optional 0 - 5000 5000
number of
devices to
return status for
in response
offset Offset in devices Integer Optional * 0
to start
returning
statuses for in
response
Returns 200 OK
401 Unauthorized (Token invalid)
403 Forbidden (Access not allowed)
500 Internal Server Error
{
"devices" : [
{

Page 43
 MultiDrive Web API 2.8 User Guide

"deviceID" : 156312,
"plantNumber" : "ABC1234"
"serialNumber" : "41545456",
"series" : "Atlas 2.0"
"model" : "EDMI Mk10E",
"installDate" : "2013-01-22T10:50:32",
"commissionDate" : "2013-01-25T12:02:03",
"decommissionDate" : "",
"status" : "INSTALLED",
"siteCode" : "SiteABC",
"siteID" : 134980,
"deviceConfiguration" : "Mk 10 Import 2 Ch",
"deviceConfigurationId" : 33
},...
]
}

Description
Property Optional/ Format Valid Values Description
Mandatory
deviceId Mandatory Integer A unique identifier for the device
plantNumber Mandatory String The manufacturer serial number
of the device
serialNumber Mandatory String The market identifier for the
device
series Mandatory String The name of the series this
meter is from, e.g. "Atlas"
model Mandatory String The name of the meter's model
within its series, e.g. "Mk 10A"
installDate Mandatory String The date and time the meter was
installed
commissionDate Mandatory String The date the meter was
commissioned
decommissionDate Mandatory String The date the meter was
decommissioned in the system
status Mandatory String AWAITING_INSTALLATION, The status of the device
INSTALLED, COMMISSIONED,
NOT_IN_SERVICE
siteCode Mandatory String The site code of the site used to
communicate with the meter
siteId Mandatory Integer The siteId of the site used to
communicate with the meter
deviceConfiguration Mandatory String The name of the device
configuration used by the meter
deviceConfigurationId Mandatory Integer The id of the device configuration
used by the meter

9.1.2. Get Device

URL /fleetManagement/devices/{deviceId}
/fleetManagement/devices/plantNumber/{plantNumber}
Method GET
Permission mdpDevice [View]
Returns 200 OK
401 Unauthorized (Token invalid)
403 Forbidden (Access not allowed)
404 Not Found
{
"device": {
"deviceId": 8072584,
"plantNumber": "ABC23421",
"serialNumber": "3410293A",
"series": "Atlas",

Page 44
 MultiDrive Web API 2.8 User Guide

"model": "Mk10B",
"deviceConfiguration": "Mk 10 Import 2 Ch",
"deviceConfigurationId": 33,
"siteId": 15,
"calorificValueId": 0,
"installDate": "2013-01-22T00:00:00",
"commissionDate": "2013-01-23T00:00:00",
"decommissionDate": "",
"status": "INSTALLED",
"misc": "",
"meterAppliesTransformer": "true",
"timeOffsetMins": 1,
"userLogins": [{
"role": "SUPER",
"username": "Bob",
"password": "kb3rsf"
},
{
"role": "SUPER",
"username": "Bob",
"password": "jd83hf"
}],
"deviceCommsSettings": [{
"order": 1,
"protocol": "Edmi MiniE",
"loginTimeoutSecs": 90,
"maxRetries": 3,
"unitAddress": 0,
"devicePort": 0
},
{
"order": 2,
"protocol": "Edmi MiniE",
"loginTimeoutSecs": 75,
"timeoutSecs": 90,
"maxRetries": 3,
"unitAddress": 0
}],
"ct": {
"primary": 2000,
"secondary": 5
},
"pt": {
"primary": 110,
"secondary": 110
},
"deviceGroups": [{
"deviceGroupId": 33,
"name": "Inbound Daily Read"
}]
}
}

Description
Property Optional/ Format Description
Mandatory
device

deviceId Mandatory String A unique identifier for the

device. This could be the

Page 45
 MultiDrive Web API 2.8 User Guide

serial number or an
internal ID such as a GUID
or integer database ID. It
is normally generated and
controlled by the
collection system.
serialNumber Mandatory String The manufacturer serial
number of the device
plantNumber Mandatory String The market identifier for
the device. Default to
serialNumber if
plantNumber is not
configured in meter.
series Mandatory See The name of the series
Meter this meter is from, e.g.
Series "Atlas".
section
below
model Mandatory See The name of the meter's
Meter model within its series,
Series e.g. "Mk 10A".
section
below
device- Either of the String The name of
Configuration two needs to the MultiDrive Device
be provided Configuration containing
but cannot be the interval and TOU
both channel mappings for the
(Mandatory) meter. Use"default" for
non MultiDrive systems
device- Integer Device configuration Id in
ConfigurationId MultiDrive
installDate Mandatory ISO8601 The date and time the
meter was installed. This
must be on or before the
first interval of data that
needs to be
collected. MultiDrive will
ignore any data prior to
this date.
commission- Unused ISO8601 The date the meter was
Date commissioned on. This is
separate to install date
and is updated if the
device is recommissioned.
decommission- Unused ISO8601 The date the meter was
Date decommissioned on.
status Mandatory See The status of the device.
Device Must be one of
Statuses AWAITING_INSTALLATION
section , INSTALLED,
COMMISSIONED,
NOT_IN_SERVICE.
Only meters with a status
of INSTALLED or
COMMISSIONED are
eligible for reading.
misc Unused String This field stores misc
information in a free form
format.

Page 46
 MultiDrive Web API 2.8 User Guide

meterApplies- Unused Boolean Indicates if the meter

Transformer applies a transformer
ratio or not.
siteId Optional String Contains the siteId of the
site used to communicate
with the meter. No siteId
means this device is not
linked to a site.
Storm will return a SiteID
when a Device is
created. The collection
info can then be updated
using the Site API.
calorificValueId Optional Integer Linked to calorific value,
only applicable to Gas
meter
ct Optional Contains current
transformer (CT) settings
for the meter.
primary Optional Integer The numerator in a CT
ratio.
secondary Optional Integer The denominator in a CT
ratio.
pt Optional Contains voltage
(potential) transformer
(PT) settings for the
meter.
primary Optional Integer The numerator in a PT
ratio.
secondary Optional Integer The denominator in a PT
ratio.
timeOffsetMins Optional Integer The meter's dither value
(read delay from the start
of the reading window) or
an offset from MultiDrive
server time.
userLogins Optional Holds the list of user
accounts that can be used
to access the meter. At
this stage, it
should contain a super
user and a standard user.
userLogin Optional
role Mandatory SUPER or The type of user account.
NORMAL

username Mandatory String The username of the user

as used to log into the
meter.
password Mandatory String The password used to log
Encrypted for into the meter.
MDX files This is Encrypted by
Decrypted for MultiDrive exports, but
REST API not other head ends (see
create/ update relevant columns)
payloads
Encrypted for
return value
from REST API
get/

Page 47
 MultiDrive Web API 2.8 User Guide

create/update
s
deviceComms- Mandatory Contains additional
Settings meter-level settings for all
the comms settings
specified at the site level.
comms- Mandatory The wrapper element in
Settings xml (not needed for json)
order Mandatory Integer The order of the
equivalent site level
comms settings.
Currently, only 1 and 2 are
supported.
protocol Mandatory See The protocol used to talk
Protocols to the meter.
section
loginTimeout- Mandatory Integer The maximum
Secs time MultiDrive should
wait for a response when
attempting to log in to the
meter.
timeoutSecs Mandatory Integer The maximum time
MultiDrive should wait for
a response when a
command (other than a
login command) has been
sent to a meter.
maxRetries Mandatory Integer Maximum number of
retries MultiDrive will
perform during a single
read attempt.
devicePort Optional Integer Device port number that
is used by POD based
devices (e.g. Mk7B). For
POD based devices,
communication with POD,
Elec. Meter and Gas
Meter will be using
different device port.
unitAddress Unused Integer
deviceGroups Optional Contains the list of groups
the device belongs to.
deviceGrou Optional
p
deviceGroupI Mandatory Integer The groupID of a group
d the device belongs to.
name Optional String Name of the device group

Note that username/passwords and security keys are not returned in the MDX. They are only allowed in the Create/
Update functions.

9.1.3. Protocols
Default
Edmi Command Line
Edmi Command Line Packet
Edmi MiniE
Edmi MiniE Packet

Page 48
 MultiDrive Web API 2.8 User Guide

IEC 1107/EDMI Command Line

LON DLC
DLMS
ANSI 1221
DLT645

9.1.4. Device Statuses

AWAITING_INSTALLATION
INSTALLED
COMMISSIONED
NOT_IN_SERVICE

9.1.5. Meter Series

Series Model
Atlas Gas G6000
Abacus Mk29
Atlas Mk7
Mk7A
Mk7B
Mk7C
Mk10
Mk10A
Mk10D
Mk10E
Mk10H
Mk10UPS
Mk10China
Mk10Mini
Mk10Allix
Genius Mk6E
Mk11
Mk6/Mk6N
Mk6Es
Others Mk3
Mk7M
Mk32
Mk32H
Mk32P
Mk10M
GW30
GWTP
HXE110
Mk10MDC
Mk7MDC
Mk10MCT
GW32P
Summation Mk3 Summation
Mk6E Summation
ICON ICon Controller
Papillon Mk31
Mk31E

Page 49
 MultiDrive Web API 2.8 User Guide

9.1.6. Create Device

URL /fleetManagement/devices
Method POST
Permission mdpDevice [Create]
Payload MDX devices object same as in Get Device operation
Notes Either deviceConfiguration (name of the device configuration) or deviceConfigurationId can be
used to update the device configuration. However both cannot be present at the same time (will
respond with 400 error).
For deviceGroups:deviceGroup:name, this does nothing if present during this operation and is
ignored.
Read only deviceId, deviceGroups:deviceGroup:name
attributes
Returns 201 Created - includes created object and location header containing the URN of the new
resource (fleetManagement/devices/{DeviceId})
400 Bad Request (device is invalid)
401 Unauthorized (Token invalid)
403 Forbidden (Access not allowed)
409 Conflict (Plant Number already exists)
500 Internal Server Error
*Note that username/passwords and security keys are sent in the clear here.

9.1.6.1 Update Device

URL /fleetManagement/devices/{deviceId}
/fleetManagement/devices/plantNumber/{plantNumber}
Method PUT
Permission mdpDevice [Modify]
Payload MDX devices object same as in Get Device operation
Notes 1. This method is used to de activate devices, by setting the status to NOT_IN_SERVICE
2. Either deviceConfiguration (name of the device configuration) or deviceConfigurationId can be
used to update the device configuration. However both cannot be present at the same time (will
respond with 400 error)
3. For deviceGroups:deviceGroup:name, this does nothing if present during this operation and is
ignored.
Read only deviceId, deviceGroups:deviceGroup:name
attributes
Returns 200 OK (returns updated object)
400 Bad Request (changes are invalid)
401 Unauthorized (Token invalid)
403 Forbidden (Access not allowed)
404 Not Found
500 Internal Server Error

9.1.7. Delete Device

URL /fleetManagement/devices/{deviceId}
/fleetManagement/devices/plantNumber/{plantNumber}
Method DELETE
Permission mdpDevice [Delete]
Returns 200 OK
401 Unauthorized (Token invalid)
403 Forbidden (Access not allowed)
404 Not Found
500 Internal Server Error

Page 50
 MultiDrive Web API 2.8 User Guide

9.1.8. Last Device Access Time (Scheduled and Adhoc Communications)

URL /fleetManagement/devices/{deviceId}/lastAccessTime
/fleetManagement/devices/plantNumber/{plantNumber}/lastAccessTime
Method GET
Permission mdpDevice [View]
Returns 200 OK
401 Unauthorized (Token invalid)
403 Forbidden (Access not allowed)
404 Not Found
500 Internal Server Error
{
"executionJob" : {
"deviceId" : 32,
"plantNumber" : "Device01",
"scheduleId" : 12,
"executionId" : 125,
"executionJobId" : 9875,
"date" : "2013-01-21T10:00:00",
"commsServer" : "Communications Pool",
"status" : "Success",
"retries" : 1,
"retriesRemaining" : 0,
"hasWarning" : "true",
"lastError" : "Communications Device Failure: System error:Connection refused, Unable to
connect to 192.168.3.20 on port 10002",
}
}

9.1.9. Next Schedule Device Access Time

URL /fleetManagement/devices/{deviceId}/nextAccessTime
/fleetManagement/devices/plantNumber/{plantNumber}/nextAccessTime
Method GET
Permission mdpDevice [View]
Returns 200 OK
401 Unauthorized (Token invalid)
403 Forbidden (Access not allowed)
404 Not Found
500 Internal Server Error
{
"schedule" : {
"scheduleId" : 34,
"name" : "Important Read Schedule",
"recurrence" : "Everyday at 10:00"
"lastRun" : "2013-01-21T10:00:00",
"nextRun" : "2013-01-22T10:00:00",
"status" : "Active"
}
}

9.1.10. Request Pining a Device

URL /fleetManagement/devices/ping/{deviceId}
/fleetManagement/devices/ping/plantNumber/{plantNumber}
Method POST
Permission mdpDevice [View]
Parameters Name Description Type Optional/ Default
Mandatory

Page 51
 MultiDrive Web API 2.8 User Guide

pingCount Number of times to ping Integer Optional 4

Optional Call back notification is an optional element and when present will mean that a notification will be
Payload POSTed to the URI provided. If not requiring notification (using polling instead) then payload can be
Empty.

Payload
Additional parameter to be added to existing payload if callback is required:
{
"notification":
{
"uri": "http://someserver/notifyme"
},
"notifyStatus":
{
"status": [ "Complete", "No Jobs" ]
}
}
<scheme> can be "http", "https" or "topic".
Scheme Example Uri Descripion
http http://someserver/notifyme The callback will be posted to the HTTP URL
"http://someserver/notifyme"
https https://someserver/notifyme The callback will be posted to the HTTP URL
"https://someserver/notifyme"
topic topic://schedule-execution- Depending on the "callbackQueueType" setting in Callback Service,
callback the callback will be sent to a RabbitMQ queue or a Kafka topic
callbackQueueType Description
RabbitMQ The callback will be sent to the queue
"schedule-execution-callback" on the
configured RabbitMQ broker
Kafka The callback will be sent to the topic
"schedule-execution-callback" on the
configured Kafka broker

Notification
URI passed in will be called back as a POST request.
Payload will be the same as Get Schedule Execution (/scheduling/executions/{executionId})

{
"execution": {
"executionId" : 14,
"scheduleId" : 12,
"startDate" : "2013-01-21T10:00:00",
"endDate" : "2013-01-21T12:00:00",
"jobsWithSuccess" : 3,
"jobsWithFailure" : 5,
"status" : "Complete",
"hasWarning" : "true",
"totalJobs" : 10,
"queuedJobs" : 2
}
}

Status can be Unknown, Queued, Running, Complete, No Jobs, Cancelled, Paused

Returns 202 Accepted - includes location header with the endpoint "/scheduling/executions/{executionId}" to
determine if schedule has been sent to the meter. This endpoint will return a 200 OK with a
representation of the commands status when the device has successfully received the command.
401 Unauthorized (Token invalid)
403 Forbidden (Access not allowed)
404 Not Found (Device Id or plant number does not exist)
500 Internal Error

Page 52
 MultiDrive Web API 2.8 User Guide

9.1.11. Get Ping Status

URL /fleetManagement/devices/pingStatus/{executionId}
Method GET
Permission mdpDevice [View]
Returns 200 OK
401 Unauthorized (Token invalid)
403 Forbidden (Access not allowed)
404 Not Found (Execution id does not exist)
500 Internal Server Error
{
"pingStatus" : {
"executionId": 105,
"devices": [
{
"deviceId" : 156312,
"plantNumber" : "ABC1234",
"serialNumber" : "41545456",
"pings" : [
{
"pingTime" : "2013-01-21T10:00:00",
"responseTime" : 1050,
"ttl" : 254,
}, ...
],
"statistics" : {
"sentPackets" : 4,
"receivedPackets" : 3,
"lostPackets" : 1,
"percentLost" : 25.0,
"minimumTime" : 556,
"maximumTime" : 1050,
"averageTime" : 783,
}
}, ...
]
}
}

Description
Property Format Description
pingStatus Object containing
information of the
inquired ping
operations
executionId Integer ID of schedule
execution that
performed the ping
operations
devices deviceId Integer ID of the pinged
device
plantNumber String Plant code of
the pinged device
serialNumber String Serial Number of
the pinged device
pings A collection of ping
objects
pingTime ISO8601 Date/Time at which
the ping packet is sent
responseTime Integer The amount of time
(in milliseconds) for
the ping to response
ttl Integer Time-to-live value of
the ping
statistics Object containing
statistics of the ping
operations

Page 53
 MultiDrive Web API 2.8 User Guide

sentPackets Integer Total number of ping

packets sent
receivedPackets Integer Total number of reply
packets received
lostPackets Integer Total number of lost
packets
percentLost Float Percentage of lost
packets
minimumTime Integer The minimum
response time (in
milliseconds) among
the various ping
operations
maximumTime Integer The maximum
response time (in
milliseconds) among
the various ping
operations
averageTime Integer The average response
time (in milliseconds)
of the ping operations

9.2. Sites
9.2.1. List / Search Sites
URL /fleetManagement/sites
Method GET
Permission mdpSite [View]
Parameters Name Description Type Optional/ Valid Default
Mandatory values
siteCode Filter by match in Site code string Optional *
isPersistentComms Limits returned sites to those boolean Optional True *
which have a comms device with or
persistence of the specified type False
limit Maximum number of devices to Integer Optional 0- 5000
return status for in response 5000
offset Offset in devices to start Integer Optional * 0
returning statuses for in
response
Returns 200 OK
401 Unauthorized (Token invalid)
403 Forbidden (Access not allowed)
500 Internal Server Error
{
"sites" : [
{
"siteId" : 1,
"siteCode" : "SiteOne"
},...
]
}

9.2.2. Get Site

URL /fleetManagement/sites/{siteId}
/fleetManagement/sites/siteCode/{siteCode}
Method GET
Permission mdpSite [View]
Returns 200 OK
401 Unauthorized (Token invalid)

Page 54
 MultiDrive Web API 2.8 User Guide

403 Forbidden (Access not allowed)

404 Not Found
500 Internal Server Error
{
"site" : {
"siteId" : 1,
"code" : "SiteOne",
"communicationsType" : "OTHER",
"modemid": 1,
"simid": 12,
"signalStrength": 6,
"baseStation": "4w3,234,2h8",
"siteCommsSettings" : [
{
"order": 1,
"deviceType" : "IP",
"deviceChaining" : "MULTIDROP",
"persistentComms" : true,
"ipSettings" : {
"ipAddress" : "10.1.2.3",
"port" : 5975,
"protocol" : "TCP"
}
},
{
"order" : 2,
"deviceType" : "Modem",
"deviceChaining" : "SINGLE_SITE",
"persistentComms" : true,
"modemSettings" : { // Modem settings would be included for devices connected
by modem and for non persistent IP (for SMS).
"phoneNumber" : "648957123"
}
}
]
}
}

Description
Property Optional/ Format Description
Mandatory
siteId Mandatory Integer A unique identifier for
the site
code Mandatory Text(50) A unique name for the
site, e.g. IMEI number.
communications- Mandatory STANDARD, OTHER is not supported
Type GPRS, by iE2
RF_MESH,
ZIGBEE, PLC,
OTHER
modemid Optional Integer Modem attached to this
site
simid Optional Integer SIM Card attached to this
site
signalStrength Optional Integer Signal Strength of the
GPRS/3G network
attached.
baseStation Optional String base station/cell tower
the site attached to.
siteComms- Mandatory
Settings
comms- Mandatory Must have at least one
Settings ipSettings or
modemSettings.
Holds any comms
settings that can be used
to communicate with the
site.

Page 55
MultiDrive Web API 2.8 User Guide

order Mandatory 1 or 2 In the event of

connection or read
issues, MultiDrive will
attempt to read the
meter(s) attached to the
site using each of its
comms settings. These
settings will be tried in
numerical order based on
the values of their order
fields.
Storm will not offer
fallback to secondary
comms
initially. Secondary
comms settings could still
be used for non-
persistent IP meters (to
store the phone number
for SMS
wakeup messages).
deviceType Mandatory IP, MODEM, The type of comms that
DIRECT this device supports.
Note that MultiDrive also
supports DIRECT,
DATABASE, EXTDriver,
RAS but these are not
supported by iE2.
device- Optional SINGLE_SITE, Indicates whether there
Chaining MULTIDROP is a single meter attached
to the site or several
chained together in a
multi-drop configuration.
The default value will be
‘SINGLE_SITE’ if
deviceChaining is not
specified.
persistent- Mandatory boolean Indicates whether
Comms the site will be contacted
by the server (true) or
vice verse (false).
ipSettings Optional For an outbound
(persistent) site, this
holds the details of how
to contact the
site using IP reading.
For an inbound (non-
persistent) site, this holds
the details of the comms
server that attached
meters will push packets
to and the last-known IP
address of the site.
protocol Optional TCP / UDP Network protocol. EDMI
meters generally use
UDP; EI meters use TCP.
port Optional Integer The site's current/last
known port.
ipAddress Mandatory Text(50) The site's current/last
known IP address.

Page 56
 MultiDrive Web API 2.8 User Guide

modem- Optional Holds the details of how

Settings to connect to the site
using cellular comms
such as CDMA.
Mandatory if
serverDeviceType =
Modem
or persistentComms =
false
phone- Mandatory Text Phone number used to
Number dial the site.

9.2.3. Create Site

URL /fleetManagement/sites
Method POST
Permission mdpSite [Create]
Payload MDX sites object same as in Get Site operation
Read only siteId
attributes
Notes New sites are created in the MultiDrive system as indicated:
1. For new persistent IP meters
i. Communications server is assigned as Pool
ii. Communications device is assigned as appropriate
▪ If UDP, finds first UDP one
▪ If TCP, finds first TCP one
2. For non-persistent IP meters
i. Assigns to non-pooled communications server with least number of meters
assigned to it
ii. Communications device is assigned as appropriate
▪ If UDP, finds first UDP one
▪ If TCP, finds first TCP one
3. For meters with modems
i. Assigns to modem with least number of meters assigned
ii. Flags error if no modem com devices available (412 error)
Returns 201 Created - includes created object and location header containing the URN of the new
resource (/sites/{siteId})
400 Bad Request (New site is not valid, device type is not valid)
401 Unauthorized (Token invalid)
403 Forbidden (Access not allowed)
409 Conflict (Site code already exists). Site Id of conflicting resource will be returned here.
412 Precondition Failed (No modems in the system for communications pool)
500 Internal Server Error

9.2.4. Delete Site

URL /fleetManagement/sites/{siteId}
/fleetManagement/sites/siteCode/{siteCode}
Method DELETE
Permission mdpSite [Delete]
Returns 200 OK
401 Unauthorized (Token invalid)
403 Forbidden (Access not allowed)
404 Not Found

Page 57
 MultiDrive Web API 2.8 User Guide

9.2.5. Update Site

URL /fleetManagement/sites/{siteId}
/fleetManagement/sites/siteCode/{siteCode}
Method PUT
Permission mdpSite [Modify]
Read only attributes siteId
Parameters/Payload As per Create Site
Returns 200 OK (this will return the updated site details)
400 Bad Request (site changes are not valid)
401 Unauthorized (Token invalid)
403 Forbidden (Access not allowed)
404 Not Found
500 Internal Server Error

9.3. Device Configurations

9.3.1. List / Search Device Configurations
URL /fleetManagement/deviceConfigurations
Method GET
Permission mdpDeviceConfig [View]
Parameters Name Description Type Optional/ Valid Default
Mandatory values
name Filter by match in device configuration name string Optional *
Returns 200 OK
401 Unauthorized (Token invalid)
403 Forbidden (Access not allowed)
500 Internal Server Error
{
"deviceConfigurations" : [
{
"deviceConfigurationId" : 1,
"name" : "config1"
"series" : "Atlas"
"model" : "Mk 10A"
},
{
"deviceConfigurationId" : 2,
"name" : "config2"
"series" : "Atlas"
"model" : "Mk 10B"
}
]
}

9.3.2. Get Device Configuration

URL /fleetManagement/deviceConfigurations/{deviceConfigurationId}
/fleetManagement/deviceConfigurations/name/{deviceConfigurationName}
Method GET
Permission mdpDeviceConfig [View]
Returns 200 OK
401 Unauthorized (Token invalid)
403 Forbidden (Access not allowed)
404 Not Found
500 Internal Server Error
For auto channel mapping, an empty channels list should be returned.
{
"deviceConfiguration": {
"deviceConfigurationId": 3,
"name": "EDMI Mk10E (Default)",
"series": "Atlas",
Page 58
 MultiDrive Web API 2.8 User Guide

"model": "Mk10E",
"description": "The default device configuration for the EDMI MK10E metering
device.",
"channelSets": [
{
"code": "LS1",
"description": "_Default Profile Mapping",
"channels": [
{
"name":"E1",
"units":"Wh",
"flowDirection":"DELIVERED",
"apportionPolicy":"SUM",
"phase":"NONE"
},...
]
},
{
"code": "LS2",
"description": "Profile Mapping 2 (Auto)",
"channels": []
},...
],
"registerSets": [
{
"code": "RegisterSet1",
"registers": [
{
"name": "Wh Consumption Total",
"units": "WH",
"flowDirection": "DELIVERED",
"phase": "TOTAL",
"apportionPolicy": "SUM",
"touRate": "TOTAL"
},...
]
}
],
"eventLogs": [
{
"eventLogId": 1,
"name": "Event Log 1(Default)"
},...
]
}
}

9.4. Device Groups

9.4.1. List / Search Device Groups
URL /fleetManagement/deviceGroups
Method GET
Permission mdpMeterGroup [View]
Parameters Name Description Type Optional/ Valid values Default
Mandatory
name Filter by match in device group name string Optional *
status Filter by status string Optional Active, *
Deactivated
Returns 200 OK

Page 59
 MultiDrive Web API 2.8 User Guide

401 Unauthorized (Token invalid)

403 Forbidden (Access not allowed)
500 Internal Server Error
{
"deviceGroups" : [
{
"deviceGroupId" : 34,
"name" : "Some Meters",
"status" : "Active"
},
{
"deviceGroupId" : 35,
"name" : "Some More Meters",
"status" : "Deactivated"
},
{
"deviceGroupId" : 36,
"name" : "Parent Meter Group",
"status" : "Active"
}
]
}

9.4.2. Get Device Group

URL /fleetManagement/deviceGroups/{deviceGroupId}
/fleetManagement/deviceGroups/name/{deviceGroupName}
Method GET
Permission mdpMeterGroup [View]
Returns 200 OK
401 Unauthorized (Token invalid)
403 Forbidden (Access not allowed)
404 Not Found
500 Internal Server Error
{
"deviceGroup" : {
"deviceGroupId" : 23,
"name" : "Some Meters",
"parentDeviceGroupId" : 34,
"status" : "Active"
}
}

9.4.3. Create Device Group

URL /fleetManagement/deviceGroups/
Method POST
Read only deviceGroupId
attributes
Permission mdpMeterGroup [Create]
Returns 201 Created - includes new device group object and location header containing the URN of the new
resource
400 Bad Request (returned if new group is not valid)
401 Unauthorized (Token invalid)
403 Forbidden (Access not allowed)
409 Conflict (Device group already exists). Id of conflicting resource will be returned here.
500 Internal Server Error

9.4.4. Update Device Group

URL /fleetManagement/deviceGroups/{deviceGroupId}
/fleetManagement/deviceGroups/name/{deviceGroupName}
Method PUT
Read only As per create
attributes

Page 60
 MultiDrive Web API 2.8 User Guide

Permission mdpMeterGroup [Modify]

Returns 200 OK (updated object is returned as well)
400 Bad Request (returned if new group is not valid)
401 Unauthorized (Token invalid)
403 Forbidden (Access not allowed)
404 Not Found
500 Internal Server Error

9.4.5. Delete Device Group

URL /fleetManagement/deviceGroups/{deviceGroupId}
/fleetManagement/deviceGroups/name/{deviceGroupName}
Method DELETE
Permission mdpMeterGroup [Delete]
Returns 200 OK
401 Unauthorized (Token invalid)
403 Forbidden (Access not allowed)
404 Not Found
500 Internal Server Error

9.4.6. List / Search Devices in Device Group

URL /fleetManagement/deviceGroups/{deviceGroupId}/devices
/fleetManagement/deviceGroups/name/{deviceGroupName}/devices
Method GET
Permission mdpMeterGroup [View]
Parameters Name Description Type Optional/ Valid Default
Mandatory values
deviceId Filter by match in device id Integer Optional
serialNumber Filter by match in serial number string Optional *
plantNumber Filter by match in plant number string Optional *
limit Maximum number of devices to return Integer Optional 0- 5000
status for in response 5000
offset Offset in devices to start returning Integer Optional * 0
statuses for in response
Returns 200 OK
401 Unauthorized (Token invalid)
403 Forbidden (Access not allowed)
500 Internal Server Error
{
"devices" : [
{
"plantNumber" : "Device A",
"SerialNumber" : "01234",
"deviceId" : 12,
},
{
"plantNumber" : "Device B",
"SerialNumber" : "456F45",
"deviceId" : 13,
},
{
"plantNumber" : "123453",
"SerialNumber" : "01222234",
"deviceId" : 14,
}, ...
]
}

9.4.7. Add Devices to Device Group

URL /fleetManagement/deviceGroups/{deviceGroupId}/devices
/fleetManagement/deviceGroups/name/{deviceGroupName}/devices
Page 61
 MultiDrive Web API 2.8 User Guide

Method POST
Permission mdpMeterGroup [Modify]
Payload {
"devices" : [
{
"deviceId" : 12,
},
{
"deviceId" : 13,
},
{
"deviceId" : 14,
}, ...
]
}

or by device Plant Number

{
"devices" : [
{
"plantNumber" : "Meter at Level 1",
},
{
"plantNumber" : "Meter at Level 2",
},
{
"plantNumber" : "Meter at Level 3",
}, ...
]
}
Optional Non-async call back notification is an optional element. When present in the request, a notification
Payload will be POSTed to the URI provided when the processing of the request is complete.

Payload
Additional parameter to be added to existing payload if non-async callback is required:
{
"notification":
{
"uri": "<scheme>://someserver/notifyme"
}
}
<scheme> can be "http", "https" or "topic".
Scheme Example Uri Descripion
http http://someserver/notifyme The callback will be posted to the HTTP URL
"http://someserver/notifyme"
https https://someserver/notifyme The callback will be posted to the HTTP URL
"https://someserver/notifyme"
topic topic://non-async-callback Depending on the "callbackQueueType" setting in Callback
Service, the callback will be sent to a RabbitMQ queue or a
Kafka topic
callbackQueueType Description
RabbitMQ The callback will be sent to the
queue "non-async-callback" on the
configured RabbitMQ broker
Kafka The callback will be sent to the
topic "non-async-callback" on the
configured Kafka broker

Notification
URI passed in will be called back as a POST request with the following payload format
{
"callback":
{
"requestUri": "http://server/api/xxxx/1",
"callbackId": "653a20db-adbb-41c9-a09b-371798fbc058",
"statusCode": "404",
"message": "Device Id (17) not found",
"errorCode": "XXXXX-002"
}
}

Property Description

Page 62
 MultiDrive Web API 2.8 User Guide

requestUri The URI of the original Web API request

callbackId The unique identifier used to correlate the current callback to the
original Web API request
statusCode The response HTTP status code of the Web API request
message (Optional) Response message from the Web API
errorCode (Optional) Error code from the Web API, when statusCode is not 2XX.

or when "UseExecutionPayloadInCallbacks" = true in web.config

{
"execution": {
"executionId": "653a20db-adbb-41c9-a09b-371798fbc058",
"jobsWithSuccess": 1,
"status": "Complete"
}
}

Returns 201 Created

401 Unauthorized (Token invalid)
403 Forbidden (Access not allowed)
404 Not Found (Device group does not exist, or plantNumber not found)
500 Internal Error

9.4.8. Remove Device From Device Group

URL /fleetManagement/deviceGroups/{deviceGroupId}/devices
/fleetManagement/deviceGroups/name/{deviceGroupName}/devices
Method DELETE
Permission mdpMeterGroup [Modify]
Payload {
"devices" : [
{
"deviceId" : 12,
},
{
"deviceId" : 13,
},
{
"deviceId" : 14,
}, ...
]
}
or by device Plant Number
{
"devices" : [
{
"plantNumber" : "Meter at Level 1",
},
{
"plantNumber" : "Meter at Level 2",
},
{
"plantNumber" : "Meter at Level 3",
}, ...
]
}
Optional Non-async call back notification is an optional element. When present in the request, a notification
Payload will be POSTed to the URI provided when the processing of the request is complete.

Payload
Additional parameter to be added to existing payload if non-async callback is required:
{
"notification":
{
"uri": "<scheme>://someserver/notifyme"
}
}
<scheme> can be "http", "https" or "topic".
Scheme Example Uri Descripion
http http://someserver/notifyme The callback will be posted to the HTTP URL
"http://someserver/notifyme"

Page 63
 MultiDrive Web API 2.8 User Guide

https https://someserver/notifyme The callback will be posted to the HTTP URL

"https://someserver/notifyme"
topic topic://non-async-callback Depending on the "callbackQueueType" setting in Callback
Service, the callback will be sent to a RabbitMQ queue or a Kafka
topic
callbackQueueType Description
RabbitMQ The callback will be sent to the
queue "non-async-callback" on the
configured RabbitMQ broker
Kafka The callback will be sent to the topic
"non-async-callback" on the
configured Kafka broker

Notification
URI passed in will be called back as a POST request with the following payload format
{
"callback":
{
"requestUri": "http://server/api/xxxx/1",
"callbackId": "653a20db-adbb-41c9-a09b-371798fbc058",
"statusCode": "404",
"message": "Device Id (17) not found",
"errorCode": "XXXXX-002"
}
}

Property Description
requestUri The URI of the original Web API request
callbackId The unique identifier used to correlate the current callback to the
original Web API request
statusCode The response HTTP status code of the Web API request
message (Optional) Response message from the Web API
errorCode (Optional) Error code from the Web API, when statusCode is not 2XX.

or when "UseExecutionPayloadInCallbacks" = true in web.config

{
"execution": {
"executionId": "653a20db-adbb-41c9-a09b-371798fbc058",
"jobsWithSuccess": 1,
"status": "Complete"
}
}
Returns 200 OK
401 Unauthorized (Token invalid)
403 Forbidden (Access not allowed)
404 Not Found (Device group does not exist, or plantNumber not found)
500 Internal Error

9.4.9. Configure Device to Leave and/or Join Device Groups

URL /fleetManagement/deviceGroups/devices/{deviceId}
/fleetManagement/deviceGroups/devices/plantNumber/{plantNumber}
Method POST
Permission mdpMeterGroup [Modify]
Payload {
"leave" : [
{
"deviceGroupId" : 12,
},
{
"deviceGroupId" : 13,
},
{
"deviceGroupId" : 14,
}, ...
],
"join" : [
{
"deviceGroupId" : 36,
},

Page 64
 MultiDrive Web API 2.8 User Guide

{
"deviceGroupId" : 59,
}, ...
]
}
or by device group name
{
"leave" : [
{
"deviceGroupName" : "Device Group 1",
},
{
"deviceGroupName" : "Device Group 2",
},
{
"deviceGroupName" : "Device Group 3",
}, ...
],
"join" : [
{
"deviceGroupName" : "New Device Group 1",
},
{
"deviceGroupName" : "New Device Group 2",
}, ...
]
}

Note: When a wildcard match is required, a regular expression can be used in place of the specific
device group name.
E.g.
{
"leave" : [
{
"deviceGroupName" : "^Device Group (\d+)$",
}
],
"join" : [
{
"deviceGroupName" : "New Device Group 1",
}, ...
]
}
Property Required Type Description
Leave No Array of device Specifies the list of
group Ids or device groups from
Names which the device must
leave
deviceGroupId Yes, Integer Id of the device group
either deviceGroupId which the device must
or deviceGroupName leave
deviceGroupName (but not both) must String Name of the device
be specified group which the device
must leave. A regular
expression can be used
in place of the specific
device group name.
The device will leave all
the device groups with
names matching the
regular expression.
Join No Array of device Specifies the list of
group Ids or device groups which
Names the device must join.
deviceGroupId Yes, Integer Id of the device group
either deviceGroupId which the device must
or deviceGroupName join
deviceGroupName (but not both) must String Name of the device
be specified group which the device
must join.A regular
expression can be used
in place of the specific

Page 65
 MultiDrive Web API 2.8 User Guide

device group name.

The device will join all
the device groups with
names matching the
regular expression.

Optional Non-async call back notification is an optional element. When present in the request, a notification will
Payload be POSTed to the URI provided when the processing of the request is complete.

Payload
Additional parameter to be added to existing payload if non-async callback is required:
{
"notification":
{
"uri": "<scheme>://someserver/notifyme"
}
}
<scheme> can be "http", "https" or "topic".
Scheme Example Uri Descripion
http http://someserver/notifyme The callback will be posted to the HTTP URL
"http://someserver/notifyme"
https https://someserver/notifyme The callback will be posted to the HTTP URL
"https://someserver/notifyme"
topic topic://non-async-callback Depending on the "callbackQueueType" setting in Callback
Service, the callback will be sent to a RabbitMQ queue or a Kafka
topic
callbackQueueType Description
RabbitMQ The callback will be sent to the queue
"non-async-callback" on the
configured RabbitMQ broker
Kafka The callback will be sent to the topic
"non-async-callback" on the
configured Kafka broker

Notification
URI passed in will be called back as a POST request with the following payload format
{
"callback":
{
"requestUri": "http://server/api/xxxx/1",
"callbackId": "653a20db-adbb-41c9-a09b-371798fbc058",
"statusCode": "404",
"message": "Device Id (17) not found",
"errorCode": "XXXXX-002"
}
}

Property Description
requestUri The URI of the original Web API request
callbackId The unique identifier used to correlate the current callback to the
original Web API request
statusCode The response HTTP status code of the Web API request
message (Optional) Response message from the Web API
errorCode (Optional) Error code from the Web API, when statusCode is not 2XX.

or when "UseExecutionPayloadInCallbacks" = true in web.config

{
"execution": {
"executionId": "653a20db-adbb-41c9-a09b-371798fbc058",
"jobsWithSuccess": 1,
"status": "Complete"
}
}
Returns 200 OK
400 Bad Request (If both "leave" and "join" are empty or the groups to join is not found)
401 Unauthorized (Token invalid)
403 Forbidden (Access not allowed)
404 Not Found (Device id does not exist, or plantNumber not found)
500 Internal Error

Page 66
 MultiDrive Web API 2.8 User Guide

9.5. Commissioning
9.5.1. Commission a SMETS device in the system
URL /fleetManagement/smets/commission/
Method POST
Permission mdpDevice [Create]
Parameters Name Description Type Optional/ Valid Default
Mandatory values
SerialNumber Electrical / Gas Meter Serial String Mandatory
Number
IMEI HUB IMEI Number String Mandatory
ICCID SIM ICCID (In case the original String Optional
linked SIM card doesn't work)
NotifyPhoneNumber Phone number to notify on String Optional
commissioning success/fail
Returns 200 OK
400 Bad Request (empty serial number or IMEI)
401 Unauthorized (Token invalid)
403 Forbidden (Access not allowed)
404 Not Found (Serial Number, IMEI, ICCID does not exist)
500 Internal Server Error
Notes This API method results in a commissioning event created, which is searchable using "List / Search
Commissioning Events".

9.5.2. Request ZigBee paring for SMETS Gas Device

URL /fleetManagement/smets/zigbee/pair/gas
Method POST
Permission mdpDevice [Create]
Parameters Name Description Type Optional/ Valid Default
Mandatory values
IMEI Master HUB IMEI Number String Mandatory
SlaveMeterSerialNumber Slave Meter Serial Number String Mandatory
InstallCode HUB Install code number. Min String Optional
8 bytes and Max 18 bytes (16
- 36 Hexadecimal values - 0 to
F)
ZigBeeJoinTime Open time for ZigBee device Intege Optional 1- 300
to allow HAN device joining r 65534
(In seconds).
NotifyPhoneNumber Phone number to notify on String Optional
commissioning success/fail
Returns 200 OK
400 Bad Request (empty IMEI, empty SlaveMeterSerialNumber, invalid InstallCode, out of range ZigBee
Join Time)
401 Unauthorized (Token invalid)
403 Forbidden (Access not allowed or MAC Address was blacklisted)
404 Not Found (IMEI / SlaveMeterSerialNumber not found in the system)
500 Internal Server Error

9.5.3. Request ZigBee pairing for SMETS IHD device

URL /fleetManagement/smets/zigbee/pair/ihd
Method POST
Permission mdpDevice [Create]

Page 67
 MultiDrive Web API 2.8 User Guide

Parameters Name Description Type Optional/ Valid Default

Mandatory values
IMEI Master HUB IMEI Number String Mandatory
MACAddress EUI64/MAC Address of IHD String Mandatory
InstallCode HUB Install code number. String Optional
Min 8 bytes and Max 18
bytes (16 - 36 Hexadecimal
values - 0 to F)
ZigBeeJoinTime Open time for ZigBee device Integer Optional 1 - 65534 300
to allow HAN device joining
(In seconds).
NotifyPhoneNumber Phone number to notify on String Optional
commissioning success/fail
Returns 200 OK
400 Bad Request (empty IMEI, empty MAC Address, invalid InstallCode, out of range ZigBeeJoinTime)
401 Unauthorized (Token invalid)
403 Forbidden (Access not allowed or MAC Address was blacklisted)
404 Not Found (IMEI / MACAddress not found in the system)
500 Internal Server Error

9.5.4. Request ZigBee un-pairing for SMETS Gas Device

URL /fleetManagement/smets/zigbee/unpair/gas
Method POST
Permission mdpDevice [Update]
Parameters Name Description Type Optional/ Valid Default
Mandatory values
IMEI Master HUB IMEI Number String Mandatory
SlaveMeterSerialNumber Slave Meter Serial Number String Mandatory
NotifyPhoneNumber Phone number to notify on String Optional
commissioning success/fail
Returns 200 OK
400 Bad Request (empty IMEI)
401 Unauthorized (Token invalid)
403 Forbidden (Access not allowed)
404 Not Found (IMEI / SlaveMeterSerialNumber not found in the system)
500 Internal Server Error

9.5.5. Request ZigBee un-pairing for SMETS IHD device

URL /fleetManagement/smets/zigbee/unpair/ihd
Method POST
Permission mdpDevice [Update]
Parameters Name Description Type Optional/ Valid Default
Mandatory values
IMEI Master HUB IMEI Number String Mandatory
MACAddress EUI64/MAC Address of IHD String Mandatory
NotifyPhoneNumber Phone number to notify on String Optional
commissioning success/fail
Returns 200 OK
400 Bad Request (empty IMEI)
401 Unauthorized (Token invalid)
403 Forbidden (Access not allowed)
404 Not Found (IMEI / MACAddress not found in the system)
500 Internal Server Error
9.5.6. Commission a device in the system
URL /fleetManagement/commission/{deviceId}

Page 68
 MultiDrive Web API 2.8 User Guide

/fleetManagement/commission/plantNumber/{plantNumber}
Method POST
Permission mdpDevice [Create]
Parameters Name Description Type Optional/ Valid Default
Mandatory values
siteId Link device to this site String Optional *
deviceGroupId Assign device to this group Integer Optional *
scheduleId Run this schedule against the device String Optional *
Returns 200 OK
201 Created - includes location header containing the URN of the created execution
(/scheduling/executions/{executionId}) if a schedule id is included
400 Bad Request (Site id, deviceGroupId or schedule id is not valid)
401 Unauthorized (Token invalid)
403 Forbidden (Access not allowed)
404 Not Found (Device id does not exist)
500 Internal Server Error
Notes This API method does not result in a commissioning event, hence it is not included in the results of "List /
Search Commissioning Events".

9.5.7. Decommission a device in the system

URL /fleetManagement/decommission/{deviceId}
/fleetManagement/decommission/plantNumber/{plantNumber}
Method POST
Permission mdpDevice [Modify]
Parameters Name Description Type Optional/ Valid Default
Mandatory values
removeFromGroup Remove device from all groups Boolean Optional *
deviceGroupId Assign device to this group Integer Optional *
Returns 200 OK
400 Bad Request (deviceGroup id is not valid)
401 Unauthorized (Token invalid)
403 Forbidden (Access not allowed)
404 Not Found (Device id does not exist)
500 Internal Server Error

9.5.8. Decommission multiple devices in the system

URL /fleetManagement/decommission/devices
Method POST
Permission mdpDevice [Modify]
Parameters Name Description Type Optional/ Valid Default
Mandatory values
removeFromGroup Remove device from all groups Boolean Optional *
deviceGroupId Assign device to this group Integer Optional *
Payloads By device Id
{
"devices" : [
{
"deviceId" : 12,
},
{
"deviceId" : 13,
},
{
"deviceId" : 14,
}, ...
]
Page 69
 MultiDrive Web API 2.8 User Guide

}
Or by plant number
{
"devices" : [
{
"plantNumber" : "Meter at Level 1",
},
{
"plantNumber" : "Meter at Level 2",
},
{
"plantNumber" : "Meter at Level 3",
}, ...
]
}
Returns 200 OK
400 Bad Request (deviceGroup id is not valid)
401 Unauthorized (Token invalid)
403 Forbidden (Access not allowed)
404 Not Found (Device id does not exist)
500 Internal Server Error

9.5.9. List / Search Commissioning Events

URL /fleetManagement/events/commissioning
Method GET
Permission mdpDevice [View]
Parameters Name Description Type Optional/ Valid Default
Mandatory values
serialNumber Filter by match in manufacturer string Optional *
serial number
plantNumber Filter by match in plant number string Optional *
commissioningCode Filter by match in Commissioning string Optional *
Code
startDate date Mandatory -
endDate date Mandatory -
Returns 200 OK
401 Unauthorized (Token invalid)
403 Forbidden (Access not allowed)
500 Internal Server Error
{
"commissioningEvents": [
{
"deviceId" : 32,
"serialNumber" : "211650803",
"plantNumber" : "ABS33241OR",
"deviceConfig" : "",
"modemIMEI" : "",
"firmwareVersion" : "",
"firmwareEdition" : 0,
"firmwareRevision" : 0,
"IPAddress" : "",
"ICCID" : "",
"MSISDN" : "",
"baseStation" : "",
"signalStrength" : 0,
"date" : "2013-01-21T03:34:00",
"status" : "SUCCESS",
"commissioningCode" : "3585" ,
"errorMessage" : ""
},
{
"deviceId" : 33,
"serialNumber" : "41545456",
"plantNumber" : "SD4TG93824E",
"deviceConfig" : "",
"modemIMEI" : "",
"firmwareVersion" : "",

Page 70
 MultiDrive Web API 2.8 User Guide

"firmwareEdition" : 0,
"firmwareRevision" : 0,
"IPAddress" : "",
"ICCID" : "",
"MSISDN" : "",
"baseStation" : "",
"signalStrength" : 0,
"date" : "2013-01-22T12:14:33",
"status" : "FAILED",
"commissioningCode" : "" ,
"errorMessage" : "Signal Strength is too low"
},...
]
}
Notes This API method lists/searches the commissioning events created by "Commission a SMETS device in the
system".

Description
Property Optional/ Format Valid Values Description
Mandatory
deviceId Mandatory Integer Multidrive identifier
serialNumber Mandatory String Manufacturer serial number
plantNumber Mandatory String Customer assigned market identifier
modemIMEI Mandatory String Modem IMEI number
firmwareVersion Mandatory String Firmware Version
firmwareEdition Mandatory Integer Firmware Edition
firmwareRevision Mandatory Integer Firmware Revision
IPAddress Mandatory String IP address and port number
ICCID Mandatory String SIM ICC-ID
MSISDN Mandatory String SIM MSISDN (Phone number)
baseStation Mandatory String Base Station infomation
signalStrength Mandatory Integer Signal Strength
date Mandatory String Date of commissioning event
status Mandatory String PROCESSING, FAILED, Status of commissioning
SUCCESS
commissioningCode Mandatory String Commissioning code assigned
bymultidrive
errorMessage Mandatory String Error message which caused the
commission to fail

9.5.10. List / Search Gas Device Pairing Events

URL /fleetManagement/events/gasPairing
Method GET
Permission mdpDevice [View]
Parameters Name Description Type Optional/ Valid Default
Mandatory values
serialNumber Filter by match in manufacturer string Optional *
serial number
plantNumber Filter by match in plant number string Optional *
commissioningCode Filter by match in Commissioning string Optional *
Code
startDate date Mandatory -
endDate date Mandatory -
Returns 200 OK
401 Unauthorized (Token invalid)
403 Forbidden (Access not allowed)
500 Internal Server Error
{
"events": [
{
"serialNumber" : "897625142",
"date" : "2013-01-22T12:14:33",

Page 71
 MultiDrive Web API 2.8 User Guide

"status" : "FAILED",
"commissioningCode" : "" ,
"errorMessage" : "Signal Strength is too low"
},...
]
}

Description
Property Optional/ Format Valid Values Description
Mandatory
serialNumber Mandatory String Serial Number of Gas Meter involved
date Mandatory String Date of commissioning event
status Mandatory String PROCESSING, FAILED, Status of commissioning
SUCCESS
commissioningCode Mandatory String Commissioning code assigned by
multidrive
errorMessage Mandatory String Error message which caused the
commission to fail

9.5.11. List / Search IHD Device Pairing Events

URL /fleetManagement/events/IHDPairing
Method GET
Permission mdpDevice [View]
Parameters Name Description Type Optional/ Valid Default
Mandatory values
MACAddress Filter by match in MAC Address string Optional *
commissioningCode Filter by match in Commissioning string Optional *
Code
startDate date Mandatory -
endDate date Mandatory -
Returns 200 OK
401 Unauthorized (Token invalid)
403 Forbidden (Access not allowed)
500 Internal Server Error
{
"events": [
{
"MACAddress" : "00905C0000003FF3",
"date" : "2013-01-22T12:14:33",
"status" : "FAILED",
"commissioningCode" : "" ,
"errorMessage" : "Signal Strength is too low"
},...
]
}

Description
Property Optional/ Format Valid Values Description
Mandatory
MACAddress Mandatory String MAC Address of In Home Display Device
date Mandatory String Date of commissioning event
status Mandatory String PROCESSING, FAILED, Status of commissioning
SUCCESS
commissioningCode Mandatory String Commissioning code assigned by
multidrive
errorMessage Mandatory String Error message which caused the
commission to fail

Page 72
 MultiDrive Web API 2.8 User Guide

9.6. Modems

9.6.1. List / Search Modems

URL /fleetManagement/modem
/fleetManagement/modem/{modemid}
Method GET
Permission mdpModem [View]
Parameters Name Description Type Optional/ Valid values Default
Mandatory
imei Filter by IMEI number String Optional *
modemModel- Filter by modem Model String Optional *
Name Name
serialNumber Filter by Serial Number String Optional *
firmwareVersion Filter by Firmware Version String Optional *
status Filter by Modem Status String Optional WAITING
INSTALLATION /
INSTALLED /
OUT OF
SERVICE
limit Maximum number of Integer Optional 0 - 5000 5000
objects to return status for
in response
offset Offset in objects to start Integer Optional * 0
returning statuses for in
response
Returns 200 OK
401 Unauthorized (Token invalid)
403 Forbidden (Access not allowed)
500 Internal Server Error
{
"modem" : [
{
"modemId" : 123,
"imei": "356187030007426",
"modemModelName" : "EWM100",
"serialNumber" : "AK9390012501300",
"firmwareVersion" : "R7.45.1",
"status" : "Installed"
},...
]
}

Description
Property Optional/ Format Valid Values Description
Mandatory
modemId Mandatory Integer Modem Auto Id
imei Mandatory String modem IMEI (http://en.wikipedia.org/wiki/
International_Mobile_Station_Equipment_Identity)
status Mandatory String WAITING Status of Modem
INSTALLATION
/ INSTALLED /
OUT OF
SERVICE
modemModelName Optional String Modem Model Name
serialNumber Optional String Modem Serial Number
firmwareVersion Optional String Modem Firmware Version

Page 73
 MultiDrive Web API 2.8 User Guide

9.6.2. Create Modem

URL /fleetManagement/modem
Method POST
Permission mdpModem [Create]
Payload MDX Modem object same as in Get Modem operation
Read only modemId
attributes
Returns 201 Created - includes created object and location header containing the URN of the new
resource (/modem/{modemid})
400 Bad Request (returned if new modem is not valid)
401 Unauthorized (Token invalid)
403 Forbidden (Access not allowed)
409 Conflict (IMEI already exists)
500 Internal Server Error

9.6.3. Delete Modem

URL /fleetManagement/modem/{modemId}
/fleetManagement/modem/imei/{imei}
Method DELETE
Permission mdpModem [Delete]
Returns 200 OK
401 Unauthorized (Token invalid)
403 Forbidden (Access not allowed)
404 Not Found

9.6.4. Update Modem

URL /fleetManagement/modem/{modemId}
/fleetManagement/modem/imei/{imei}
Method PUT
Permission mdpModem [Modify]
Read only attributes modemId
Parameters/Payload As per create
Returns 200 OK (this will return the updated modem details)
400 Bad Request (modem changes are not valid)
401 Unauthorized (Token invalid)
403 Forbidden (Access not allowed)
404 Not Found
409 Conflict (IMEI already exists)
500 Internal Server Error

9.7. SIM Cards

9.7.1. List / Search SIMs
URL /fleetManagement/sim
/fleetManagement/sim/{simId}
Method GET
Permission mdpSIM [View]
Parameters Name Description Type Optional/ Valid values Default
Mandatory
iccid Filter by ICCID String Optional *
imsi Filter by IMSI String Optional *
Page 74
 MultiDrive Web API 2.8 User Guide

msisdn Filter by MSISDN String Optional *

status Filter by SIM Status String Optional ACTIVATED,
DEACTIVATED
limit Maximum number of objects to Integer Optional 0 - 5000 5000
return status for in response
offset Offset in objects to start returning Integer Optional * 0
statuses for in response
Returns 200 OK
401 Unauthorized (Token invalid)
403 Forbidden (Access not allowed)
500 Internal Server Error
{
"sim" : [
{
"simId" : 23,
"networkProviderName": "Singtel",
"dataPlanName" : "4G Plus Package",
"iccid" : "1234",
"imsi" : "5678",
"msisdn" : "6567567538",
"mcc" : "65",
"mnc" : "02",
"country" : "Singapore",
"status" : "ACTIVATED"
},...
]
}

Description
Property Optional/ Forma Valid Values Description
Mandatory t
simId Mandatory Integer SIM Auto Id

iccid Mandatory String Unique Serial Number of SIM Card

(http://en.wikipedia.org/wiki/ICCID#ICCID)
status Mandatory String ACTIVATED, Status of SIM Card
DEACTIVATE
D
networkProviderNam Optional String Name of Network Provider / Telco
e
dataPlanName Optional String Data Subscrition Plan Name
imsi Optional String International Mobile Subscriber Identity
(http://en.wikipedia.org/wiki/IMSI)
msisdn Optional String MSISDN (http://en.wikipedia.org/wiki/MSISDN)
mcc Optional String Mobile Country Code
(http://en.wikipedia.org/wiki/Mobile_country_cod
e)
mnc Optional String Mobile Network Code
(http://en.wikipedia.org/wiki/Mobile_country_cod
e)
country Optional String Country

9.7.2. Create SIM

URL /fleetManagement/sim
Method POST
Permission mdpSIM [Create]
Payload MDX SIM object same as in Get SIM operation
Read only attributes simId
Returns 201 Created - includes created object and location header containing the URN of the new
resource (/sim/{simid})
400 Bad Request (returned if new sim is not valid)
401 Unauthorized (Token invalid)

Page 75
 MultiDrive Web API 2.8 User Guide

403 Forbidden (Access not allowed)

409 Conflict (ICCID already exists)
500 Internal Server Error

9.7.3. Update SIM

URL /fleetManagement/sim/{simId}
/fleetManagement/sim/iccid/{iccid}
Method PUT
Permission mdpSIM [Modify]
Read only attributes simId
Parameters/Payload As per create
Returns 200 OK (this will return the updated sim details)
400 Bad Request (sim changes are not valid)
401 Unauthorized (Token invalid)
403 Forbidden (Access not allowed)
404 Not Found
409 Conflict (ICCID already exists)
500 Internal Server Error

9.7.4. Delete SIM

URL /fleetManagement/sim/{simId}
/fleetManagement/sim/iccid/{iccid}
Method DELETE
Permission mdpSIM [Delete]
Returns 200 OK
401 Unauthorized (Token invalid)
403 Forbidden (Access not allowed)
404 Not Found

9.8. Gas Clorific Value

9.8.1. List / Search Gas Calorific Value
URL /fleetManagement/device/gas/calorificvalue
/fleetManagement/device/gas/calorificvalue/{calorificValueId}
Method GET
Permission mdpDevice [View]
Parameters Name Description Type Optional/ Valid Default
Mandatory values
name Unique Identifier of Gas Calorific Value String Optional *
Returns 200 OK
401 Unauthorized (Token invalid)
403 Forbidden (Access not allowed)
500 Internal Server Error
{
"calorificValue" : [
{
"calorificValueId" : 123,
"name": "Calorific Group 1",
"conversionFactor " : 2.83,
"calorificValue" : 39.47333
},...
]
}

Page 76
 MultiDrive Web API 2.8 User Guide

Description
Property Optional/ Format Valid Description
Mandatory Values
calorificValueId Mandatory Integer Calorific Value Auto Id
name Mandatory String Unique Identifier of the calorific group
conversionFactor Mandatory Float Conversion Factor
calorificValue Mandatory Float Calorific Value

9.8.2. Create Gas Calorific Value

URL /fleetManagement/device/gas/calorificvalue
Method POST
Permission mdpDevice [Create]
Payload MDX Gas Calorific Value object same as in List / Search Gas Calorific Value
Read only calorificValueId
attributes
Returns 201 Created - includes created object and location header containing the URN of the new resource
(device/gas/calorificvalue/{calorificValueId})
400 Bad Request (returned if new Gas Calorific Value is not valid)
401 Unauthorized (Token invalid)
403 Forbidden (Access not allowed)
409 Conflict (name already exists)
500 Internal Server Error

9.8.3. Delete Gas Calorific Value

URL /fleetManagement/device/gas/calorificvalue/{calorificValueId}
/fleetManagement/device/gas/calorificvalue/name/{name}
Method DELETE
Permission mdpDevice [Delete]
Returns 200 OK
401 Unauthorized (Token invalid)
403 Forbidden (Access not allowed)
404 Not Found

9.8.4. Update Gas Calorific Value

URL /fleetManagement/device/gas/calorificvalue/{calorificValueId}
/fleetManagement/device/gas/calorificvalue/name/{name}
Method PUT
Permission mdpDevice [Modify]
Read only attributes calorificValueId
Parameters/Payload As per create
Returns 200 OK (this will return the updated calorific value details)
400 Bad Request (calorific value changes are not valid)
401 Unauthorized (Token invalid)
403 Forbidden (Access not allowed)
404 Not Found
409 Conflict (name already exists)
500 Internal Server Error

9.9. Device Setups

9.9.1. Schedule Write Device Setup Stages
URL /fleetManagement/writeDeviceSetupStages/{deviceId}
Page 77
 MultiDrive Web API 2.8 User Guide

/fleetManagement/writeDeviceSetupStages/plantNumber/{plantNumber}
Method POST
Permission mdpDeviceSetupTemplateAtlas2 [Create]
Payload
* Generic Atlas 2
Change TariffChangeoverData and TenancyData
{
"setupStages": [{
"stageName": "TariffChangeoverData",
"setupXml": "<TariffChangeoverData>
<CalendarChangeoverDate>2000-01-
01T00:00:00</CalendarChangeoverDate>
<PriceMatrixChangeoverDate>2000-01-
01T00:00:00</PriceMatrixChangeoverDate>
<BlockMonitorsChangeoverDate>2000-01-
01T00:00:00</BlockMonitorsChangeoverDate>
<CotChangeoverDate>2000-01-
18T00:00:00</CotChangeoverDate>
<StandingChargesChangeoverDate>2000-01-
01T00:00:00</StandingChargesChangeoverDate>
<MajorVersion>1</MajorVersion>
<MinorVersion>0</MinorVersion>
</TariffChangeoverData>"
},
{
"stageName": "TenancyData",
"setupXml": "<TenancyData>
<TenancyID>12</TenancyID>
<COT>2016-01-23T00:00:00</COT>
<MajorVersion>1</MajorVersion>
<MinorVersion>0</MinorVersion>
</TenancyData>"
}]
}

* First Utility GAS API specific

Change read type / Frequency (Daily)
{
"setupStages": [{
"stageName": "ReadFrequency",
"setupXml": "
<ReadFrequency>
<DailyRead>
<PushTime>00:00:00</PushTime>
</DailyRead>
</ReadFrequency>"
}]
}

Change read type / Frequency (Monthly)

{
"setupStages": [{
"stageName": "ReadFrequency",
"setupXml": "
<ReadFrequency>
<MonthlyRead>
<PushTime>00:00:00</PushTime>
</MonthlyRead>
</ReadFrequency>"
}]
}

Change Billing Reset Date

{
"setupStages": [{
"stageName": "TariffBilling",
"setupXml": "
<TariffBillingData>
<ChangeOverDateTime>2017-03-08T22:00:00</ChangeOverDateTime>
<ExecutionTime>
<BillingCycleTime>00:30:00</BillingCycleTime>
<DayOfMonth>2</DayOfMonth>
</ExecutionTime>
</TariffBillingData>"
}]
}

Page 78
 MultiDrive Web API 2.8 User Guide

Change of Tenancy
{
"setupStages": [{
"stageName": "Tenancy",
"setupXml": "
<TenancyData>
<COT>2017-03-08T11:00:00</COT>
<TenancyID>somestring</TenancyID>
<ChangeOverDateTime>2017-03-08T11:00:00</ChangeOverDateTime>
</TenancyData>"
}]
}

Change of Supplier
{
"setupStages": [{
"stageName": "SMETS1Supplier",
"setupXml": "
<SMETS1SupplierData>
<NewSupplierDateTime >2017-03-08T11:00:00</NewSupplierDateTime>
<NewSupplierID>somestring</NewSupplierID>
<ChangeOverDateTime>2017-03-08T11:00:00</ChangeOverDateTime>
</SMETS1SupplierData>"
}]
}

Price Change Single Rate

{
"setupStages": [{
"stageName": "PriceMatrix",
"setupXml": "
<PriceMatrixData>
<RatePrices>
<decimal>10000</decimal>
</RatePrices>
<ActivateValuePassiveTime>2017-03-08T11:00:00</ActivateValuePassiveTime>
<PassiveStandingChargeRate>100000</PassiveStandingChargeRate>
<StandingChargeChangeOverDateTime>2017-03-
08T11:00:00</StandingChargeChangeOverDateTime>
</PriceMatrixData>"
}]
}

Price Change Dual Rate

{
"setupStages": [{
"stageName": "PriceMatrix",
"setupXml": "
<PriceMatrixData>
<RatePrices>
<decimal>10000</decimal>
<decimal 20000</decimal>
</RatePrices>
<ActivateValuePassiveTime>2017-03-08T11:00:00</ActivateValuePassiveTime>
<PassiveStandingChargeRate>100000</PassiveStandingChargeRate>
<StandingChargeChangeOverDateTime>2017-03-
08T11:00:00</StandingChargeChangeOverDateTime>
<PassiveCalendarActivationTime>
<ScheduleDateTime>2017-03-08T11:00:00</ScheduleDateTime>
</PassiveCalendarActivationTime>
<DayProfiles>
<DayProfile>
<DayID>1</DayID>
<DayProfileActions>
<DayProfileAction>
<SwitchTime>00:00:00</SwitchTime>
<ScriptLogicalName/>
<Rate>1</Rate>
</DayProfileAction>
<DayProfileAction>
<SwitchTime>00:00:00</SwitchTime>
<ScriptLogicalName/>
<Rate>2</Rate>
</DayProfileAction>
</DayProfileActions>
</DayProfile>
</DayProfiles>
</PriceMatrixData>"
}]
}

Calorific Value
{

Page 79
 MultiDrive Web API 2.8 User Guide

"setupStages": [{
"stageName": "CalorificValue",
"setupXml": "
<CalorificValue>
<PassiveConversionDataValue>
<CalorificValue>33300</CalorificValue>
</PassiveConversionDataValue>
<ActivateValuePassiveTime>2017-02-
28T10:00:00</ActivateValuePassiveTime>
</CalorificValue>"
}]
}

Optional Call back notification is an optional element and when present will mean that a notification will be
Payload POSTed to the URI provided. If not requiring notification (using polling instead) then payload can be
Empty.

Payload
Additional parameter to be added to existing payload if callback is required:
{
"notification":
{
"uri": "http://someserver/notifyme"
},
"notifyStatus":
{
"status": [ "Complete", "No Jobs" ]
}
}

<scheme> can be "http", "https" or "topic".

Scheme Example Uri Descripion
http http://someserver/notifyme The callback will be posted to the HTTP URL
"http://someserver/notifyme"
https https://someserver/notifyme The callback will be posted to the HTTP URL
"https://someserver/notifyme"
topic topic://schedule-execution- Depending on the "callbackQueueType" setting in Callback
callback Service, the callback will be sent to a RabbitMQ queue or a Kafka
topic
callbackQueueType Description
RabbitMQ The callback will be sent to the queue
"schedule-execution-callback" on the
configured RabbitMQ broker
Kafka The callback will be sent to the topic
"schedule-execution-callback" on the
configured Kafka broker

Notification
URI passed in will be called back as a POST request.
Payload will be the same as Get Schedule Execution (/scheduling/executions/{executionId})
{
"execution": {
"executionId" : 14,
"scheduleId" : 12,
"startDate" : "2013-01-21T10:00:00",
"endDate" : "2013-01-21T12:00:00",
"jobsWithSuccess" : 3,
"jobsWithFailure" : 5,
"status" : "Complete",
"hasWarning" : "true",
"totalJobs" : 10,
"queuedJobs" : 2
}
}

Status can be Unknown, Queued, Running, Complete, No Jobs, Cancelled, Paused

Optional Dynamic Schedule Settings

Payload The following payload can optionally be specified to control some aspects of the dynamic schedule
being triggered.
{
"dynamicScheduleSettings": {
"duration": 86400, // seconds
"priority": "Medium",

Page 80
 MultiDrive Web API 2.8 User Guide

"retryCount": 2,
"retryDelay": 300000, // milliseconds
"timeToLive": 96, // hours
"executionTime": "2016-05-16T16:50:00Z"
}
}
Returns 202 Accepted - includes location header with the endpoint "/scheduling/executions/{executionId}" to
determine if schedule has been sent to the meter. This endpoint will return a 200 OK with a
representation of the commands status when the device has successfully received the command.
401 Unauthorized (Token invalid)
403 Forbidden (Access not allowed)
404 Not Found (Device does not exist, or plantNumber not found)
500 Internal Error

Description
Property Format Default Value Valid Values Description
duration Integer 86400 60 to 2147483647 Number of seconds the schedule is given before
failing.
priority String “Medium” "Very High", "High", Priority of the schedule relative to all other
"Medium", "Low", "Very MultiDrive schedules.
Low"
retry count Integer 2 0 to 255 Maximum number of retries for the schedule.
retryDelay Integer 300000 60000 to 2147483647 Number of milliseconds to wait for the schedule
retries.
timeToLive Integer 96 1 to 32767 Number of hours the schedule execution status will
remain in the system.
executionTime ISO8601 Date - - Date and time when the schedule should run.
String If the specified time has passed when the request
reaches MultiDrive, the schedule will be executed
immediately.

Note: This property is currently not supported in

Supply Control API.
Prepayment API (Pass prepayment token to
meter).

9.9.2. Schedule Read Device Setup Stages

URL /fleetManagement/readDeviceSetupStages/{deviceId}
/fleetManagement/readDeviceSetupStages/plantNumber/{plantNumber}
Method POST
Permission mdpDeviceSetupTemplateAtlas2 [View]
{
Payload "setupStages": [{
"stageName": "TariffChangeover"
},
{
"stageName": "Tenancy"
},
{
"stageName": "LoadSurvey1"
}...]
}
Optional Call back notification is an optional element and when present will mean that a notification will be POSTed
Payload to the URI provided. If not requiring notification (using polling instead) then payload can be Empty.
Payload
Additional parameter to be added to existing payload if callback is required:
{
"notification":
{
"uri": "http://someserver/notifyme"
},
"notifyStatus":
{
"status": [ "Complete", "No Jobs" ]
}
}

Page 81
 MultiDrive Web API 2.8 User Guide

<scheme> can be "http", "https" or "topic".

Scheme Example Uri Descripion
http http://someserver/notifyme The callback will be posted to the HTTP URL
"http://someserver/notifyme"
https https://someserver/notifyme The callback will be posted to the HTTP URL
"https://someserver/notifyme"
topic topic://schedule-execution- Depending on the "callbackQueueType" setting in Callback Service,
callback the callback will be sent to a RabbitMQ queue or a Kafka topic
callbackQueueType Description
RabbitMQ The callback will be sent to the queue
"schedule-execution-callback" on the
configured RabbitMQ broker
Kafka The callback will be sent to the topic
"schedule-execution-callback" on the
configured Kafka broker

Notification
URI passed in will be called back as a POST request.
Payload will be the same as Get Schedule Execution (/scheduling/executions/{executionId})
{
"execution": {
"executionId" : 14,
"scheduleId" : 12,
"startDate" : "2013-01-21T10:00:00",
"endDate" : "2013-01-21T12:00:00",
"jobsWithSuccess" : 3,
"jobsWithFailure" : 5,
"status" : "Complete",
"hasWarning" : "true",
"totalJobs" : 10,
"queuedJobs" : 2
}
}

Status can be Unknown, Queued, Running, Complete, No Jobs, Cancelled, Paused

Optional Dynamic Schedule Settings

Payload The following payload can optionally be specified to control some aspects of the dynamic schedule being
triggered.
{
"dynamicScheduleSettings": {
"duration": 86400, // seconds
"priority": "Medium",
"retryCount": 2,
"retryDelay": 300000, // milliseconds
"timeToLive": 96, // hours
"executionTime": "2016-05-16T16:50:00Z"
}
}
Returns 202 Accepted - includes location header with the endpoint "/scheduling/executions/{executionId}" to
determine if schedule has been sent to the meter. This endpoint will return a 200 OK with a representation
of the commands status when the device has successfully received the command.
400 Bad Request (Request payload not specified or is empty)
401 Unauthorized (Token invalid)
403 Forbidden (Access not allowed)
404 Not Found (Device Id or plant number not found)
500 Internal Error

Description
Property Format Default Value Valid Values Description
duration Integer 86400 60 to 2147483647 Number of seconds the schedule is given before
failing.
priority String “Medium” "Very High", "High", Priority of the schedule relative to all other
"Medium", "Low", "Very MultiDrive schedules.
Low"
retry count Integer 2 0 to 255 Maximum number of retries for the schedule.
retryDelay Integer 300000 60000 to 2147483647 Number of milliseconds to wait for the schedule
retries.

Page 82
 MultiDrive Web API 2.8 User Guide

timeToLive Integer 96 1 to 32767 Number of hours the schedule execution status will
remain in the system.
executionTime ISO8601 Date - - Date and time when the schedule should run.
String If the specified time has passed when the request
reaches MultiDrive, the schedule will be executed
immediately.

Note: This property is currently not supported in

Supply Control API.
Prepayment API (Pass prepayment token to
meter).

9.9.3. Get Last Read Device Setup

URL /fleetManagement/deviceSetups/{deviceId}
/fleetManagement/deviceSetups/plantNumber/{plantNumber}
Method GET
Permission mdpDevice [View]
Parameters Name Description Type Optional/ Valid Default
Mandatory Values
setupStageNames Comma-separated string string Optional *
specifying the names of setup
stages required.
All setup stages are returned if
this parameter is not specified.

Returns 200 OK
401 Unauthorized (Token invalid)
403 Forbidden (Access not allowed)
404 Not Found (Device does not exist, or plantNumber not found)
500 Internal Server Error

{
"deviceSetup": {
"setupDate": "2016-01-01T00:00:00Z",
"setupString": "<<device setup string in MTR or XML format, Base64-
encoded>>"
}
}

9.9.4. Create Device Setup Template

URL /fleetManagement/deviceSetupTemplates
Method POST
Permission mdpDeviceSetupTemplateAtlas2 [Create]
{
Payload "setupTemplate": {
"templateName": "Template1",
"description": "This is a sample template",
"setupString": "<<device setup string in XML format, Base64-encoded>>"
}
}
Returns 201 Created - includes created object
400 Bad Request (setup template name is empty or not specified)
401 Unauthorized (Token invalid)
403 Forbidden (Access not allowed)
500 Internal Server Error
For "201 Created", the summary of the newly created template is returned in the response body.
{
"setupTemplate": {
"templateId": 1,
"templateName": "Template1",
"description": "This is a sample template",
"deviceType": "Mk7B"
}

Page 83
 MultiDrive Web API 2.8 User Guide

}
Note: When specifying the setup template to create, the revision can be 0 and/or the firmwareVersion
can be omitted.

9.9.5. Apply Device Setup Template

URL /fleetManagement/deviceSetupTemplates/{templateId}
/fleetManagement/deviceSetupTemplates/name/{templateName}
Method POST
Permission mdpSchedule [Modify]
{
Returns "devices" : [
{
"deviceId" : 12,
},
{
"deviceId" : 13,
},
{
"deviceId" : 14,
}, ...
]
}
Or
{
"devices" : [
{
"plantNumber" : "Meter at Level 1",
},
{
"plantNumber" : "Meter at Level 2",
},
{
"plantNumber" : "Meter at Level 3",
}, ...
]
}
Optional Call back notification is an optional element and when present will mean that a notification will be
Payload POSTed to the URI provided. If not requiring notification (using polling instead) then payload can be
Empty.

Payload

Additional parameter to be added to existing payload if callback is required:

{
"notification":
{
"uri": "http://someserver/notifyme"
},
"notifyStatus":
{
"status": [ "Complete", "No Jobs" ]
}
}
<scheme> can be "http", "https" or "topic".
Scheme Example Uri Descripion
http http://someserver/notifyme The callback will be posted to the HTTP URL
"http://someserver/notifyme"
https https://someserver/notifyme The callback will be posted to the HTTP URL
"https://someserver/notifyme"
topic topic://schedule-execution- Depending on the "callbackQueueType" setting in Callback Service,
callback the callback will be sent to a RabbitMQ queue or a Kafka topic
callbackQueueType Description
RabbitMQ The callback will be sent to the queue
"schedule-execution-callback" on the
configured RabbitMQ broker
Kafka The callback will be sent to the topic
"schedule-execution-callback" on the
configured Kafka broker

Page 84
 MultiDrive Web API 2.8 User Guide

Notification
URI passed in will be called back as a POST request.
Payload will be the same as Get Schedule Execution (/scheduling/executions/{executionId})
{
"execution": {
"executionId" : 14,
"scheduleId" : 12,
"startDate" : "2013-01-21T10:00:00",
"endDate" : "2013-01-21T12:00:00",
"jobsWithSuccess" : 3,
"jobsWithFailure" : 5,
"status" : "Complete",
"hasWarning" : "true",
"totalJobs" : 10,
"queuedJobs" : 2
}
}

Status can be Unknown, Queued, Running, Complete, No Jobs, Cancelled, Paused

Optional Dynamic Schedule Settings
Payload The following payload can optionally be specified to control some aspects of the dynamic schedule being
triggered.
{
"dynamicScheduleSettings": {
"duration": 86400, // seconds
"priority": "Medium",
"retryCount": 2,
"retryDelay": 300000, // milliseconds
"timeToLive": 96, // hours
"executionTime": "2016-05-16T16:50:00Z"
}
}

Description
Property Format Default Value Valid Values Description
duration Integer 86400 60 to 2147483647 Number of seconds the schedule is given before
failing.
priority String “Medium” "Very High", "High", Priority of the schedule relative to all other
"Medium", "Low", "Very MultiDrive schedules.
Low"
retryCount Integer 2 0 to 255 Maximum number of retries for the schedule.
retryDelay Integer 300000 60000 to 2147483647 Number of milliseconds to wait for the schedule
retries.
timeToLive Integer 96 1 to 32767 Number of hours the schedule execution status will
remain in the system.
executionTime ISO8601 Date - - Date and time when the schedule should run.
String If the specified time has passed when the request
reaches MultiDrive, the schedule will be executed
immediately.

Note: This property is currently not supported in

Supply Control API.
Prepayment API (Pass prepayment token to
meter).

Page 85
 MultiDrive Web API 2.8 User Guide

Chapter

Scheduling API

10
0
ter1
p
a
h
C

10.1 Schedules
10.1.1. List / Search Schedules
URL /scheduling/schedules
Method GET
Permission mdpSchedule [View]
Parameters Name Description Type Optional/ Valid values Default
Mandatory
name Filter by match in string Optional *
schedule name
status Filter by schedule string Optional Active, Manual *
status, whether the
schedule is activated
or needs to be
manually triggered
deviceId Filter by schedules Integer Optional
associated with this
device
scheduleIncludes- Limits inclusion of string Optional List of comma *
Features schedules which separated operations
perform. TOU, LOAD_PROFILE,
SETTIME, SETUP,
FIRMWARE
Returns 200 OK
401 Unauthorized (Token invalid)
403 Forbidden (Access not allowed)
500 Internal Server Error
{
"schedules" : [
{
"scheduleId" : 12,
"name" : "Important Read Schedule 1",
"lastExecution" :
{
"executionId" : 14,
"startDate" : "2013-01-21T10:00:00",
"endDate" : "2013-01-21T12:00:00",
"jobsWithSuccess" : 3,
"jobsWithFailure" : 5,
"status" : "Complete",
"hasWarning" : "true",
"connectAttempts" : 1
}
"nextRun" : "2013-01-22T10:00:00",
"status" : "Active",
"maxRetries" : 2
},
{
"scheduleId" : 14,
"name" : "Important Read Schedule 2",
"lastExecution" :
{
"executionId" : 0,
"startDate" : "",
"endDate" : "",

Page 86
 MultiDrive Web API 2.8 User Guide

"jobsWithSuccess" : 0,
"jobsWithFailure" : 0,
"status" : "",
"hasWarning" : "false",
"connectAttempts" : 0
}
"nextRun" : "",
"status" : "Manual Trigger",
"maxRetries" : 3
},
{
"scheduleId" : 15,
"name" : "Important Read Schedule 3",
"lastExecution" :
{
"executionId" : 14,
"startDate" : "2013-01-21T10:00:00",
"endDate" : "2013-01-21T12:00:00",
"jobsWithSuccess" : 3,
"jobsWithFailure" : 5,
"status" : "Failed",
"hasWarning" : "true",
"connectAttempts" : 2,
}
"nextRun" : "2013-01-22T10:00:00",
"status" : "Active",
"maxRetries" : 3
}
]
}

10.1.2. Get Schedule

URL /scheduling/schedules/{scheduleId}
/scheduling/schedules/name/{scheduleName}
Method GET
Permission mdpSchedule [View] or mdpScheduleRunNow[View]
Returns 200 OK
401 Unauthorized (Token invalid)
403 Forbidden (Access not allowed)
404 Not Found
500 Internal Server Error
{
"schedule" : {
"scheduleId" : 34,
"name" : "Important Read Schedule",
"recurrence" : "Everyday at 10:00"
"lastRun" : "2013-01-21T10:00:00",
"nextRun" : "2013-01-22T10:00:00",
"status" : "Active"
}
}

Description
Property Optional/ Format Description
Mandatory
scheduleId Mandatory Integer A unique identifier for the schedule.
name Mandatory Text A descriptive name for the schedule.
recurrence Optional Recurrence rule for schedules that are set to run automatically. Omitted for
schedules that are only triggered manually/via the API.
lastRun Optional ISO8601 The date and time the schedule was last run. Omitted if the schedule has
never been triggered.
nextRun Optional ISO8601 The next date and time the schedule is set to run (if the schedule is set to
run automatically).
status Mandatory Active, Active indicates the schedule is set to run automatically by the system.
Manual Manual indicates the schedule can only be triggered by an external request.

Page 87
 MultiDrive Web API 2.8 User Guide

10.2. Executions
10.2.1. Trigger Regular Schedule As Configured
URL /scheduling/schedules/{scheduleId}/executions
/scheduling/schedules/name/{scheduleName}/executions
Method POST
Permission mdpScheduleRunNow [View]
Description Triggers a schedule to run as configured in the system using the device groups it has been
configured for. This does not run the schedule on any user defined devices or groups.

Notification is an optional element and when present will mean that a notification will be POSTed
to the URI provided based on the notificationEvent requested. If not requiring notification (using
polling instead) then payload can be Empty.
Optional Call back notification is an optional element and when present will mean that a notification will be
Payload POSTed to the URI provided. If not requiring notification (using polling instead) then payload can be
Empty.

Payload
Additional parameter to be added to existing payload if callback is required:
{
"notification":
{
"uri": "http://someserver/notifyme"
},
"notifyStatus":
{
"status": [ "Complete", "No Jobs" ]
}
}
<scheme> can be "http", "https" or "topic".
Scheme Example Uri Descripion
http http://someserver/notifyme The callback will be posted to the HTTP URL
"http://someserver/notifyme"
https https://someserver/notifyme The callback will be posted to the HTTP URL
"https://someserver/notifyme"
topic topic://schedule-execution- Depending on the "callbackQueueType" setting in Callback
callback Service, the callback will be sent to a RabbitMQ queue or a
Kafka topic
callbackQueueType Description
RabbitMQ The callback will be sent to the
queue "schedule-execution-
callback" on the configured
RabbitMQ broker
Kafka The callback will be sent to the
topic "schedule-execution-
callback" on the configured Kafka
broker

Notification
URI passed in will be called back as a POST request.
Payload will be the same as Get Schedule Execution (/scheduling/executions/{executionId})
{
"execution": {
"executionId" : 14,
"scheduleId" : 12,
"startDate" : "2013-01-21T10:00:00",
"endDate" : "2013-01-21T12:00:00",
"jobsWithSuccess" : 3,
"jobsWithFailure" : 5,
"status" : "Complete",
"hasWarning" : "true",
"totalJobs" : 10,
"queuedJobs" : 2
}
}

Status can be Unknown, Queued, Running, Complete, No Jobs, Cancelled, Paused

Page 88
 MultiDrive Web API 2.8 User Guide

Returns 201 Created - includes location header containing the URN of the created execution
(/scheduling/executions/{executionId})
400 Bad Request (Payload is invalid or not well formed or device ids are be invalid)
401 Unauthorized (Token invalid)
403 Forbidden (Access not allowed)
404 Not Found
500 Internal Server Error

10.2.2. Trigger Adhoc Schedule for particular devices

URL /scheduling/schedules/{scheduleId}/executions
/scheduling/schedules/name/{scheduleName}/executions
Method POST
Permission mdpScheduleRunNow [View]
Description Triggers a schedule to run on a particular set of devices (from payload below) and ignores the
preconfigured device groups setup in the system.

Notification is an optional element and when present will mean that a notification will be POSTed
to the URI provided based on the notificationEvent requested. If not requiring notification (using
polling instead) then payload can be Empty.
Payload {
"devices" :
[
{
"deviceId" : 1,
},
{
"deviceId" : 2,
},...
]
}
or by device plant number

{
"devices" :
[
{
"plantNumber" : "Meter at Level 1",
},
{
"plantNumber" : "Meter at Level 2",
},...
]
}
Optional Call back notification is an optional element and when present will mean that a notification will be
Payload POSTed to the URI provided. If not requiring notification (using polling instead) then payload can
be Empty.

Payload
Additional parameter to be added to existing payload if callback is required:
{
"notification":
{
"uri": "http://someserver/notifyme"
},
"notifyStatus":
{
"status": [ "Complete", "No Jobs" ]
}
}
<scheme> can be "http", "https" or "topic".
Scheme Example Uri Descripion
http http://someserver/notifyme The callback will be posted to the HTTP URL
"http://someserver/notifyme"
https https://someserver/notifyme The callback will be posted to the HTTP URL
"https://someserver/notifyme"
topic topic://schedule-execution- Depending on the "callbackQueueType" setting in Callback
callback Service, the callback will be sent to a RabbitMQ queue or a
Kafka topic
callbackQueueType Description

Page 89
 MultiDrive Web API 2.8 User Guide

RabbitMQ The callback will be sent to the

queue "schedule-execution-
callback" on the configured
RabbitMQ broker
Kafka The callback will be sent to the
topic "schedule-execution-
callback" on the configured Kafka
broker

Notification
URI passed in will be called back as a POST request.
Payload will be the same as Get Schedule Execution (/scheduling/executions/{executionId})

{
"execution": {
"executionId" : 14,
"scheduleId" : 12,
"startDate" : "2013-01-21T10:00:00",
"endDate" : "2013-01-21T12:00:00",
"jobsWithSuccess" : 3,
"jobsWithFailure" : 5,
"status" : "Complete",
"hasWarning" : "true",
"totalJobs" : 10,
"queuedJobs" : 2
}
}

Status can be Unknown, Queued, Running, Complete, No Jobs, Cancel, Paused

Returns 201 Created - includes location header containing the URN of the created execution
(/scheduling/executions/{executionId})
400 Bad Request (Payload is invalid or not well formed or device ids are be invalid)
401 Unauthorized (Token invalid)
403 Forbidden (Access not allowed)
404 Not Found (Schedule id does not exist)
500 Internal Server Error

10.2.3. List Schedule Executions

URL /scheduling/executions
/scheduling/schedules/{scheduleID}/executions (filtered by schedule Id)
/scheduling/schedules/name/{scheduleName}/executions (filtered by schedule Name)
Method GET
Permission mdpScheduleExecutions [View]
Parameters Name Description Type Optional/ Valid Default
Mandatory values
hasWarning Filter by has warning status boolean Optional True, *
False
limit Maximum number of devices to return Integer Optional 0 - 5000 5000
status for in response
offset Offset in devices to start returning Integer Optional * 0
statuses for in response
Returns 200 OK
401 Unauthorized (Token invalid)
403 Forbidden (Access not allowed)
500 Internal Server Error
{
"executions" : [
{
"executionId" : 14,
"scheduleId" : 12,
"scheduleName" : "Important Read Schedule",
"startDate" : "2013-01-21T10:00:00",
"endDate" : "2013-01-21T12:00:00",
"jobsWithSuccess" : 3,
"jobsWithFailure" : 5,
"status" : "Complete",
"hasWarning" : "true",

Page 90
 MultiDrive Web API 2.8 User Guide

"totalJobs" : 9,
"queuedJobs" : 2,
"scheduleCreated" : "2013-01-21T09:00:00",
"scheduleLastRun" : "2013-01-21T09:30:00"
},
{
"executionId" : 15,
"scheduleId" : 54,
"scheduleName" : "Another Important Read Schedule",
"startDate" : "2013-01-21T10:00:00",
"endDate" : "2013-01-21T12:00:00",
"jobsWithSuccess" : 0,
"jobsWithFailure" : 5,
"status" : "Complete",
"hasWarning" : "true",
"totalJobs" : 5,
"queuedJobs" : 1,
"scheduleCreated" : "2013-01-21T09:00:00",
"scheduleLastRun" : "2013-01-21T09:31:00"
},
{
"executionId" : 83,
"scheduleId" : 54,
"scheduleName" : "Unimportant schedule...",
"startDate" : "2013-01-21T10:00:00",
"endDate" : "",
"jobsWithSuccess" : 0,
"jobsWithFailure" : 0,
"status" : "Pending",
"hasWarning" : "true",
"totalJobs" : 16,
"queuedJobs" : 7,
"scheduleCreated" : "2013-01-21T09:00:00",
"scheduleLastRun" : "2013-01-21T09:32:00"
},
...
]
}

Note: "scheduleCreated" and "scheduleLastRun" are only available for predefined schedules. These
fields are not applicable to ad-hoc schedule execution.
10.2.4. Get Schedule Execution
URL /scheduling/executions/{executionId}
Method GET
Permission mdpScheduleExecutions [View]
Returns 200 OK
401 Unauthorized (Token invalid)
403 Forbidden (Access not allowed)
404 Not Found
500 Internal Server Error
{
"execution": {
"executionId" : 14,
"scheduleId" : 12,
"startDate" : "2013-01-21T10:00:00",
"endDate" : "2013-01-21T12:00:00",
"jobsWithSuccess" : 3,
"jobsWithFailure" : 5,
"status" : "Complete",
"hasWarning" : "true",
"totalJobs" : 10,
"queuedJobs" : 2,
"scheduleCreated" : "2013-01-21T09:00:00",
"scheduleLastRun" : "2013-01-21T09:30:00"
}
}

Note: "scheduleCreated" and "scheduleLastRun" are only available for predefined schedules. These
fields are not applicable to ad-hoc schedule execution.

10.2.5. Cancel Schedule Execution

URL /scheduling/executions/{executionId}
Method DELETE

Page 91
 MultiDrive Web API 2.8 User Guide

Permission mdpScheduleRunNow [View]

Returns 200 OK
400 Bad Request (Excecution ID is not valid)
401 Unauthorized (Token invalid)
403 Forbidden (Access not allowed)
404 Not Found (Excecution ID not found)
500 Internal Error

10.3. Execution Jobs

10.3.1. Search for Schedule Execution Jobs
URL /scheduling/executionJobs
/scheduling/executions/{executionId}/executionJobs (filtered by execution)
/scheduling/schedules/{scheduleId}/executions/{executionID}/executionJobs (filtered by schedule id and
execution)
/scheduling/schedules/name/{scheduleName}/executions/{executionID}/executionJobs (filtered by
schedule name and execution)
Method GET
Permission mdpScheduleJobs [View]
Parameters Name Description Type Optional/ Valid values Default
Mandatory
status Filter by job status string Optional Queued, *
Running,
Complete,
Failed
plantNumber Filter by plant number string Optional *
deviceId Filter by device id Intege Optional *
r
siteCode Filter by site code string Optional *
limit Maximum number of devices to Intege Optional 0 - 5000 5000
return status for in response r
offset Offset in devices to start Intege Optional * 0
returning statuses for in r
response
Returns 200 OK
400 Bad Request (one of the parameters are not valid)
401 Unauthorized (Token invalid)
403 Forbidden (Access not allowed)
404 Not Found (Execution id not found or schedule not found)
500 Internal Server Error
{
"executionJobs" : [
{
"executionJobId" : 9875,
"executionId" : 125,
"deviceId" : 32,
"plantNumber" : "Device01",
"date" : "2013-01-21T10:00:00",
"commsServer" : "Communications Pool",
"status" : "Success",
"retries" : 1,
"retriesRemaining" : 0,
"hasWarning" : "true",
"lastError" : "Communications Device Failure: System error:Connection
refused, Unable to connect to 192.168.3.20 on port 10002",
},
{
"executionJobId" : 9876,
"executionId" : 125,
"deviceId" : 32,
"plantNumber" : "Device01",
"date" : "",
"commsServer" : "",
"status" : "Pending",
"retries" : 0,
"retriesRemaining" : 3,

Page 92
 MultiDrive Web API 2.8 User Guide

"hasWarning" : "false",
"lastError" : ""
},...
]
}

10.3.2. Get Schedule Execution Job

URL /scheduling/executionJobs/{executionJobId}
Method GET
Permission mdpScheduleJobs [View]
Returns 200 OK
401 Unauthorized (Token invalid)
403 Forbidden (Access not allowed)
404 Not Found
500 Internal Server Error
{
"executionJob": {
"executionJobId" : 9875,
"executionId" : 125,
"deviceId" : 32,
"plantNumber" : "ADEVICE",
"date" : "2013-01-21T10:00:00",
"status" : "Retry",
"retries" : 1,
"retriesRemaining" : 2
}
}

Status can be:

• Unknown
▪ Anything unhandled will report this status
• Queued
• Running
• Success
• Failed
▪ Incorporates Failed, Remote Fail, Fail Use Resend, Fail Use 2nd Comm and Fail Use
Mobile status from MultiDrive
• Error
• Expired
• Retry
• Cancelled
• Waiting
▪ Incorporates Listen and Ready To Send from MultiDrive
• PartialComplete

10.3.3. Get Schedule Execution Job Log

URL /scheduling/executionJobs/{executionJobId}/scheduleLog
Method GET
Permission mdpScheduleJobs [View]
Returns 200 OK
401 Unauthorized (Token invalid)
403 Forbidden (Access not allowed)
404 Not Found (No schedule log was stored)
500 Internal Server Error
{
"scheduleLog" : [
{
"entryDate" : "2013-01-25T09:56:09+0000",
"logEntry" : "Connecting"
},

Page 93
 MultiDrive Web API 2.8 User Guide

{
"entryDate" : "2013-01-25T09:57:09+0000",
"logEntry" : "Login"
},
{
"entryDate" : "2013-01-25T09:58:09+0000",
"logEntry" : "Timeout on meter "124000001""
},
{
"entryDate" : "2013-01-25T09:59:09+0000",
"logEntry" : "Rescheduled for 2013-01-24 18:20:41.432"
},...
]
}

10.3.4. Get Schedule Execution Job Log By Device

URL /scheduling/devices/{deviceId}/scheduleLog
/scheduling/devices/plantNumber/{plantNumber}/scheduleLog
Method GET
Permission mdpScheduleJobs [View]
Parameters Name Description Type Optional/ Valid values Default
Mandatory
startDate Inclusive start date/time of ISO8601 Mandatory must be When both
schedule logs to fetch for if endDate is earlier than startDate and
device specified endDate endDate are not
endDate Inclusive end date/time of ISO8601 Mandatory must be later specified, only
schedule logs to fetch for if startDate thanstartDate the latest
device is specified schedule log
entry (if
available) is
returned
Returns 200 OK
400 Bad Request (Invalid parameters)
401 Unauthorized (Token invalid)
403 Forbidden (Access not allowed)
404 Not Found (No schedule log was stored)
500 Internal Server Error
{
"scheduleLog" : [
{
"entryDate" : "2013-01-25T09:56:09+0000",
"logEntry" : "Connecting"
},
{
"entryDate" : "2013-01-25T09:57:09+0000",
"logEntry" : "Login"
},
{
"entryDate" : "2013-01-25T09:58:09+0000",
"logEntry" : "Timeout on meter "124000001""
},
{
"entryDate" : "2013-01-25T09:59:09+0000",
"logEntry" : "Rescheduled for 2013-01-24 18:20:41.432"
},...
]
}

10.3.5. Get Schedule Execution Communications Log

URL /scheduling/executionJobs/{executionJobId}/communicationsLog
Method GET
Permission mdpScheduleJobs [View]
Returns 200 OK
401 Unauthorized (Token invalid)
403 Forbidden (Access not allowed)
404 Not Found (No communications log was stored)
Page 94
 MultiDrive Web API 2.8 User Guide

500 Internal Server Error

{
"communicationsLog" : [
{
"entryDate" : "2013-01-25T09:56:09+0000",
"data" : "8F4BA6945A1F74C5791C45444D49",
"transmitted" : true,
},
{
"entryDate" : "2013-01-25T09:57:09+0000",
"data" : "8F4B2029EEC50C851CA6C06B",
"transmitted" : false,
},
{
"entryDate" : "2013-01-25T09:58:09+0000",
"data" : "8F4BBE80E62347CF2CFB45444D49 ",
"transmitted" : true,
},
{
"entryDate" : "2013-01-25T09:59:09+0000",
"data" : "8F066B60",
"transmitted" : false,
},...
]
}

Description
Property Format Optional/ Description
Mandatory
entryDate ISO8601 Mandatory Date and time data was sent/received,
data Text Mandatory Raw data sent/received.
transmitted Boolean Mandatory true - data was sent to the device
false - data was received from the device

10.3.6. Get Schedule Execution Communications Log By Device

URL /scheduling/devices/{deviceId}/communicationsLog
/scheduling/devices/plantNumber/{plantNumber}/communicationsLog
Method GET
Permission mdpScheduleJobs [View]
Parameters Name Description Type Optional/ Valid values Default
Mandatory
startDate Inclusive start date/time of ISO8601 Mandatory Must be When both
communications logs to if endDate is earlier than startDate and
fetch for device specified endDate endDate are not
endDate Inclusive end date/time of ISO8601 Mandatory Must be later specified, only
communications logs to if startDate thanstartDate the latest
fetch for device is specified communication
s log entry (if
available) is
returned
Returns 200 OK
400 Bad Request (Invalid parameters)
401 Unauthorized (Token invalid)
403 Forbidden (Access not allowed)
404 Not Found (No schedule log was stored)
500 Internal Server Error
{
"communicationsLog" : [
{
"entryDate" : "2013-01-25T09:56:09+0000",
"data" : "8F4BA6945A1F74C5791C45444D49",
"transmitted" : true,
},
{
"entryDate" : "2013-01-25T09:57:09+0000",
"data" : "8F4B2029EEC50C851CA6C06B",
"transmitted" : false,
},

Page 95
 MultiDrive Web API 2.8 User Guide

{
"entryDate" : "2013-01-25T09:58:09+0000",
"data" : "8F4BBE80E62347CF2CFB45444D49 ",
"transmitted" : true,
},
{
"entryDate" : "2013-01-25T09:59:09+0000",
"data" : "8F066B60",
"transmitted" : false,
},...
]
}

Description
Property Format Optional/ Description
Mandatory
entryDate ISO8601 Mandatory Date and time data was sent/received,
data Text Mandatory Raw data sent/received.
transmitted Boolean Mandatory true - data was sent to the device
false - data was received from the device

Page 96
 MultiDrive Web API 2.8 User Guide

Chapter

11.1. Top-up prepayment credit

ter1
p
a
h
C

11
Prepayment API

URL /prepayment/credit/{deviceId}
/prepayment/credit/plantNumber/{plantNumber}
Method POST
Permission mdpPrepaymentTopup [View]
Payload {
"prepaymentCredit" :
{
"dollarValue" : 1.00,
},
}
Optional Call back notification is an optional element and when present will mean that a notification will be
Payload POSTed to the URI provided. If not requiring notification (using polling instead) then payload can be
Empty.

Payload
Additional parameter to be added to existing payload if callback is required:
{
"notification":
{
"uri": "http://someserver/notifyme"
},
"notifyStatus":
{
"status": [ "Complete", "No Jobs" ]
}
}
<scheme> can be "http", "https" or "topic".
Scheme Example Uri Descripion
http http://someserver/notifyme The callback will be posted to the HTTP URL
"http://someserver/notifyme"
https https://someserver/notifyme The callback will be posted to the HTTP URL
"https://someserver/notifyme"
topic topic://schedule-execution- Depending on the "callbackQueueType" setting in Callback
callback Service, the callback will be sent to a RabbitMQ queue or a Kafka
topic
callbackQueueType Description
RabbitMQ The callback will be sent to the
queue "schedule-execution-callback"
on the configured RabbitMQ broker
Kafka The callback will be sent to the topic
"schedule-execution-callback" on the
configured Kafka broker

Notification
URI passed in will be called back as a POST request.
Payload will be the same as Get Schedule Execution (/scheduling/executions/{executionId})

{
"execution": {
"executionId" : 14,

Page 97
 MultiDrive Web API 2.8 User Guide

"scheduleId" : 12,
"startDate" : "2013-01-21T10:00:00",
"endDate" : "2013-01-21T12:00:00",
"jobsWithSuccess" : 3,
"jobsWithFailure" : 5,
"status" : "Complete",
"hasWarning" : "true",
"totalJobs" : 10,
"queuedJobs" : 2
}
}

Status can be Unknown, Queued, Running, Complete, No Jobs, Cancelled, Paused

Optional Dynamic Schedule Settings
Payload The following payload can optionally be specified to control some aspects of the dynamic schedule
being triggered.
{
"dynamicScheduleSettings": {
"duration": 86400, // seconds
"priority": "Medium",
"retryCount": 2,
"retryDelay": 300000, // milliseconds
"timeToLive": 96, // hours
"executionTime": "2016-05-16T16:50:00Z"
}
}
Returns 202 Accepted - includes location header to schedule execution history to determine if it has been sent
to the meter /scheduling/executions/{executionId}, This/scheduling/executions/{executionId} endpoint
will return a 200 OK with a representation of the commands status, or a when the device has
successfully received the command.
401 Unauthorized (Token invalid)
403 Forbidden (Access not allowed)
404 Not Found (Device Id, plant number or device group id does not exist)
500 Internal Error

Description
Property Format Default Value Valid Values Description
duration Integer 86400 60 to 2147483647 Number of seconds the schedule is given before
failing.
priority String “Medium” "Very High", "High", Priority of the schedule relative to all other
"Medium", "Low", "Very MultiDrive schedules.
Low"
retryCount Integer 2 0 to 255 Maximum number of retries for the schedule.
retryDelay Integer 300000 60000 to 2147483647 Number of milliseconds to wait for the schedule
retries.
timeToLive Integer 96 1 to 32767 Number of hours the schedule execution status will
remain in the system.
executionTime ISO8601 Date - - Date and time when the schedule should run.
String If the specified time has passed when the request
reaches MultiDrive, the schedule will be executed
immediately.

Note: This property is currently not supported in

Supply Control API.
Prepayment API (Pass prepayment token to
meter).

11.2. Request prepayment information for a device (with EDMI Atlas

Proprietary Prepayment System)
URL /prepayment/status/{deviceId}
/prepayment/status/plantNumber/{plantNumber}
Method POST
Permission mdpPrepaymentInformation [View]
Optional Call back notification is an optional element and when present will mean that a notification will be
Payload POSTed to the URI provided. If not requiring notification (using polling instead) then payload can be
Empty.

Page 98
 MultiDrive Web API 2.8 User Guide

Payload
Additional parameter to be added to existing payload if callback is required:
{
"notification":
{
"uri": "http://someserver/notifyme"
},
"notifyStatus":
{
"status": [ "Complete", "No Jobs" ]
}
}
<scheme> can be "http", "https" or "topic".
Scheme Example Uri Descripion
http http://someserver/notifyme The callback will be posted to the HTTP URL
"http://someserver/notifyme"
https https://someserver/notifyme The callback will be posted to the HTTP URL
"https://someserver/notifyme"
topic topic://schedule-execution- Depending on the "callbackQueueType" setting in Callback
callback Service, the callback will be sent to a RabbitMQ queue or a
Kafka topic
callbackQueueType Description
RabbitMQ The callback will be sent to the
queue "schedule-execution-
callback" on the configured
RabbitMQ broker
Kafka The callback will be sent to the
topic "schedule-execution-
callback" on the configured Kafka
broker

Notification
URI passed in will be called back as a POST request.
Payload will be the same as Get Schedule Execution (/scheduling/executions/{executionId})

{
"execution": {
"executionId" : 14,
"scheduleId" : 12,
"startDate" : "2013-01-21T10:00:00",
"endDate" : "2013-01-21T12:00:00",
"jobsWithSuccess" : 3,
"jobsWithFailure" : 5,
"status" : "Complete",
"hasWarning" : "true",
"totalJobs" : 10,
"queuedJobs" : 2
}
}

Status can be Unknown, Queued, Running, Complete, No Jobs, Cancelled, Paused

Optional Dynamic Schedule Settings
Payload The following payload can optionally be specified to control some aspects of the dynamic schedule
being triggered.
{
"dynamicScheduleSettings": {
"duration": 86400, // seconds
"priority": "Medium",
"retryCount": 2,
"retryDelay": 300000, // milliseconds
"timeToLive": 96, // hours
"executionTime": "2016-05-16T16:50:00Z"
}
}
Returns 202 Accepted - includes location header to schedule execution history to determine if it has been
sent to the meter /scheduling/executions/{executionId},
This/scheduling/executions/{executionId} endpoint will return a 200 OK with a representation of
the commands status, or a when the device has successfully received the command.
400 Bad Request (function not supported by the device type)
401 Unauthorized (Token invalid)
403 Forbidden (Access not allowed)
404 Not Found (Device Id, plant number or device group id does not exist)

Page 99
 MultiDrive Web API 2.8 User Guide

500 Internal Error

Description
Property Format Default Value Valid Values Description
duration Integer 86400 60 to 2147483647 Number of seconds the schedule is given before
failing.
priority String “Medium” "Very High", "High", Priority of the schedule relative to all other
"Medium", "Low", MultiDrive schedules.
"Very Low"
retryCount Integer 2 0 to 255 Maximum number of retries for the schedule.
retryDelay Integer 300000 60000 to 2147483647 Number of milliseconds to wait for the schedule
retries.
timeToLive Integer 96 1 to 32767 Number of hours the schedule execution status
will remain in the system.
executionTime ISO8601 Date - - Date and time when the schedule should run.
String If the specified time has passed when the request
reaches MultiDrive, the schedule will be
executed immediately.

Note: This property is currently not supported in

Supply Control API.
Prepayment API (Pass prepayment token to
meter).

11.3. Get prepayment information for a device (with EDMI Atlas Proprietary
Prepayment System)
URL /prepayment/status/{deviceId}
/prepayment/status/plantNumber/{plantNumber}
Method GET
Permission mdpPrepaymentInformation [View]
Returns 200 OK
401 Unauthorized (Token invalid)
403 Forbidden (Access not allowed)
404 Not Found (Device Id, plant number or device group id does not exist)
500 Internal Server Error
{
"prepaymentStatus" :
{
"readingDate" : "2013-01-21T10:00:00",
"prepaymentMode" : "credit",
"currency" : "dollars",
"creditType" : "",
"normalCredit" : 1.00,
"emergencyCredit" : 5.00,
"fuelDebt" : 1.00,
"nonFuelDebt" : 1.33,
"totalCreditAdded" : 10.00,
"miscInfo" : "",
},
}

11.4. Write misc. prepayment info to meter

URL /prepayment/misc/{deviceId}
/prepayment/misc/plantNumber/{plantNumber}
Method POST
Permission mdpPrepaymentTopup [View]
Payload Note: All items in payload are optional
{
"creditNotification" : //Only available for Atlas 1 series meter for the moment
{
"creditBalance" : 5600, //$56.00, Integer with two implied decimal places
"remainingDays" : 10 //credit remaining days
}

Page 100
 MultiDrive Web API 2.8 User Guide

}
Property Format Default Valid Values Description
Value
creditBalance Integer None -9223372036854775808 Depending on the meter firmware
to implementations, this is either the new
9223372036854775807 value for credit balance or the
adjustment to be applied to the
existing credit balance.

It should be an integer, with the last

two digits representing the cents value.
remainingDays Integer None -9223372036854775808 Depending on the meter firmware
to implementations, this is either the new
9223372036854775807 value for remaining days or the
adjustment to be applied to the
existing remaining days.
Optional Call back notification is an optional element and when present will mean that a notification will be
Payload POSTed to the URI provided. If not requiring notification (using polling instead) then payload can be
Empty.

Payload
Additional parameter to be added to existing payload if callback is required:
{
"notification":
{
"uri": "http://someserver/notifyme"
},
"notifyStatus":
{
"status": [ "Complete", "No Jobs" ]
}
}
<scheme> can be "http", "https" or "topic".
Scheme Example Uri Descripion
http http://someserver/notifyme The callback will be posted to the HTTP URL
"http://someserver/notifyme"
https https://someserver/notifyme The callback will be posted to the HTTP URL
"https://someserver/notifyme"
topic topic://schedule-execution- Depending on the "callbackQueueType" setting in Callback
callback Service, the callback will be sent to a RabbitMQ queue or a Kafka
topic
callbackQueueType Description
RabbitMQ The callback will be sent to the queue
"schedule-execution-callback" on the
configured RabbitMQ broker
Kafka The callback will be sent to the topic
"schedule-execution-callback" on the
configured Kafka broker

Notification
URI passed in will be called back as a POST request.
Payload will be the same as Get Schedule Execution (/scheduling/executions/{executionId})
{
"execution": {
"executionId" : 14,
"scheduleId" : 12,
"startDate" : "2013-01-21T10:00:00",
"endDate" : "2013-01-21T12:00:00",
"jobsWithSuccess" : 3,
"jobsWithFailure" : 5,
"status" : "Complete",
"hasWarning" : "true",
"totalJobs" : 10,
"queuedJobs" : 2
}
}

Status can be Unknown, Queued, Running, Complete, No Jobs, Cancelled, Paused

Page 101
 MultiDrive Web API 2.8 User Guide

Optional Dynamic Schedule Settings

Payload The following payload can optionally be specified to control some aspects of the dynamic schedule
being triggered.
{
"dynamicScheduleSettings": {
"duration": 86400, // seconds
"priority": "Medium",
"retryCount": 2,
"retryDelay": 300000, // milliseconds
"timeToLive": 96, // hours
"executionTime": "2016-05-16T16:50:00Z"
}
}
Returns 202 Accepted - includes location header to schedule execution history to determine if it has been sent
to the meter /scheduling/executions/{executionId}, This/scheduling/executions/{executionId} endpoint
will return a 200 OK with a representation of the commands status, or a when the device has
successfully received the command.
400 Bad Request (payload is empty, payload is invalid, or function not supported by the device type)
401 Unauthorized (Token invalid)
403 Forbidden (Access not allowed)
404 Not Found (Device Id, plant number does not exist)
500 Internal Error
Description
Property Format Default Value Valid Values Description
duration Integer 86400 60 to 2147483647 Number of seconds the schedule is given before
failing.
priority String “Medium” "Very High", "High", Priority of the schedule relative to all other
"Medium", "Low", "Very MultiDrive schedules.
Low"
retryCount Integer 2 0 to 255 Maximum number of retries for the schedule.
retryDelay Integer 300000 60000 to 2147483647 Number of milliseconds to wait for the schedule
retries.
timeToLive Integer 96 1 to 32767 Number of hours the schedule execution status will
remain in the system.
executionTime ISO8601 Date - - Date and time when the schedule should run.
String If the specified time has passed when the request
reaches MultiDrive, the schedule will be executed
immediately.

Note: This property is currently not supported in

Supply Control API.
Prepayment API (Pass prepayment token to
meter).

11.5. Pass prepayment token to meter

URL /prepayment/token/{deviceId}
/prepayment/token/plantNumber/{plantNumber}
Method POST
Permission mdpPrepaymentTopup [View]
Payload {
"prepaymentTokens" :
[
{
"token" : "azxjv0asjtoaj9ghaond",
},
{
"token" : "yxp4anywyxnqdg9hajln",
},
{
"token" : "exhwngfuexd5eg5xzgc5",
}
]
}

Page 102
 MultiDrive Web API 2.8 User Guide

Optional Call back notification is an optional element and when present will mean that a notification will be
Payload POSTed to the URI provided. If not requiring notification (using polling instead) then payload can be
Empty.

Payload
Additional parameter to be added to existing payload if callback is required:
{
"notification":
{
"uri": "http://someserver/notifyme"
},
"notifyStatus":
{
"status": [ "Complete", "No Jobs" ]
}
}
<scheme> can be "http", "https" or "topic".
Scheme Example Uri Descripion
http http://someserver/notifyme The callback will be posted to the HTTP URL
"http://someserver/notifyme"
https https://someserver/notifyme The callback will be posted to the HTTP URL
"https://someserver/notifyme"
topic topic://schedule-execution- Depending on the "callbackQueueType" setting in Callback
callback Service, the callback will be sent to a RabbitMQ queue or a Kafka
topic
callbackQueueType Description
RabbitMQ The callback will be sent to the queue
"schedule-execution-callback" on the
configured RabbitMQ broker
Kafka The callback will be sent to the topic
"schedule-execution-callback" on the
configured Kafka broker

Notification
URI passed in will be called back as a POST request.
Payload will be the same as Get Schedule Execution (/scheduling/executions/{executionId})
{
"execution": {
"executionId" : 14,
"scheduleId" : 12,
"startDate" : "2013-01-21T10:00:00",
"endDate" : "2013-01-21T12:00:00",
"jobsWithSuccess" : 3,
"jobsWithFailure" : 5,
"status" : "Complete",
"hasWarning" : "true",
"totalJobs" : 10,
"queuedJobs" : 2
}
}

Status can be Unknown, Queued, Running, Complete, No Jobs, Cancelled, Paused

Optional Dynamic Schedule Settings

Payload The following payload can optionally be specified to control some aspects of the dynamic schedule
being triggered.
{
"dynamicScheduleSettings": {
"duration": 86400, // seconds
"priority": "Medium",
"retryCount": 2,
"retryDelay": 300000, // milliseconds
"timeToLive": 96 // hours
}
}
Returns 202 Accepted - includes location header to schedule execution history to determine if it has been sent
to the meter /scheduling/executions/{executionId}, This/scheduling/executions/{executionId} endpoint
will return a 200 OK with a representation of the commands status, or a when the device has
successfully received the command.
401 Unauthorized (Token invalid)
403 Forbidden (Access not allowed)

Page 103
 MultiDrive Web API 2.8 User Guide

404 Not Found (Device Id, plant number or device group id does not exist)
500 Internal Error

Description
Property Format Default Value Valid Values Description
duration Integer 86400 60 to 2147483647 Number of seconds the schedule is given before
failing.
priority String “Medium” "Very High", "High", Priority of the schedule relative to all other
"Medium", "Low", "Very MultiDrive schedules.
Low"
retryCount Integer 2 0 to 255 Maximum number of retries for the schedule.
retryDelay Integer 300000 60000 to 2147483647 Number of milliseconds to wait for the schedule
retries.
timeToLive Integer 96 1 to 32767 Number of hours the schedule execution status will
remain in the system.

11.6. Generate UTRN token

URL /prepayment/utrn
Method POST
Permission mdpPrepaymentTopup [View]
Payload {
"utrnParameters" :
{
"dollarValue" : 1.00,
"authenticationKey" : "00000000000000000000000000000001",
"masterKey" : "00000000000000000000000000000001",
"originatorCounter" : 1,
},
}
Returns 200 OK
400 Bad Request (Request is not properly formed)
401 Unauthorized (Token invalid)
403 Forbidden (Access not allowed)
500 Internal Server Error

{
"utrn" :
{
"token" : "00004398128020693249"
},
}

11.7. Get token transfer history of 3rd-party vending system

URL • To get the tokens transferred in a previously triggered schedule
/prepayment/vending/executions/{executionId}/tokens
• To get the latest tokens transferred for the specified device
/prepayment/vending/devices/{deviceId}/tokens
/prepayment/vending/devices/plantNumber/{plantNumber}/tokens
Method GET
Permission mdpPrepaymentTopup [View]
Returns 200 OK
400 Bad Request (Device Id or execution id is invalid)
401 Unauthorized (Token invalid)
403 Forbidden (Access not allowed)
404 Not Found (Device Id, plant number or execution id does not exist)
500 Internal Server Error

{
"tokenTransfer": {

Page 104
 MultiDrive Web API 2.8 User Guide

"executionId": 125,
"transactionDateTime": "2018-01-21T10:00:00",
"devices": [{
"deviceId": 32,
"plantNumber": "Device01",
"tokens": [{
"tokenSequence": 1,
"token": "azxjv0asjtoaj9ghaond",
"tokenStatus": ["Accepted"],
"creditBalance": null
},{
"tokenSequence": 2,
"token": "yxp4anywyxnqdg9hajln",
"tokenStatus": ["Overflow_credit_balance"],
"creditBalance": 3.00
}]
}, ... ]
}
}

Description
Property Format Description
executionId Integer Id of schedule execution through which the token
transfers are transacted
transactionDateTime ISO8601 The date and time at which the token transfers are
transacted
devices An array of devices for which token transfers are
transacted
deviceId Integer ID of the device
plantNumber String Plant number of the device
tokens An array of tokens transferred for the device
tokenSequence Integer The sequence number of the token transferred
token String The token transferred
tokenStatus Array of String The statuses of the token transfer.

Valid values:
• Authentication_failed,
• Validation_failed,
• Token_older_than_oldest_token_in_meter,
• Token_used_in_meter,
• Meter_key_expired,
• Accepted,
• Token_has_Error,
• First_KCT_entered,
• Second_KCT_entered,
• Overflow_credit_balance

creditBalance Double The new credit balance after the token transfer (as
dollar and cent)

11.8. Request prepayment information of a device

URL /prepayment/info/{deviceId}
/prepayment/info/plantNumber/{plantNumber}
Method POST
Permission mdpPrepaymentInformation [View]
Optional Call back notification is an optional element and when present will mean that a notification will be
Payload POSTed to the URI provided. If not requiring notification (using polling instead) then payload can be
Empty.

Payload
Additional parameter to be added to existing payload if callback is required:
{
"notification":
{
"uri": "http://someserver/notifyme"
},
"notifyStatus":
{
"status": [ "Complete", "No Jobs" ]

Page 105
 MultiDrive Web API 2.8 User Guide

}
}
<scheme> can be "http", "https" or "topic".
Scheme Example Uri Descripion
http http://someserver/notifyme The callback will be posted to the HTTP URL
"http://someserver/notifyme"
https https://someserver/notifyme The callback will be posted to the HTTP URL
"https://someserver/notifyme"
topic topic://schedule-execution- Depending on the "callbackQueueType" setting in Callback
callback Service, the callback will be sent to a RabbitMQ queue or a
Kafka topic
callbackQueueType Description
RabbitMQ The callback will be sent to the
queue "schedule-execution-
callback" on the configured
RabbitMQ broker
Kafka The callback will be sent to the
topic "schedule-execution-
callback" on the configured Kafka
broker

Notification
URI passed in will be called back as a POST request.
Payload will be the same as Get Schedule Execution (/scheduling/executions/{executionId})

{
"execution": {
"executionId" : 14,
"scheduleId" : 12,
"startDate" : "2013-01-21T10:00:00",
"endDate" : "2013-01-21T12:00:00",
"jobsWithSuccess" : 3,
"jobsWithFailure" : 5,
"status" : "Complete",
"hasWarning" : "true",
"totalJobs" : 10,
"queuedJobs" : 2
}
}

Status can be Unknown, Queued, Running, Complete, No Jobs, Cancelled, Paused

Optional Dynamic Schedule Settings
Payload The following payload can optionally be specified to control some aspects of the dynamic schedule
being triggered.
{
"dynamicScheduleSettings": {
"duration": 86400, // seconds
"priority": "Medium",
"retryCount": 2,
"retryDelay": 300000, // milliseconds
"timeToLive": 96, // hours
"executionTime": "2016-05-16T16:50:00Z"
}
}
Returns 202 Accepted - includes location header with the endpoint "/scheduling/executions/{executionId}"
to determine if schedule has been sent to the meter. This endpoint will return a 200 OK with a
representation of the commands status when the device has successfully received the command.
400 Bad Request (function not supported by the device type)
401 Unauthorized (Token invalid)
403 Forbidden (Access not allowed)
404 Not Found (Device Id, plant number or device group id does not exist)
500 Internal Error

Description

Property Format Default Value Valid Values Description

duration Integer 86400 60 to 2147483647 Number of seconds the schedule is given before
failing.

Page 106
 MultiDrive Web API 2.8 User Guide

priority String “Medium” "Very High", "High", Priority of the schedule relative to all other
"Medium", "Low", MultiDrive schedules.
"Very Low"
retryCount Integer 2 0 to 255 Maximum number of retries for the schedule.
retryDelay Integer 300000 60000 to 2147483647 Number of milliseconds to wait for the schedule
retries.
timeToLive Integer 96 1 to 32767 Number of hours the schedule execution status
will remain in the system.
executionTime ISO8601 Date - - Date and time when the schedule should run.
String If the specified time has passed when the request
reaches MultiDrive, the schedule will be
executed immediately.

Note: This property is currently not supported in

Supply Control API.
Prepayment API (Pass prepayment token to
meter).

11.9. Get prepayment information of a device

URL /prepayment/info/{deviceId}
/prepayment/info/plantNumber/{plantNumber}
Method GET
Permission mdpPrepaymentInformation [View]
Returns 200 OK
401 Unauthorized (Token invalid)
403 Forbidden (Access not allowed)
404 Not Found (Device Id, plant number or device group id does not exist)
500 Internal Server Error
{
"prepaymentInfo": {
"prepaymentMode": "Prepaid",
"stsKeyRevisionNumber": 456,
"stsSupplyGroupCode": "1234567890",
"tariffIndex": 1,
"remainingCredit": 12.3,
"creditType": "TokenCredit",
"priority": 1,
"warningThreshold": 10.3,
"creditLimit": 5.3,
"creditConfigurations": [ "RequiresVisual", "RequiresConfirmation",
"RequiresCreditPaidBack" ],
"creditStatus": "Selectable",
"presetCreditAmount": 12.3,
"availableThreshold": 10.3,
"period": "2016-04-28T12:30:00.000+0000",
"lastReadDate": "2016-04-28T12:30:00.000+0000",
"lastTopUpTime": "2016-04-28T11:30:00.000+0000",
"lastTopUpAmount": 10.0,
"lastTopUpToken: "8F4BA6945A1F74C5791C45444D49",
"totalUsedAmount": 50.6,
"totalCredit": 40.6
}
}

Description

Property Format Valid Values Description

priority Integer 0 (credit is not activated), 1 - 255 (1: highest priority, Credit activation priority.
255: lowest priority)
creditStatus Text Enabled, Selectable, Selected, InUse, Exhausted State of Credit Object in
the meter

Page 107
 MultiDrive Web API 2.8 User Guide

prepaymentMode Text Postpaid, Prepaid The current Mode the

meter is in
creditConfigurations Array of Text RequiresVisual (Requires visual indication), Describes the credit
RequiresConfirmation (Requires confirmation before it behaviour
can be selected/invoked),
RequiresCreditPaidBack (Requires the credit amount to
be paid back),
Resettable (The credit is resettable),
CanReceiveToken (Able to receive credit amounts from
tokens)

creditType Text TokenCredit, ReservedCredit, EmergencyCredit, The type of credit the

TimeBasedCredit, ConsumptionBasedCredit meter accepts

stsKeyRevisionNumber Integer STS Key Revision Number

stsSupplyGroupCode Text STS Supply Group Code

tariffIndex Integer The current tariff index

Available credit in the
remainingCredit Float meter
Minimum credit value
warningThreshold Float before a warning is
triggered for low credit.
Threshold for the lowest
creditLimit Float value before the Credit
Status can be set to
"Exhausted".
Initial amount of credit
presetCreditAmount Float that
is available for the Credit
object
A threshold value related
availableThreshold Float to the Account object
available_credit.
The time at which the
period ISO8601 current credit amount is
set automatically to the
preset credit amount.
Last date and time when
lastReadDate ISO8601 the meter was read
Last date and time where a
lastTopUpTime ISO8601 successful top-up were
made
Last amount value
lastTopUpAmount Float successfully added
Last successful token used
lastTopUpToken Text to top-up the meter
Total amount value used
totalUsedAmount Float
Total credit
totalCredit Float

11.10. Set prepayment mode for a device

URL /prepayment/mode/{deviceId}
/prepayment/mode/plantNumber/{plantNumber}
Method POST
Permission mdpPrepaymentInformation [Modify]
Parameters Name Description Type Optional/Mandatory Valid Default
values
prepaymentMode The new string Mandatory Postpaid,
mode of Prepaid
prepayment
to set for
the device

Page 108
 MultiDrive Web API 2.8 User Guide

Optional Call back notification is an optional element and when present will mean that a notification will be
Payload POSTed to the URI provided. If not requiring notification (using polling instead) then payload can be
Empty.

Payload
Additional parameter to be added to existing payload if callback is required:
{
"notification":
{
"uri": "http://someserver/notifyme"
},
"notifyStatus":
{
"status": [ "Complete", "No Jobs" ]
}
}
<scheme> can be "http", "https" or "topic".
Scheme Example Uri Descripion
http http://someserver/notifyme The callback will be posted to the HTTP URL
"http://someserver/notifyme"
https https://someserver/notifyme The callback will be posted to the HTTP URL
"https://someserver/notifyme"
topic topic://schedule-execution- Depending on the "callbackQueueType" setting in Callback
callback Service, the callback will be sent to a RabbitMQ queue or a
Kafka topic
callbackQueueType Description
RabbitMQ The callback will be sent to the
queue "schedule-execution-
callback" on the configured
RabbitMQ broker
Kafka The callback will be sent to the topic
"schedule-execution-callback" on
the configured Kafka broker

Notification
URI passed in will be called back as a POST request.
Payload will be the same as Get Schedule Execution (/scheduling/executions/{executionId})

{
"execution": {
"executionId" : 14,
"scheduleId" : 12,
"startDate" : "2013-01-21T10:00:00",
"endDate" : "2013-01-21T12:00:00",
"jobsWithSuccess" : 3,
"jobsWithFailure" : 5,
"status" : "Complete",
"hasWarning" : "true",
"totalJobs" : 10,
"queuedJobs" : 2
}
}

Status can be Unknown, Queued, Running, Complete, No Jobs, Cancelled, Paused

Optional Dynamic Schedule Settings
Payload The following payload can optionally be specified to control some aspects of the dynamic schedule
being triggered.
{
"dynamicScheduleSettings": {
"duration": 86400, // seconds
"priority": "Medium",
"retryCount": 2,
"retryDelay": 300000, // milliseconds
"timeToLive": 96, // hours
"executionTime": "2016-05-16T16:50:00Z"
}
}
Returns 202 Accepted - includes location header with the endpoint "/scheduling/executions/{executionId}" to
determine if schedule has been sent to the meter. This endpoint will return a 200 OK with a
representation of the commands status when the device has successfully received the command.
400 Bad Request (function not supported by the device type)
401 Unauthorized (Token invalid)

Page 109
 MultiDrive Web API 2.8 User Guide

403 Forbidden (Access not allowed)

404 Not Found (Device Id, plant number or device group id does not exist)
500 Internal Error

Description

Property Format Default Value Valid Values Description

duration Integer 86400 60 to 2147483647 Number of seconds the schedule is given before
failing.
priority String “Medium” "Very High", "High", Priority of the schedule relative to all other
"Medium", "Low", MultiDrive schedules.
"Very Low"
retryCount Integer 2 0 to 255 Maximum number of retries for the schedule.
retryDelay Integer 300000 60000 to 2147483647 Number of milliseconds to wait for the schedule
retries.
timeToLive Integer 96 1 to 32767 Number of hours the schedule execution status
will remain in the system.
executionTime ISO8601 Date - - Date and time when the schedule should run.
String If the specified time has passed when the request
reaches MultiDrive, the schedule will be
executed immediately.

Note: This property is currently not supported in

Supply Control API.
Prepayment API (Pass prepayment token to
meter).

11.11. Pass prepayment token to multiple meters

URL /prepayment/token/devices
Method POST
Permission mdpPrepaymentTopup [View]
Payload by device id
{
"devices": [
{
"deviceId": 12,
"prepaymentTokens" : [
{
"token" : "azxjv0asjtoaj9ghaond",
},
{
"token" : "yxp4anywyxnqdg9hajln",
},
{
"token" : "exhwngfuexd5eg5xzgc5",
}
]
},
...
]
}
or by device plant number
{
"devices": [
{
"plantNumber" : "Meter at Level 1",
"prepaymentTokens" : [
{
"token" : "azxjv0asjtoaj9ghaond",
},
{
"token" : "yxp4anywyxnqdg9hajln",
},
{
"token" : "exhwngfuexd5eg5xzgc5",
}
]

Page 110
 MultiDrive Web API 2.8 User Guide

},
...
]
}
Optional Call back notification is an optional element and when present will mean that a notification will be
Payload POSTed to the URI provided. If not requiring notification (using polling instead) then payload can be
Empty.

Payload
Additional parameter to be added to existing payload if callback is required:
{
"notification":
{
"uri": "http://someserver/notifyme"
},
"notifyStatus":
{
"status": [ "Complete", "No Jobs" ]
}
}
<scheme> can be "http", "https" or "topic".
Scheme Example Uri Descripion
http http://someserver/notifyme The callback will be posted to the HTTP URL
"http://someserver/notifyme"
https https://someserver/notifyme The callback will be posted to the HTTP URL
"https://someserver/notifyme"
topic topic://schedule-execution- Depending on the "callbackQueueType" setting in Callback
callback Service, the callback will be sent to a RabbitMQ queue or a Kafka
topic
callbackQueueType Description
RabbitMQ The callback will be sent to the queue
"schedule-execution-callback" on the
configured RabbitMQ broker
Kafka The callback will be sent to the topic
"schedule-execution-callback" on the
configured Kafka broker

Notification
URI passed in will be called back as a POST request.
Payload will be the same as Get Schedule Execution (/scheduling/executions/{executionId})

{
"execution": {
"executionId" : 14,
"scheduleId" : 12,
"startDate" : "2013-01-21T10:00:00",
"endDate" : "2013-01-21T12:00:00",
"jobsWithSuccess" : 3,
"jobsWithFailure" : 5,
"status" : "Complete",
"hasWarning" : "true",
"totalJobs" : 10,
"queuedJobs" : 2
}
}

Status can be Unknown, Queued, Running, Complete, No Jobs, Cancel, Paused

Optional Dynamic Schedule Settings

Payload The following payload can optionally be specified to control some aspects of the dynamic schedule
being triggered.
{
"dynamicScheduleSettings": {
"duration": 86400, // seconds
"priority": "Medium",
"retryCount": 2,
"retryDelay": 300000, // milliseconds
"timeToLive": 96 // hours
}
}

Page 111
 MultiDrive Web API 2.8 User Guide

Returns 202 Accepted - includes location header to schedule execution history to determine if it has been sent
to the meter /scheduling/executions/{executionId}, This/scheduling/executions/{executionId} endpoint
will return a 200 OK with a representation of the commands status, or a when the device has
successfully received the command.
401 Unauthorized (Token invalid)
403 Forbidden (Access not allowed)
404 Not Found (Device Id, plant number or device group id does not exist)
500 Internal Error

Description

Property Format Default Value Valid Values Description

duration Integer 86400 60 to 2147483647 Number of seconds the schedule is given before
failing.
priority String “Medium” "Very High", "High", Priority of the schedule relative to all other
"Medium", "Low", "Very MultiDrive schedules.
Low"
retryCount Integer 2 0 to 255 Maximum number of retries for the schedule.
retryDelay Integer 300000 60000 to 2147483647 Number of milliseconds to wait for the schedule
retries.
timeToLive Integer 96 1 to 32767 Number of hours the schedule execution status will
remain in the system.

11.12. Request prepayment information of multiple devices

URL /prepayment/info/devices
Method POST
Permission mdpPrepaymentInformation [View]
Payload by device id
{
"devices" : [
{
"deviceId" : 12,
},
{
"deviceId" : 13,
},
{
"deviceId" : 14,
}, ...
]
}

or by device plant number

{
"devices" : [
{
"plantNumber" : "Meter at Level 1",
},
{
"plantNumber" : "Meter at Level 2",
},
{
"plantNumber" : "Meter at Level 3",
}, ...
]
}
Optional Call back notification is an optional element and when present will mean that a notification will be
Payload POSTed to the URI provided. If not requiring notification (using polling instead) then payload can be
Empty.

Payload
Additional parameter to be added to existing payload if callback is required:

Page 112
 MultiDrive Web API 2.8 User Guide

{
"notification":
{
"uri": "http://someserver/notifyme"
},
"notifyStatus":
{
"status": [ "Complete", "No Jobs" ]
}
}
<scheme> can be "http", "https" or "topic".
Scheme Example Uri Descripion
http http://someserver/notifyme The callback will be posted to the HTTP URL
"http://someserver/notifyme"
https https://someserver/notifyme The callback will be posted to the HTTP URL
"https://someserver/notifyme"
topic topic://schedule-execution- Depending on the "callbackQueueType" setting in Callback
callback Service, the callback will be sent to a RabbitMQ queue or a
Kafka topic
callbackQueueType Description
RabbitMQ The callback will be sent to the
queue "schedule-execution-
callback" on the configured
RabbitMQ broker
Kafka The callback will be sent to the
topic "schedule-execution-
callback" on the configured Kafka
broker

Notification
URI passed in will be called back as a POST request.
Payload will be the same as Get Schedule Execution (/scheduling/executions/{executionId})

{
"execution": {
"executionId" : 14,
"scheduleId" : 12,
"startDate" : "2013-01-21T10:00:00",
"endDate" : "2013-01-21T12:00:00",
"jobsWithSuccess" : 3,
"jobsWithFailure" : 5,
"status" : "Complete",
"hasWarning" : "true",
"totalJobs" : 10,
"queuedJobs" : 2
}
}

Status can be Unknown, Queued, Running, Complete, No Jobs, Cancel, Paused

Optional Dynamic Schedule Settings
Payload The following payload can optionally be specified to control some aspects of the dynamic schedule
being triggered.
{
"dynamicScheduleSettings": {
"duration": 86400, // seconds
"priority": "Medium",
"retryCount": 2,
"retryDelay": 300000, // milliseconds
"timeToLive": 96, // hours
"executionTime": "2016-05-16T16:50:00Z"
}
}
Returns 202 Accepted - includes location header to schedule execution history to determine if it has been
sent to the meter /scheduling/executions/{executionId},
This/scheduling/executions/{executionId} endpoint will return a 200 OK with a representation of
the commands status, or a when the device has successfully received the command.
400 Bad Request (function not supported by the device type)
401 Unauthorized (Token invalid)
403 Forbidden (Access not allowed)
404 Not Found (Device Id, plant number or device group id does not exist)
500 Internal Error

Page 113
 MultiDrive Web API 2.8 User Guide

Description

Property Format Default Value Valid Values Description

duration Integer 86400 60 to 2147483647 Number of seconds the schedule is given before
failing.
priority String “Medium” "Very High", "High", Priority of the schedule relative to all other
"Medium", "Low", MultiDrive schedules.
"Very Low"
retryCount Integer 2 0 to 255 Maximum number of retries for the schedule.
retryDelay Integer 300000 60000 to 2147483647 Number of milliseconds to wait for the schedule
retries.
timeToLive Integer 96 1 to 32767 Number of hours the schedule execution status
will remain in the system.
executionTime ISO8601 Date - - Date and time when the schedule should run.
String If the specified time has passed when the request
reaches MultiDrive, the schedule will be
executed immediately.

Note: This property is currently not supported in

Supply Control API.
Prepayment API (Pass prepayment token to
meter).

11.13. Get prepayment information of multiple devices

URL /prepayment/info/devices
Method GET
Permission mdpPrepaymentInformation [View]
Payload by device id
{
"devices" : [
{
"deviceId" : 12,
},
{
"deviceId" : 13,
},
{
"deviceId" : 14,
}, ...
]
}

or by device plant number

{
"devices" : [
{
"plantNumber" : "Meter at Level 1",
},
{
"plantNumber" : "Meter at Level 2",
},
{
"plantNumber" : "Meter at Level 3",
}, ...
]
}
Returns 200 OK
401 Unauthorized (Token invalid)
403 Forbidden (Access not allowed)
404 Not Found (Device Id, plant number or device group id does not exist)
500 Internal Server Error

Page 114
 MultiDrive Web API 2.8 User Guide

{
"prepaymentInfo": [
{
"deviceId" : 14,
"plantNumber" : "Meter at Level 3",
"prepaymentMode": "Prepaid",
"stsKeyRevisionNumber": 456,
"stsSupplyGroupCode": "1234567890",
"tariffIndex": 1,
"remainingCredit": 12.3,
"creditType": "TokenCredit",
"priority": 1,
"warningThreshold": 10.3,
"creditLimit": 5.3,
"creditConfigurations": [ "RequiresVisual", "RequiresConfirmation",
"RequiresCreditPaidBack" ],
"creditStatus": "Selectable",
"presetCreditAmount": 12.3,
"availableThreshold": 10.3,
"period": "2016-04-28T12:30:00.000+0000",
"lastReadDate": "2016-04-28T12:30:00.000+0000",
"lastTopUpTime": "2016-04-28T11:30:00.000+0000",
"lastTopUpAmount": 10.0,
"lastTopUpToken: "8F4BA6945A1F74C5791C45444D49",
"totalUsedAmount": 50.6,
"totalCredit": 40.6
},
...
]
}

Description

Property Format Valid Values Description

deviceId Integer Device Id
plantNumber Text Device plant number
prepaymentMode Text Postpaid, Prepaid The current Mode the
meter is in
stsKeyRevisionNumber Integer STS Key Revision Number
stsSupplyGroupCode Text STS Supply Group Code
tariffIndex Integer The current tariff index
remainingCredit Float Available credit in the
meter
creditType Text TokenCredit, ReservedCredit, EmergencyCredit, The type of credit the
TimeBasedCredit, ConsumptionBasedCredit meter accepts
priority Integer 0 (credit is not activated), 1 - 255 (1: highest priority, Credit activation priority.
255: lowest priority)
warningThreshold Float Minimum credit value
before a warning is
triggered for low credit.
creditLimit Float Threshold for the lowest
value before the Credit
Status can be set to
"Exhausted".
creditConfigurations Array of Text RequiresVisual (Requires visual indication), Describes the credit
RequiresConfirmation (Requires confirmation before it behaviour
can be selected/invoked),
RequiresCreditPaidBack (Requires the credit amount to
be paid back),
Resettable (The credit is resettable),
CanReceiveToken (Able to receive credit amounts from
tokens)
State of Credit Object in
creditStatus Text Enabled, Selectable, Selected, InUse, Exhausted the meter

presetCreditAmount Float Initial amount of credit

that
is available for the Credit
object

Page 115
 MultiDrive Web API 2.8 User Guide

availableThreshold Float A threshold value related

to the Account object
available_credit.

period ISO8601 The time at which the

current credit amount is
set automatically to the
preset credit amount.
Last date and time when
lastReadDate ISO8601 the meter was read
Last date and time where a
lastTopUpTime ISO8601 successful top-up were
made
Last amount value
lastTopUpAmount Float successfully added
Last successful token used
lastTopUpToken Text to top-up the meter
Total amount value used
totalUsedAmount Float
Total credit
totalCredit Float

Chapter

12.1. Read Diagnostic Register

2
ter1
p
a
h
C

12
Diagnostic API

URL /diagnostic/readRegister/{deviceId}
/diagnostic/readRegister/plantNumber/{plantNumber}
/diagnostic/readRegister/deviceGroup/{deviceGroupId}
/diagnostic/readRegister/deviceGroup/name/{deviceGroupName}
Method POST
Permission mdpDiagnosticRegister [View]

Page 116
 MultiDrive Web API 2.8 User Guide

Payload
{
"diagnosticRegisters" : [
{
"registerNumber" : "F002",
"type" : "String"
},...
]
}

Valid Data Types -

• Byte,
• Word,
• DWORD,
• ShortInt,
• SmallInt,
• LongInt,
• Int64,
• Float,
• Double,
• Extended,
• Boolean,
• String,
• Date,
• Time,
• DateTime,
• Blob,
• Format,
• ErrorInfo,
• NULL,
• Address,
• Currency,
• WavHarm,
• WideString

Data Value Formats

• String, WideString always as a normal string.
• Word, DWORD, ShortInt, SmallInt, LongInt, Int64 as normal numbers
• Float, Double as normal numbers with decimal places
• Date, Time, DateTime always in ISO8601
• Blob always as a hex string

Optional Payload Call back notification is an optional element and when present will mean that a notification
will be POSTed to the URI provided. If not requiring notification (using polling instead) then
payload can be Empty.

Payload
Additional parameter to be added to existing payload if callback is required:
{
"notification":
{
"uri": "http://someserver/notifyme"
},
"notifyStatus":
{
"status": [ "Complete", "No Jobs" ]
}
}
<scheme> can be "http", "https" or "topic".
Scheme Example Uri Descripion
http http://someserver/notifyme The callback will be posted to the HTTP URL
"http://someserver/notifyme"
https https://someserver/notifyme The callback will be posted to the HTTP URL
"https://someserver/notifyme"
topic topic://schedule-execution- Depending on the "callbackQueueType" setting in
callback Callback Service, the callback will be sent to a
RabbitMQ queue or a Kafka topic

Page 117
 MultiDrive Web API 2.8 User Guide

callbackQueueType Description
RabbitMQ The callback will be sent to
the queue "schedule-
execution-callback" on the
configured RabbitMQ
broker
Kafka The callback will be sent to
the topic "schedule-
execution-callback" on the
configured Kafka broker

Notification
URI passed in will be called back as a POST request.
Payload will be the same as Get Schedule Execution (/scheduling/executions/{executionId})

{
"execution": {
"executionId" : 14,
"scheduleId" : 12,
"startDate" : "2013-01-21T10:00:00",
"endDate" : "2013-01-21T12:00:00",
"jobsWithSuccess" : 3,
"jobsWithFailure" : 5,
"status" : "Complete",
"hasWarning" : "true",
"totalJobs" : 10,
"queuedJobs" : 2
}
}

Status can be Unknown, Queued, Running, Complete, No Jobs, Cancelled, Paused

Optional Payload Dynamic Schedule Settings

The following payload can optionally be specified to control some aspects of the dynamic
schedule being triggered.
{
"dynamicScheduleSettings": {
"duration": 86400, // seconds
"priority": "Medium",
"retryCount": 2,
"retryDelay": 300000, // milliseconds
"timeToLive": 96, // hours
"executionTime": "2016-05-16T16:50:00Z"
}
}
Returns 202 Accepted - includes location header to schedule execution history to determine if it has
been sent to the meter /scheduling/executions/{executionId},
This/scheduling/executions/{executionId} endpoint will return a 200 OK with a representation
of the commands status, or a when the device has successfully received the command.
401 Unauthorized (Token invalid)
403 Forbidden (Access not allowed)
404 Not Found (Device Id does not exist)
409 Conflict (Exceeds maximum concurrent requests)
Note: Requesting register read/write on a large number of devices may result in
length processing time. Multiple instances of the similar request adds even more
load to the server. To avoid the server resources being held up, the number of
concurrent requests for register read/write are limited to 2.
500 Internal Server Error (Exceeds maximum number of registers to read)
Important Notes There is a maximum limit in the total number of registers to read
For SQL Server, the limit is 2500.
For Oracle, the limit is 1000.
For /diagnostic/readRegister/deviceGroup/*, Total Number of Registers to Read = Number of
Registers specified in Payload x Number of Devices in Device Group.

Description
Property Format Default Value Valid Values Description

Page 118
 MultiDrive Web API 2.8 User Guide

duration Integer 86400 60 to 2147483647 Number of seconds the schedule is given before
failing.
priority String “Medium” "Very High", "High", Priority of the schedule relative to all other
"Medium", "Low", "Very MultiDrive schedules.
Low"
retryCount Integer 2 0 to 255 Maximum number of retries for the schedule.
retryDelay Integer 300000 60000 to 2147483647 Number of milliseconds to wait for the schedule
retries.
timeToLive Integer 96 1 to 32767 Number of hours the schedule execution status will
remain in the system.
executionTime ISO8601 Date - - Date and time when the schedule should run.
String If the specified time has passed when the request
reaches MultiDrive, the schedule will be executed
immediately.

Note: This property is currently not supported in

Supply Control API.
Prepayment API (Pass prepayment token to
meter).

12.2. Get Diagnostic Register Value read out

URL /diagnostic/registerValues/{executionId}/
/diagnostic/registerValues/{executionId}/{deviceId}
/diagnostic/registerValues/{executionId}/plantNumber/{plantNumber}
Method GET
Permission mdpDiagnosticRegister [View]
Parameters Name Description Type Optional/Mandatory Valid values Default
register Meter register to string Optional *
return data for in HEX
(ie. F002)
Returns 200 OK
400 Bad Request (register is invalid)
401 Unauthorized (Token invalid)
403 Forbidden (Access not allowed)
404 Not Found (execution job id or register does not exist)
500 Internal Server Error

AKA Diagnostic Registers. Note diagnostic registers are not supported by iE2 at this time.

MDX Export Example

<diagnosticDataSets>
<diagnosticDataSet>
<deviceId>1</deviceId>
<plantNumber>meter1</plantNumber>
<recordDateTime>2012-06-10T12:30:00.000+0000</recordDateTime>
<diagnosticValues>
<diagnosticValue>
<registerNumber>F061</registerNumber>
<type>DateTime</type>
<value>2012-06-10T10:30:00.000+0000</value>
</diagnosticValue>
<diagnosticValue>
<registerNumber>2020</registerNumber>
<type>Float</type>
<value>123</value>
</diagnosticValue>
</diagnosticValues>
</diagnosticDataSet>
</diagnosticDataSets>

Full diagnostic value data details

{
"diagnosticDataSets": [{
"deviceId": 1,
"plantNumber": "meter1",

Page 119
 MultiDrive Web API 2.8 User Guide

"recordDateTime":"2012-06-10T12:30:00.000+0000",
"diagnosticValues":[{
"registerNumber":"F061",
"type":"DateTime",
"value":"2012-06-10T10:30:00.000+0000"
},{
"registerNumber":"2020",
"type":"Float",
"value":"123"
}, ...]
}]
}

23.2.1. Description
Property iE2 Import Format Description
Usage
diagnosticDataSet Unused -
deviceId Unused Integer Device Id
plantNumber Unused Text The manufacturer serial number of the
device
recordDateTime Unused ISO8601 The timestamp when the values were
recorded
diagnosticValues Unused - Values for a single diagnostic register
registerNumber Unused Text The register number being recorded
type Unused See data The datatype from this register
types
below
value Unused Text The value from this register

23.2.2. Data Types

Type Format
Byte Number
Word Number
DWORD Number
ShortInt Number
SmallInt Number
LongInt Number
Int64 Number
Float Number (with decimal places)
Double Number (with decimal places)
Boolean Boolean
String String
WideString String
Date ISO8601
Time ISO8601
DateTime ISO8601
Blob Hex string

12.3. Write Diagnostic Register

URL /diagnostic/writeRegister/{deviceId}
/diagnostic/writeRegister/plantNumber/{plantNumber}
/diagnostic/writeRegister/deviceGroup/{deviceGroupId}
/diagnostic/writeRegister/deviceGroup/name/{deviceGroupName}
Method POST
Permission mdpDiagnosticRegister [Create]
Payload {
"diagnosticRegisters" : [
{
"registerNumber" : "F002",
"type" : "String",
"value" : "Hello",
},...
]
}
Valid Date Types -
• Byte,
Page 120
 MultiDrive Web API 2.8 User Guide

• Word,
• DWORD,
• ShortInt,
• SmallInt,
• LongInt,
• Int64,
• Float,
• Double,
• Extended,
• Boolean,
• String,
• Date,
• Time,
• DateTime,
• Blob,
• Format,
• ErrorInfo,
• NULL,
• Address,
• Currency,
• WavHarm,
• WideString

Data Value Formats

• String, WideString always as a normal string.
• Word, DWORD, ShortInt, SmallInt, LongInt, Int64 as normal numbers
• Float, Double as normal numbers with decimal places
• Date, Time, DateTime always in ISO8601
• Blob always as a hex string

Optional Payload Call back notification is an optional element and when present will mean that a notification will
be POSTed to the URI provided. If not requiring notification (using polling instead) then payload
can be Empty.
Payload
Additional parameter to be added to existing payload if callback is required:
{
"notification":
{
"uri": "http://someserver/notifyme"
},
"notifyStatus":
{
"status": [ "Complete", "No Jobs" ]
}
}
<scheme> can be "http", "https" or "topic".
Scheme Example Uri Descripion
http http://someserver/notifyme The callback will be posted to the HTTP URL
"http://someserver/notifyme"
https https://someserver/notifyme The callback will be posted to the HTTP URL
"https://someserver/notifyme"
topic topic://schedule-execution- Depending on the "callbackQueueType" setting in Callback Service,
callback the callback will be sent to a RabbitMQ queue or a Kafka topic
callbackQueueType Description
RabbitMQ The callback will be sent to the queue
"schedule-execution-callback" on the
configured RabbitMQ broker
Kafka The callback will be sent to the topic
"schedule-execution-callback" on the
configured Kafka broker

Notification
URI passed in will be called back as a POST request.
Payload will be the same as Get Schedule Execution (/scheduling/executions/{executionId})

Page 121
 MultiDrive Web API 2.8 User Guide

{
"execution": {
"executionId" : 14,
"scheduleId" : 12,
"startDate" : "2013-01-21T10:00:00",
"endDate" : "2013-01-21T12:00:00",
"jobsWithSuccess" : 3,
"jobsWithFailure" : 5,
"status" : "Complete",
"hasWarning" : "true",
"totalJobs" : 10,
"queuedJobs" : 2
}
}
Status can be Unknown, Queued, Running, Complete, No Jobs, Cancelled, Paused

Optional Payload Dynamic Schedule Settings

The following payload can optionally be specified to control some aspects of the dynamic
schedule being triggered.
{
"dynamicScheduleSettings": {
"duration": 86400, // seconds
"priority": "Medium",
"retryCount": 2,
"retryDelay": 300000, // milliseconds
"timeToLive": 96, // hours
"executionTime": "2016-05-16T16:50:00Z"
}
}
Returns 202 Accepted - includes location header to schedule execution history to determine if it has
been sent to the meter /scheduling/executions/{executionId},
This/scheduling/executions/{executionId} endpoint will return a 200 OK with a representation of
the commands status, or a when the device has successfully received the command.
401 Unauthorized (Token invalid)
403 Forbidden (Access not allowed)
404 Not Found (Device Id does not exist)
409 Conflict (Exceeds maximum concurrent requests)
Note: Requesting register read/write on a large number of devices may result in
length processing time. Multiple instances of the similar request adds even more load
to the server. To avoid the server resources being held up, the number of concurrent
requests for register read/write are limited to 2.
500 Internal Server Error (Exceeds maximum number of registers to write)
Important Notes There is a maximum limit in the total number of registers to write
For SQL Server, the limit is 2500.
For Oracle, the limit is 1000.
For /diagnostic/writeRegister/deviceGroup/*, Total Number of Registers to Write = Number of
Registers specified in Payload x Number of Devices in Device Group.

Description
Property Format Default Value Valid Values Description
duration Integer 86400 60 to 2147483647 Number of seconds the schedule is given before
failing.
priority String “Medium” "Very High", "High", Priority of the schedule relative to all other
"Medium", "Low", "Very MultiDrive schedules.
Low"
retryCount Integer 2 0 to 255 Maximum number of retries for the schedule.
retryDelay Integer 300000 60000 to 2147483647 Number of milliseconds to wait for the schedule
retries.
timeToLive Integer 96 1 to 32767 Number of hours the schedule execution status will
remain in the system.
executionTime ISO8601 Date - - Date and time when the schedule should run.
String If the specified time has passed when the request
reaches MultiDrive, the schedule will be executed
immediately.

Note: This property is currently not supported in

Supply Control API.
Prepayment API (Pass prepayment token to
meter).

Page 122
MultiDrive Web API 2.8 User Guide

Page 123
 MultiDrive Web API 2.8 User Guide

Chapter

13
Notification API
3
ter1
p
a
h
C

13.1. Set Notification Callback Address

URL /notifications/callback
Method POST
Permissio mdpAlarmNotification [View]
n
Payload {
"notification": {
"uri": "<scheme>://someserver/notifyme/1"
}
}
Property Type Description
uri string The URI to which the callback will be directed.
When set to an empty string, the callback is disabled.
<scheme> can be "http", "https" or "topic"

Scheme Example Uri Descripion

http http://someserver/notifyalarm The callback will be posted to the HTTP URL
"http://someserver/notifyalarm"
https https://someserver/notifyalarm The callback will be posted to the HTTP URL
"https://someserver/notifyalarm"
topic topic://alarm-callback Depending on the "callbackQueueType" setting in Callback Service,
the callback will be sent to a RabbitMQ queue or a Kafka topic
callbackQueueType Description
RabbitMQ The callback will be sent to the queue
"alarm-callback" on the configured
RabbitMQ broker
Kafka The callback will be sent to the topic
"alarm-callback" on the configured
Kafka broker
Returns 200 OK
400 Bad Request (Payload is not provided or invalid)
401 Unauthorized (Token invalid)
403 Forbidden (Access not allowed)
500 Internal Error
Callback The notifications currently supported are the device alarms.
When a device alarms, the following payload will be sent to the notification uri specified in the request
payload.
{
notifications: [{
"alarmId": 1,
"eventTypeName": "Meter Alarms",
"eventTypeId": 20,
"eventId": 800,
"eventValue": "0",
"deviceId": 556,
"startTime": "2016-04-21T00:11:57.110",
"duration" : 0.123,
"description": "The CPU temperature is equal to or greater than 85 degrees
C.",
"finished" : "Yes",
"acknowledged" : "No",
"notificationId": 101
},
{
"alarmId": 2,

Page 124
 MultiDrive Web API 2.8 User Guide

"eventTypeName": "Genius Alarms",

"eventTypeId": 18,
"eventId": 800,
"eventValue": "0",
"deviceId": 559,
"startTime": "2016-04-21T18:40:33.567",
"duration" : 10.5,
"description": "The estimated battery power is equal to or less than
2000mAh.",
"finished" : "No",
"acknowledged" : "No",
"notificationId": 101
}]
}

Property Type Description

alarmId integer Unique identifier of the notification
eventTypeName String
Type name of the event notified. Possible types are:System, Com Server,
System Operations, Device, Meter Finish, Integration Operations, Schedules,
Genius Alarms, Atlas Alarms, Meter Alarms, Unused/Reserved
eventTypeId Integer
The actual type identifier of the event notified.
eventId Integer
The identifier of the event notified
deviceId Integer
The id of device involved in the event
startTime
Date/Time The time at which the event starts
string in
ISO8601

duration Float Duration of the event

description String Explanation of the event
finished Boolean Indicates whether the event has finished
acknowledged Boolean Indicates whether the event has been acknowledged

notificationId Integer The notification identifier to be used when acknowledging the alarm. Note:
Multiple alarms may contain the same notification identifier.

13.2. Acknowledge Notifications in System

URL /notifications/acknowledge
Method POST
Permission mdpAlarmNotification [Modify]
Payload {
"acknowledgement": {
"remark": "A note of the acknowledgement",
"notifications": [
{
"notificationId": 1
},
{
"notificationId": 2
}, ...
]
}
}
Note: Up to a maximum of 1000 notifications can be acknowledged at a time.
Property Type Mandatory Description
remark string Yes A short remark about the acknowledgement
notifications Yes A collection of notification IDs.
notificationId Integer Yes The ID of the notification to acknowledge.
Returns 200 OK
400 Bad Request (Payload is not valid, or more than 1000 Notification IDs are specified in the payload)
401 Unauthorized (Token invalid)
403 Forbidden (Access not allowed)
404 Not Found (One or more Notification IDs are not found in the system)
Note: Notification IDs that are found in the system will still be acknowledged in this case.

Page 125
 MultiDrive Web API 2.8 User Guide

Chapter

500 Internal Error

14.1. Request an authentication token for the system

4
ter1
p
a
h
C

14
System API

URL /system/authToken
Method POST
Payload None
Permission NA
Authentication This call requires basic HTTP authentication credentials to be set
Returns 200 OK
400 Bad Request (Request is not properly formed)
401 Unauthorized (Username/password is invalid)
403 Forbidden (Username has been disabled)
500 Internal Server Error
{
"authToken" : {
"token" : "a0a8b777cd73739e99d000dfff",
}
}

Basic HTTP authentication is done using the username/password of the user as current stored in MultiDrive. This also
provides the access capabilities for the user.
All users must first request an access token from the System Management API. That token then must be passed in with all
API calls.

The token is entered as part of the HTTP Authorization header:

Authorization: AuthToken “Token = <token>”
Example: Authorization: AuthToken “Token = c1a0d63e-18b6-46df-bbda-5cb0282cecdb”

All API calls will validate the token in the system before allowing any request.
• Any request for which the token does not exist (or has been deleted) will respond with a “HTTP 401 Unauthorised”
response.
• Any request for which the token indicates that the user is not allowed to access will respond with a “HTTP 403
Forbidden” response.

Auto-purging of expired tokens

Authentication tokens that have expired for more than N minutes may be auto-deleted when a new token is being
requested. Both N and the maximum number of tokens deleted each round, X, can be controlled by the settings
purgeTokensExpiredMoreThanMinutes and maxTokensToDeletePerPurge, respectively in web.config.

14.2. Delete Authentication Token

URL /system/authToken/{token}
Method DELETE
Authentication This call requires basic HTTP authentication credentials to be set

Page 126
 MultiDrive Web API 2.8 User Guide

Returns 200 OK
400 Bad Request (Request is incorrectly formed)
401 Unauthorized (username/password is invalid)
403 Forbidden (Username is disabled)
404 Not Found (Token not found)
500 Internal Server Error

14.3. Decrypt Device Password

URL /system/decryption
Method POST
Permission mdpDevice [View]
Parameters Name Description Type Optional/Mandatory Valid values Default
password Password to be decrypted String Mandatory *
serialNumber Serial number of device String Mandatory
Returns 200 OK
401 Unauthorized (username/password is invalid)
500 Internal Server Error
{
"decryption" : {
"output" : "209111304",
}
}

Page 127
 MultiDrive Web API 2.8 User Guide

Chapter

15.1 Suppress Load Profile downloads on MDDCS

URL /mddcs/loadProfile/suppress
MDDCS Configurations API
5
ter1
p
a
h
C

15
Method POST
Permission mdpDevice [Modify]
Payload {
"start": "2017-05-21",
"end": "2017-06-21",
"devices": [
{
"deviceId": 12,
},
{
"deviceId": 13,
},
{
"deviceId": 14,
}
]
}

Property Type Optional/Mandatory Description

start Date Mandatory Date starting from which the load profile
downloads should be suppressed.
end Date Optional The last date on which the load profile
downloads should be suppressed.
devices Array of
deviceId
deviceId Integer Mandatory Id of device for which the load profile
downloads should be suppressed.

Or

{
"start": "2017-05-21",
"end": "2017-06-21",
"devices": [
{
"plantNumber": "Meter1",
},
{
"plantNumber": "Meter2",
},
{
"plantNumber": "Meter3",
}
]
}

Property Type Optional/Mandatory Description

start Date Mandatory Date starting from which the load
profile downloads should be
suppressed.
end Date Optional The last date on which the load profile
downloads should be suppressed.
devices Array of
plantNumber

Page 128
 MultiDrive Web API 2.8 User Guide

plantNumber String Mandatory Plant number of device for which the

load profile downloads should be
suppressed.

Optional Non-async call back notification is an optional element. When present in the request, a notification will
Payload be POSTed to the URI provided when the processing of the request is complete.

Payload
Additional parameter to be added to existing payload if non-async callback is required:
{
"notification":
{
"uri": "<scheme>://someserver/notifyme"
}
}
<scheme> can be "http", "https" or "topic".
Scheme Example Uri Descripion
http http://someserver/notifyme The callback will be posted to the HTTP URL
"http://someserver/notifyme"
https https://someserver/notifyme The callback will be posted to the HTTP URL
"https://someserver/notifyme"
topic topic://non-async-callback Depending on the "callbackQueueType" setting in Callback
Service, the callback will be sent to a RabbitMQ queue or a Kafka
topic
callbackQueueType Description
RabbitMQ The callback will be sent to the queue
"non-async-callback" on the
configured RabbitMQ broker
Kafka The callback will be sent to the topic
"non-async-callback" on the
configured Kafka broker

Notification
URI passed in will be called back as a POST request with the following payload format
{
"callback":
{
"requestUri": "http://server/api/xxxx/1",
"callbackId": "653a20db-adbb-41c9-a09b-371798fbc058",
"statusCode": "404",
"message": "Device Id (17) not found",
"errorCode": "XXXXX-002"
}
}

Property Description
requestUri The URI of the original Web API request
callbackId The unique identifier used to correlate the current callback to the
original Web API request
statusCode The response HTTP status code of the Web API request
message (Optional) Response message from the Web API
errorCode (Optional) Error code from the Web API, when statusCode is not 2XX.

or when "UseExecutionPayloadInCallbacks" = true in web.config

{
"execution": {
"executionId": "653a20db-adbb-41c9-a09b-371798fbc058",
"jobsWithSuccess": 1,
"status": "Complete"
}
}
Returns 200 OK
400 Bad Request (Request is not properly formed, or end date is not later than start date)
401 Unauthorized (Token invalid)
403 Forbidden (Access not allowed)
500 Internal Server Error (MDDCS not reachable, or suppress start/end dates not set correctly for one or
more devices)

Page 129
 MultiDrive Web API 2.8 User Guide

15.2 Re-enable Load Profile downloads on MDDCS

URL /mddcs/loadProfile/unsuppress
Method POST
Permission mdpDevice [Modify]
Payload {
"start": "2017-05-21",
"devices": [
{
"deviceId": 12,
},
{
"deviceId": 13,
},
{
"deviceId": 14,
}
]
}

Property Type Optional/Mandatory Description

start Date Mandatory Date starting from which the load profile
downloads should be suppressed.
devices Array of
deviceId
deviceId Integer Mandatory Id of device for which the load profile
downloads should be resumed.

Or

{
"start": "2017-05-21",
"devices": [
{
"plantNumber": "Meter1",
},
{
"plantNumber": "Meter2",
},
{
"plantNumber": "Meter3",
}
]
}

Property Type Optional/Mandatory Description

start Date Mandatory Date starting from which the load
profile downloads should be
suppressed.
devices Array of
plantNumber
plantNumber String Mandatory Plant number of device for which the
load profile downloads should be
resumed.

Optional Non-async call back notification is an optional element. When present in the request, a notification will
Payload be POSTed to the URI provided when the processing of the request is complete.

Payload
Additional parameter to be added to existing payload if non-async callback is required:
{
"notification":
{
"uri": "<scheme>://someserver/notifyme"
}
}
<scheme> can be "http", "https" or "topic".
Scheme Example Uri Descripion
http http://someserver/notifyme The callback will be posted to the HTTP URL
"http://someserver/notifyme"

Page 130
 MultiDrive Web API 2.8 User Guide

https https://someserver/notifyme The callback will be posted to the HTTP URL

"https://someserver/notifyme"
topic topic://non-async-callback Depending on the "callbackQueueType" setting in Callback
Service, the callback will be sent to a RabbitMQ queue or a Kafka
topic
callbackQueueType Description
RabbitMQ The callback will be sent to the queue
"non-async-callback" on the
configured RabbitMQ broker
Kafka The callback will be sent to the topic
"non-async-callback" on the
configured Kafka broker

Notification
URI passed in will be called back as a POST request with the following payload format
{
"callback":
{
"requestUri": "http://server/api/xxxx/1",
"callbackId": "653a20db-adbb-41c9-a09b-371798fbc058",
"statusCode": "404",
"message": "Device Id (17) not found",
"errorCode": "XXXXX-002"
}
}

Property Description
requestUri The URI of the original Web API request
callbackId The unique identifier used to correlate the current callback to the
original Web API request
statusCode The response HTTP status code of the Web API request
message (Optional) Response message from the Web API
errorCode (Optional) Error code from the Web API, when statusCode is not 2XX.

or when "UseExecutionPayloadInCallbacks" = true in web.config

{
"execution": {
"executionId": "653a20db-adbb-41c9-a09b-371798fbc058",
"jobsWithSuccess": 1,
"status": "Complete"
}
}
Returns 200 OK
400 Bad Request (Request is not properly formed, or end date is not later than start date)
401 Unauthorized (Token invalid)
403 Forbidden (Access not allowed)
500 Internal Server Error (MDDCS not reachable, or unsuppress start/end dates not set correctly for one
or more devices)

15.3 Request Load Profile downloads

URL /mddcs/loadProfile/download
Method POST
Permission mdpProfileData [View]
Payload {
"start": "2017-05-21",
"end": "2017-06-21",
"devices": [
{
"deviceId": 12,
},
{
"deviceId": 13,
},
{
"deviceId": 14,
}
]
}

Page 131
 MultiDrive Web API 2.8 User Guide

Property Type Optional/Mandatory Description

Start Date Mandatory Date starting to download missing load
profile data.
end Date Mandatory The last date to download missing load
profile data.
devices Array of
deviceId
deviceId Integer Mandatory Id of device for which the missing load
profile data to download.

Or

{
"start": "2017-05-21",
"end": "2017-06-21",
"devices": [
{
"plantNumber": "Meter1",
},
{
"plantNumber": "Meter2",
},
{
"plantNumber": "Meter3",
}
]
}

Property Type Optional/Mandatory Description

start Date Mandatory Date starting to download missing load
profile data.
end Date Mandatory The last date to download missing load
profile data.
devices Array of
plantNumber
plantNumber String Mandatory Plant number of device for which the
missing load profile data to download.

Returns 200 OK
400 Bad Request (Request is not properly formed, or end date is not later than start date)
401 Unauthorized (Token invalid)
403 Forbidden (Access not allowed)
500 Internal Server Error (MDDCS not reachable, or download start/end dates not set correctly for one
or more devices)

Page 132
 MultiDrive Web API 2.8 User Guide

Appendix

API Area Error Code Description

6
ter1
p
a
h
C

A
API Error Codes

Fleet CalorificValue-000 Calorific Value Name does not exist

Management
CalorificValue-001 Calorific Value Id is not valid
CalorificValue-002 Calorific Value name is required
CalorificValue-003 Calorific Value conversion factor is required
CalorificValue-004 Calorific Value value is required
CalorificValue-005 Calorific Value conversion factor is not valid
CalorificValue-006 Calorific Value value is not valid
CalorificValue-007 Calorific Value name is not valid
CalorificValue-008 Payload is not valid
CalorificValue-009 Calorific Value is not valid
CalorificValue-404 Calorific Value Id does not exist
CalorificValue-409 Calorific Value name already exists
CalorificValue-500 Internal Error occurred. Please contact your System Administrator
Commissioning-000 Remove From Group is not valid
Commissioning-001 Device Id is not valid
Commissioning-002 Plant number is not valid
Commissioning-003 Device Group Id is not valid
Commissioning-004 Device Id does not exist
Commissioning-005 Plant number does not exist
Commissioning-006 Device Group Id does not exist
Commissioning-007 SIM ICC ID does not exist
Commissioning-008 Modem IMEI does not exist
Commissioning-009 Device serial number does not exist
Commissioning-010 SIM ICC ID is not valid
Commissioning-011 Modem IMEI is required
Commissioning-012 Device serial number is required
Commissioning-013 Device is out of service
Commissioning-014 Device is already commissioned
Commissioning-015 Device is not ready for commissioning
Commissioning-016 Schedule Id is not valid
Commissioning-017 Schedule Id does not exist

Page 133
 MultiDrive Web API 2.8 User Guide

Commissioning-018 Site Id is not valid

Commissioning-019 Site Id does not exist
Commissioning-020 User not found
Commissioning-021 Device is already decommissioned
Commissioning-022 Device cannot be decommissioned
Commissioning-023 Device not linked to site
Commissioning-024 Cannot mix device Id and plant number
Commissioning-025 Payload is empty
Commissioning-026 Payload is not valid
Commissioning-500 Internal Error occurred. Please contact your System Administrator
CommissioningEvent Start Date cannot be later than End Date
-000
CommissioningEvent Internal Error occurred. Please contact your System Administrator
-500
Customer-001 No record found
Customer-002 Offset is not valid
Customer-003 Limit is not valid
Customer-004 Offset should not be less than 0
Customer-005 Limit should not be greater than 5000
Customer-006 Limit should not be less than 0
Customer-007 Parameter username is required
Customer-008 Parameter password is required
Customer-009 Customer username/password is invalid
Customer-010 Customer has been deactivated
Customer-011 Parameter newPassword is required
Customer-012 Customer Code is required
Customer-013 Status is required
Customer-014 Security level is required
Customer-015 Invalid security level value
Customer-016 Invalid status value
Customer-017 Invalid device group Id
Customer-018 Device group name is required
Customer-019 Invalid report group Id
Customer-020 Schedule Id is required
Customer-021 Invalid schedule Id
Customer-022 Schedule name is required
Customer-023 Customer code already exists
Customer-024 Specified device group Id and name do not match
Customer-025 Report group Id is required
Customer-026 Specified schedule Id and name do not match
Customer-027 Invalid payload
Customer-028 Device group Id is required
Customer-029 Disabled customer
Customer-030 Customer Code does not exist in Multidrive
Customer-031 Invalid customer agent setting information
Customer-032 Invalid customer agent values

Page 134
 MultiDrive Web API 2.8 User Guide

Customer-033 Invalid customer Id

Customer-034 Customer Id is required
Customer-035 Customer Id does not exist
Customer-036 Customer Id and username do not belong to the same customer
Customer-037 Customer code and username do not belong to the same customer
Customer-038 Parameter oldPassword is required
Customer-039 Customer status is not valid
Customer-500 Internal Error occurred. Please contact your System Administrator
Device-000 Status is not valid
Device-001 Site Assigned is not valid
Device-002 Install Date is not valid
Device-003 Commission Date is not valid
Device-004 Decommission Date is not valid
Device-005 Device Id is not valid
Device-006 No record found
Device-007 Device does not exist
Device-008 Parameter is invalid
Device-009 Plant number is invalid
Device-010 Method not allowed
Device-011 Payload is not valid
Device-012 There was an error in deleting the device
Device-013 Device Id does not exist
Device-014 Plant Number does not exist
Device-015 Device is not valid
Device-016 Changes are not valid
Device-018 Limit is not valid
Device-019 Offset is not valid
Device-020 Device group id is not valid
Device-021 Username or password is not valid
Device-022 Password must be more than 5 characters
Device-023 Serial number is not valid
Device-024 Serial number is required
Device-025 Plant number is required
Device-026 Plant number already exists
Device-027 Device config Id is not valid
Device-028 Device config Id does not exist
Device-029 Device config name does not exist
Device-030 Device meter point does not exist
Device-031 Device must not be null
Device-032 Misc is not valid
Device-033 Limit should not be less than 0
Device-034 Limit should not be greater than 5000
Device-035 Offset should not be less than 0
Device-036 System status associated with the required job not found

Page 135
 MultiDrive Web API 2.8 User Guide

Device-037 Invalid retries count

Device-038 Invalid install date range
Device-039 Invalid uninstall date range
Device-040 Invalid Ping count
Device-041 Execution Id does not exist
Device-042 Invalid execution Id
Device-400 Bad Request
Device-500 Internal Error occurred. Please contact your System Administrator
Device-501 Internal Server Error. There was an error in MDSCI method call. Please
check the MDSCI logs
DeviceConfig-000 Device configuration Id/name is not valid
DeviceConfig-404 Device Configuration does not exit
DeviceConfig-500 Internal Error occurred. Please contact your System Administrator
DeviceGroup-000 Device Group Id is not valid
DeviceGroup-001 Changes are not valid
DeviceGroup-002 Device Id is not valid
DeviceGroup-003 Payload is not valid
DeviceGroup-005 Plant Number is not valid
DeviceGroup-006 Changes are not valid
DeviceGroup-007 Payload is required
DeviceGroup-008 Device group Id does not exist
DeviceGroup-009 Device Id does not exist
DeviceGroup-010 Plant Number does not exist
DeviceGroup-011 Device Meter Point does not exist
DeviceGroup-012 Parameter is invalid
DeviceGroup-013 Device Group Name does not exist
DeviceGroup-014 Device group Id is required
DeviceGroup-015 Device group must not be null
DeviceGroup-016 Device group name is required
DeviceGroup-017 Parent device group Id is not valid
DeviceGroup-018 Device group status is required
DeviceGroup-019 Device group status is not valid
DeviceGroup-020 Device group name already exists
DeviceGroup-021 Device group name is not valid
DeviceGroup-022 Must specify Device group Id or Device group name
DeviceGroup-023 Should not specify both Device group Id and Device group name
DeviceGroup-024 Device group does not contain any device
DeviceGroup-025 Limit is not valid
DeviceGroup-026 Limit should not be greater than 5000
DeviceGroup-027 Limit should not be less than 0
DeviceGroup-028 Offset is not valid
DeviceGroup-029 Offset should not be less than 0
DeviceGroup-030 Unexpected operation status
DeviceGroup-400 Device Group is not valid
DeviceGroup-404 Device Group does not exist

Page 136
 MultiDrive Web API 2.8 User Guide

DeviceGroup-500 Internal Error occurred. Please contact your System Administrator

DeviceSetup-000 Device Id not found in MultiDrive
DeviceSetup-001 Plant number not found in MultiDrive
DeviceSetup-002 Payload is not valid
DeviceSetup-003 Payload is empty
DeviceSetup-004 Payload properties are empty
DeviceSetup-005 StageName is not valid
DeviceSetup-006 SetupXml is not valid
DeviceSetup-007 Device not linked to site
DeviceSetup-008 Device Id is not valid
DeviceSetup-009 Device setup not read
DeviceSetup-011 Template name not specified
DeviceSetup-012 Setup string not specified
DeviceSetup-013 Template name not unique
DeviceSetup-014 Invalid setup stages
DeviceSetup-015 Invalid template Id/name
DeviceSetup-016 Template Id not found
DeviceSetup-017 Cannot mix device Id and plant number
DeviceSetup-019 Device Id not found
DeviceSetup-020 Plant number not found
DeviceSetup-021 Devices not linked to site
DeviceSetup-022 Device Type mismatched
DeviceSetup-023 Template name not found
DeviceSetup-500 Internal Error occurred. Please contact your System Administrator
DeviceSetup-501 Internal Server Error. There was an error in MDSCI method call. Please
check the MDSCI logs
MeteringPoint-000 Metering point status is not valid
MeteringPoint-001 Offset is not valid
MeteringPoint-002 Limit is not valid
MeteringPoint-003 Offset should not be less than 0
MeteringPoint-004 Limit should not be greater than 5000
MeteringPoint-005 Limit should not be less than 0
MeteringPoint-006 Invalid metering point Id
MeteringPoint-007 Metering point Id is required
MeteringPoint-008 Metering point Id does not exist
MeteringPoint-009 Metering point code is required
MeteringPoint-010 Metering point code does not exist
MeteringPoint-011 Metering point code already exists
MeteringPoint-012 Source Id is required
MeteringPoint-013 Invalid source Id value
MeteringPoint-014 Metering point status is required
MeteringPoint-015 Invalid metering point status value
MeteringPoint-016 Device Id is required
MeteringPoint-017 Invalid device Id value
MeteringPoint-018 Device plant number is required
MeteringPoint-019 Device serial number is required

Page 137
 MultiDrive Web API 2.8 User Guide

MeteringPoint-020 Device status is required

MeteringPoint-021 Invalid device status value
MeteringPoint-022 Specified device Id and plant number do not match
MeteringPoint-023 Specified device Id and serial number do not match
MeteringPoint-024 Customer Id is required
MeteringPoint-025 Invalid customer Id value
MeteringPoint-026 Customer code is required
MeteringPoint-027 Customer status is required
MeteringPoint-028 Invalid customer status value
MeteringPoint-029 Specified customer Id and customer code do not match
MeteringPoint-030 Invalid payload
MeteringPoint-031 Invalid activation date range
MeteringPoint-032 Invalid termination date range
MeteringPoint-404 Metering point does not exist
MeteringPoint-500 Internal Error occurred. Please contact your System Administrator
Modem-000 Payload is not valid
Modem-001 Modem is not valid
Modem-002 Modem firmware version is not valid
Modem-003 Modem serial number is not valid
Modem-004 Modem status is not valid
Modem-005 Modem Id is not valid
Modem-006 Modem IMEI is not valid
Modem-007 Modem IMEI is required
Modem-008 Modem IMEI is already existing for Modem Id =
Modem-009 Limit is not valid
Modem-010 Offset is not valid
Modem-011 Modem Modelname is not valid
Modem-012 Modem status is required
Modem-013 Modem model name is not valid
Modem-014 Method not implemented
Modem-015 Limit should not be less than 0
Modem-016 Limit should not be greater than 5000
Modem-017 Offset should not be less than 0
Modem-401 Modem Id does not exist
Modem-402 Modem IMEI does not exist
Modem-404 Not Found
Modem-500 Internal Error occurred. Please contact your System Administrator
PairingEvent-000 Start Date cannot be later than End Date
PairingEvent-500 Internal Error occurred. Please contact your System Administrator
SIM-000 Country is not valid
SIM-001 DataPlan Name is not valid
SIM-002 ICCID is not valid
SIM-003 ICCID is required
SIM-004 IMSI is not valid
SIM-005 MNC is not valid

Page 138
 MultiDrive Web API 2.8 User Guide

SIM-006 MCC is not valid

SIM-007 MSISDN is not valid
SIM-008 Provider Name is not valid
SIM-009 SimId is not valid
SIM-010 Sim Status is not valid
SIM-011 Sim Status is required
SIM-012 SimId does not exist
SIM-013 ICCID was not found
SIM-014 Payload is not valid
SIM-015 Limit is not valid
SIM-016 Offset is not valid
SIM-017 Changes are not valid
SIM-018 Limit should not be less than 0
SIM-019 Limit should not be greater than 5000
SIM-020 Offset should not be less than 0
SIM-404 Not Found
SIM-409 ICCID already exists
SIM-500 Internal Error occurred. Please contact your System Administrator
SIM-501 Method not implemented
Site-000 Site Id is not valid
Site-001 Site Code is not valid
Site-002 IsPersistentComms is not valid
Site-003 Site changes are not valid
Site-004 New site is not valid
Site-005 Site Code does not exist
Site-006 Site is not valid
Site-007 Site Code already exists
Site-008 Site Code is required
Site-009 Site Id does not exist
Site-010 Site must not be null
Site-011 Site communication type is not valid
Site-012 Site must have at least one communication settings
Site-013 There are too many site comms settings
Site-014 Site comm settings order is not valid
Site-015 Site comm settings deviceType is not valid
Site-016 Site comm settings deviceChaining is not valid
Site-017 IsPersistent comms is required
Site-018 IsPersistent is not valid
Site-019 Site comm settings deviceChaining {0} is not valid
Site-020 No active communication server of type {0} is available
Site-021 Site must have complete communication settings
Site-022 MODEM Id is not valid
Site-023 MODEM Id does not exist
Site-024 SIM Id is not valid
Site-025 SIM Id does not exist

Page 139
 MultiDrive Web API 2.8 User Guide

Site-026 ComDeviceType is not valid

Site-027 Site needs complete IP settings
Site-028 Site IP Address, Port and Protocol are required
Site-029 Site IP Address is not valid
Site-030 Site IP port is not valid
Site-031 Site IP protocol is not valid
Site-032 No modem communication device is available
Site-033 Site needs Modem settings
Site-034 Modem device type cannot be non-persistent
Site-035 Site Modem phone number is required
Site-036 Site Modem phone number is not valid
Site-037 Limit is not valid
Site-038 Offset is not valid
Site-039 No active communication server of type {0} is found in the communication
server pool
Site-040 Limit should not be less than 0
Site-041 Limit should not be greater than 5000
Site-042 Offset should not be less than 0
Site-404 Site does not exist
Site-500 Internal Error occurred. Please contact your System Administrator
ZigBee-000 Either MAC Address / Gas Meter Serial Number should be provided
ZigBee-001 MAC Address does not exist
ZigBee-002 Access not allowed
ZigBee-003 MAC Address was blacklisted
ZigBee-004 IMEI does not exist
ZigBee-005 IMEI is required
ZigBee-006 Either the Gas Meter Serial Number does not exist or it is not related to a
ZigBee device
ZigBee-007 Install code is not valid
ZigBee-008 Gas Meter Serial Number is required
ZigBee-009 MAC Address is required
ZigBee-500 Internal Error occurred. Please contact your System Administrator
Measured MeasuredData-000 Device Id is not valid
Data MeasuredData-001 Start Date is not valid
MeasuredData-002 End Date is not valid
MeasuredData-003 Period Type is not valid
MeasuredData-004 Offset is not valid
MeasuredData-005 Offset should not be less than 0
MeasuredData-006 Limit is not valid
MeasuredData-007 Limit should not be greater than {0}
MeasuredData-008 End Date should not exceed 1 month from the Start Date
MeasuredData-009 End Date should not be less than or equal to Start Date
MeasuredData-010 Limit should not be less than 0
MeasuredData-011 Data type does not exist
MeasuredData-012 Data type does not contain unit of measurement
MeasuredData-013 Data type contains value not supported by MDX

Page 140
 MultiDrive Web API 2.8 User Guide

MeasuredData-014 Log number is not valid

MeasuredData-404 Device does not exist
MeasuredData-500 Internal Error occurred. Please contact your System Administrator
Prepayment Prepayment-000 Device Id does not exist
Prepayment-001 Plant number does not exist
Prepayment-002 Payload is not valid
Prepayment-003 Payload is empty
Prepayment-004 Payload properties are empty
Prepayment-005 Meter does not support prepayment
Prepayment-006 Credit Balance is not valid
Prepayment-007 Remaining Days is not valid
Prepayment-009 Prepayment information does not exist
Prepayment-010 Device not linked to site
Prepayment-011 Device Id is not valid
Prepayment-012 Dollar Value should not be greater than 8191
Prepayment-013 Dollar Value is not valid
Prepayment-014 Originator Counter is not valid
Prepayment-015 Token transfer history does not exist
Prepayment-016 Execution Id is not valid
Prepayment-017 Prepayment is disabled
Prepayment-018 Prepayment mode is required
Prepayment-019 Prepayment mode is invalid
Prepayment-500 Internal Error occurred. Please contact your System Administrator.
Prepayment-501 Internal Server Error. There was an error in MDSCI method call. Please
check the MDSCI logs
Scheduling AsyncCallback-400 Invalid callback payload
AsyncCallback-501 Asynchronous Callback is not supported by current version of MultiDrive
Server
AsyncCallback-503 Asynchronous Callback is not enabled on MultiDrive Server
ScheduleSettings-000 Priority is invalid
Scheduling-000 Schedule name is not valid
Scheduling-001 Status is not valid
Scheduling-002 Has warning is not valid
Scheduling-003 Schedule Execution Id is not valid
Scheduling-004 Site code is not valid
Scheduling-005 Plant number is not valid
Scheduling-006 Schedule Feature is not valid
Scheduling-007 Device Id is not valid
Scheduling-008 Schedule Id is not valid
Scheduling-009 Execution Id does not exist
Scheduling-010 Execution Job Id does not exist
Scheduling-011 No communications log was stored
Scheduling-012 No schedule log was stored
Scheduling-013 Limit is not valid
Scheduling-014 Offset is not valid
Scheduling-015 Schedule Name does not exist

Page 141
 MultiDrive Web API 2.8 User Guide

Scheduling-016 Payload is not valid

Scheduling-017 Device not linked to site
Scheduling-018 Limit should not be greater than 5000
Scheduling-019 Limit should not be less than 0
Scheduling-020 Offset should not be less than 0
Scheduling-021 Device id and Plant Number do not match
Scheduling-022 Device Id not found in MultiDrive
Scheduling-023 Site code not found in MultiDrive
Scheduling-024 Device not linked to site
Scheduling-025 Plant number not found in MultiDrive
Scheduling-026 Execution Job Id is not valid
Scheduling-027 System status associated with the required job not found
Scheduling-028 Invalid retries count
Scheduling-029 Start date is not valid
Scheduling-030 End date is not valid
Scheduling-031 End date must be later than start date
Scheduling-032 Both start and end date parameter are required
Scheduling-400 Payload is invalid or not well formed or device ids are invalid
Scheduling-404 Schedule Id does not exist
Scheduling-405 Unknown method
Scheduling-409 The location header cannot be generated
Scheduling-500 Internal Error occurred. Please contact your System Administrator
Scheduling-501 Internal Server Error. There was an error in MDSCI method call. Please
check the MDSCI logs
Supply LoadLimit-000 Invalid control mode
Control LoadLimit-001 Threshold is not valid
LoadLimit-002 Threshold should not be less than 0
LoadLimit-003 StartTime format is not valid
LoadLimit-004 EndTime format is not valid
LoadLimit-005 ApportionPolicy is not valid
LoadLimit-006 Device id is not valid
LoadLimit-007 Device Id does not exist
LoadLimit-008 Plant number does not exist
LoadLimit-009 Control mode is required
LoadLimit-010 Device not linked to site
LoadLimit-011 Start time specified, End time also required
LoadLimit-012 End time specified, Start time also required
LoadLimit-013 Start time must be greater than 1899-12-30T00:00:00
LoadLimit-014 End time must be greater than or equal to the specified Start time
LoadLimit-015 Payload is empty
LoadLimit-016 Payload is not valid
LoadLimit-017 Cannot mix deviceId and plant number
LoadLimit-500 Internal Error occurred. Please contact your System Administrator
LoadLimit-501 Internal Server Error. There was an error in MDSCI method call. Please
check the MDSCI logs
RelayStatus-000 Offset is not valid

Page 142
 MultiDrive Web API 2.8 User Guide

RelayStatus-001 Offset should not be less than 0

RelayStatus-002 Limit is not valid
RelayStatus-003 Limit should not be greater than 5000
RelayStatus-004 Limit should not be less than 0
RelayStatus-005 Control code is not valid
RelayStatus-006 StartDate is not valid
RelayStatus-007 EndDate is not valid
RelayStatus-008 Device Id does not exist
RelayStatus-009 Plant number is not valid
RelayStatus-010 Control code is not valid or parameters are missing
RelayStatus-011 Device group Id does not exist
RelayStatus-012 Device group Id is not valid
RelayStatus-013 Device Id is not valid
RelayStatus-014 No relay status found
RelayStatus-015 Plant number does not exist
RelayStatus-016 Device group name does not exist
RelayStatus-017 Payload is not valid
RelayStatus-018 mainsControlDuration is not valid
RelayStatus-019 MainsControlDuration in Web.config is not valid
RelayStatus-020 Device not linked to site
RelayStatus-021 Payload is empty
RelayStatus-022 Cannot mix deviceId and plant number
RelayStatus-404 Device Id or plant number does not exist
RelayStatus-500 Internal Error occurred. Please contact your System Administrator
RelayStatus-501 Internal Server Error. There was an error in MDSCI method call. Please
check the MDSCI logs
System Authentication-000 Username/Password is invalid
Authentication-001 Username has been disabled
Authentication-002 Token is invalid
Authentication-003 Hash is not valid or timestamp is too old
Authentication-004 Token not found
Authentication-500 Internal Error occurred. Please contact your System Administrator
Decryption-000 Password should not be empty
Decryption-001 Device serial number should not be empty
Decryption-002 Encrypted password is invalid
Decryption-003 Internal Error occurred. Please contact your System Administrator
Data Delivery AnyAvailableData- Meter Point Id does not exist
000
AnyAvailableData- Device Group Id does not exist
001
AnyAvailableData- Device Group Name does not exist
002
AnyAvailableData- Plant Number does not exist
003
AnyAvailableData- Start date must not be greater than End date
004
AnyAvailableData- Device Id is not valid
005

Page 143
 MultiDrive Web API 2.8 User Guide

AnyAvailableData- Device Group Id is not valid

006
AnyAvailableData- No devices under the selected group
007
AnyAvailableData- Start Date is required/not valid
008
AnyAvailableData- End Date is required/not valid
009
AnyAvailableData- Access not allowed
403
AnyAvailableData- Device Id does not exist
404
DataDelivery-000 Delivery Id is not valid
DataDelivery-400 Bad Request
DataDelivery-404 Delivery Id does not exist
DataDelivery-500 Internal Error occurred. Please contact your System Administrator
LoadProfile-000 MeterPoint Id does not exist
LoadProfile-001 Start date must not be greater than End date
LoadProfile-002 No associated data mapping for selected Load Profiles
LoadProfile-003 More than 1 associated data mapping for selected Load Profiles
LoadProfile-004 No associated manual mapping
LoadProfile-005 Device Configuration of Meter has no associated Load Profile Mapping
LoadProfile-006 Device Group Id does not exist
LoadProfile-007 No Quantity Channels for selected Load Profile
LoadProfile-008 Device Group Name does not exist
LoadProfile-009 No devices under the selected group
LoadProfile-010 Plant Number does not exist
LoadProfile-011 Device Id is not valid
LoadProfile-012 Device Group Id is not valid
LoadProfile-013 No associated data mapping for this profile type
LoadProfile-014 Start Date is required/not valid
LoadProfile-015 End Date is required/not valid
LoadProfile-400 Bad Request
LoadProfile-404 Device Id does not exist
LoadProfile-500 Internal Error occurred. Please contact your System Administrator
TriggerLog-000 Device Id does not exist
TriggerLog-001 Plant number does not exist
TriggerLog-002 Device group Id does not exist
TriggerLog-003 Device group name does not exist
TriggerLog-004 Device has no associated meterpoint
TriggerLog-005 Device has no associated device configuration
TriggerLog-006 Device group does not have any associated devices
TriggerLog-007 Start Date is required
TriggerLog-008 Start Date is not valid
TriggerLog-009 End Date is required
TriggerLog-010 End Date is not valid
TriggerLog-011 Start date must not be greater than End date
TriggerLog-012 Device Configuration of Meter has no enabled event types

Page 144
 MultiDrive Web API 2.8 User Guide

TriggerLog-013 Device Id is not valid

TriggerLog-014 Device Group Id is not valid
TriggerLog-015 Selected Event Type is not supported
TriggerLog-403 Access not allowed
TriggerLog-400 Bad request
TriggerLog-500 Internal Error occurred. Please contact your System Administrator
TriggerTOU-000 Device Id does not exist
TriggerTOU-001 Plant number does not exist
TriggerTOU-002 Device group Id does not exist
TriggerTOU-003 Device group name does not exist
TriggerTOU-004 Device has no associated meterpoint
TriggerTOU-005 Device has no associated device configuration
TriggerTOU-006 Device Configuration of Meter has no associated TOU Mapping
TriggerTOU-007 No TOU Period matches the TOU periods specified in the request
TriggerTOU-008 Device has no associated TOU data
TriggerTOU-009 Start Date is required
TriggerTOU-010 Start Date is not valid
TriggerTOU-011 End Date is required
TriggerTOU-012 End Date is not valid
TriggerTOU-013 Device group does not have any associated devices
TriggerTOU-014 Start date must not be greater than End date
TriggerTOU-015 Device Id is not valid
TriggerTOU-016 Device Group Id is not valid
TriggerTOU-017 No TOU Period matches the TOU periods specified in the request for block
{0}
TriggerTOU-018 One or more of the period types in the request is not supported
TriggerTOU-400 Bad request
TriggerTOU-500 Internal Error occurred. Please contact your System Administrator
Diagnostic Diagnostic-000 Execution Id not found in MultiDrive
Diagnostic-001 Device Id not found in MultiDrive
Diagnostic-002 Plant number not found in MultiDrive
Diagnostic-003 Payload is empty
Diagnostic-004 Payload is not valid
Diagnostic-005 Payload properties are empty
Diagnostic-009 Diagnostic Register Value does not exist
Diagnostic-010 Devices not linked to site
Diagnostic-011 Device Id is not valid
Diagnostic-012 Execution Id is not valid
Diagnostic-013 Device group Id is not valid
Diagnostic-014 Device group Id not found in MultiDrive
Diagnostic-015 Device Group Name not found in MultiDrive
Diagnostic-016 Device group does not contain any device
Diagnostic-500 Internal Error occurred. Please contact your System Administrator.
Diagnostic-501 Internal Server Error. There was an error in MDSCI method call. Please
check the MDSCI logs
msg_Accepted Accepted

Page 145
 MultiDrive Web API 2.8 User Guide

msg_OK OK
Notification Notification-000 Invalid payload
Notification-001 remark property not specified
Notification-002 notifications property not specified
Notification-003 Invalid notificationId
Notification-004 Exceeds maximum number of notifications allowed for acknowledgment
Notification-005 Invalid Callback url
Notification-006 Payload not specified
Notification-007 Uri not specified for callback notification
Notification-404 Notification Ids not found in MultiDrive
Notification-500 Internal Error occurred. Please contact your System Administrator.
Notification-501 Internal Server Error. There was an error in MDSCI method call. Please
check the MDSCI logs
Notification-502 Component for Alarm Callback is not initialized correctly
MDDCS MDDCS-000 Payload is not valid
MDDCS-001 Payload is empty
MDDCS-002 Device Id not found
MDDCS-003 MDDCS unreachable
MDDCS-004 Start date is not valid
MDDCS-005 End date is not valid
MDDCS-006 End date must be later than Start date
MDDCS-007 Device Id is not valid
MDDCS-008 Should not specify both Device Id and Plant number
MDDCS-009 Device Id/Plant number property is empty
MDDCS-010 MDDCS API application setting is not configured
MDDCS-011 Plant number not found
MDDCS-012 Failed to request MDDCS AuthToken
MDDCS-013 Start date must be later than current date
MDDCS-014 Start/End date must not be later than current date
MDDCS-015 End date must be later than or equal to Start date
MDDCS-500 Internal Error occurred. Please contact your System Administrator

Page 146
 MultiDrive Web API 2.8 User Guide

Appendix

B.1. MDX – Flow Direction

MDX Constants
7
ter1
p
a
h
C

B
Value Description
NONE No flow direction.
DELIVERED Forward or Import as per IEC definition. Also known as Consumption; Inbound.

RECEIVED Reverse or Export as per IEC definition. Also known as Generation; outbound

ABSOLUTE Total as per IEC definition. Sum of delivered and received; total flow.

NET_DELIVERED Net as per IEC definition. Delivered less received.

Q1 Quadrant 1 only.
Q2 Quadrant 2 only.
Q3 Quadrant 3 only.
Q4 Quadrant 4 only.
Q1Q3 Quadrants 1 and 3.
Q1Q4 Quadrants 1 and 4.
Q2Q3 Quadrants 2 and 3.
Q2Q4 Quadrants 2 and 4.
Q1Q2Q3 Quadrants 1, 2 and 3.
Q1Q2Q4 Quadrants 1, 2 and 4.
Q1Q3Q4 Quadrants 1, 3 and 4.
Q2Q3Q4 Quadrants 2, 3 and 4.

B.2. MDX – Apportion Policy

Apportion Policy Description
MIN Minimum value is used when apportioniong

Page 147
 MultiDrive Web API 2.8 User Guide

INST Value is instantaneous; apportioning not applicable.

Note this is not supported with any of the current UOMs supported.
AVG Average of values is used when apportioning
MAX Maximum value is used when apportioning
SUM Sum of all values is used when apportioning

B.3. MDX - Phase

Phase Description
NONE No phase, phase not known, or phase not applicable
A Phase A
B Phase B
C Phase C
LINE_TOTAL Three phase total
AB Phase angle AB
BC Phase angle BC
AC Phase angle AC
TOTAL Line type
MAIN Line type
LOAD Line type
EARTH Line type
NEUTRAL Line type
ABC_AVERAGE Abc Average

B.4. MDX – Unit Types (UOM)

Unit Description Flow Directions Phases Recommended Apportion
Policies
WH Watt Hour DELIVERED ABC SUM
RECEIVED NONE
VARH var Hour DELIVERED ABC SUM
RECEIVED NONE
VAR var DELIVERED ABC SUM
RECEIVED NONE
VAH VoltAmp Hour DELIVERED ABC SUM
RECEIVED NONE
A Ampere NONE ABC MIN MAX AVG
NONE
V Volt NONE ABC MIN MAX AVG
NONE
W Watt DELIVERED ABC AVG
RECEIVED NONE
VA VoltAmp DELIVERED ABC AVG
RECEIVED NONE
PF Power Factor DELIVERED ABC AVG
RECEIVED NONE

Page 148
 MultiDrive Web API 2.8 User Guide

NONE
C (degrees) Celsius NONE NONE MIN MAX AVG
M3 m³, cubic metre DELIVERED NONE SUM
RECEIVED
L l, Litre DELIVERED NONE SUM
RECEIVED
GAL Gallon NONE NONE SUM
KG kilogramme DELIVERED NONE SUM
RECEIVED
J Joule DELIVERED NONE SUM
RECEIVED
OHM Ohm NONE NONE AVG
CURRENCY Currency DELIVERED
RECEIVED
NONE
DB Decibel (dB) NONE NONE AVG
HZ hertz NONE NONE AVG
PHASE_ANGLE Phase angle (º) NONE ABC AVG
NONE
VOLTAGE_ANGLE Voltage angle (º) NONE ABC AVG
NONE
PERCENT Percent (%) NONE NONE AVG
NUMERIC Numeric (no unit) NONE NONE SUM
BOOLEAN Boolean (true and false) NONE NONE MAX
CURRENT_THD Currrent Total Harmonic Distortion NONE ABC AVG
NONE
VOLTAGE_THD Voltage Total Harmonic Distortion NONE ABC AVG
NONE

B.5. MDX – Accumulation Policy

Specifies how values have been accumulated during the measurement period.
Accumulation Policy Description

INTERVAL Value is accumulated for the captured interval period

CUMULATIVE Value is accumulated since the day device had been installed and activated

The diagram below explained the different between Interval and Cumulative value:

Page 149
 MultiDrive Web API 2.8 User Guide

Appendix

C
Device Setup Template
8
ter1
p
a
h
C

C.1. Electric meter setup template : Change of Supplier

<?xml version="1.0" encoding="utf-16"?>
<MainData xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<MeterRevision>2000956</MeterRevision>
<MeterType>Mk7B</MeterType>
<MeterFirmwareVersion>2.911</MeterFirmwareVersion>
<RawEdition>188771760</RawEdition>
<SMETS1Supplier>
<NewSupplierDateTime>2017-04-01T00:00:00</NewSupplierDateTime>
<NewSupplierName>ABC</NewSupplierName>
<NewSupplierID>12</NewSupplierID>
<MajorVersion>1</MajorVersion>
<MinorVersion>0</MinorVersion>
</SMETS1Supplier>
</MainData>

C.2. Gas meter setup template : Change of Supplier

<TestTasks>
<TestTask>
<Name>Set_Passive_CoS_Effective_From_Datetime</Name>
<DLMSTask>SetAttribute</DLMSTask>
<ObisCode>0.0.65.1.1.255</ObisCode>
<InterfaceClass>114</InterfaceClass>
<Index>8</Index>
<DLMSAttributeValues>
<OctetString Value="07E00106FF0D0000008000FF" /></DLMSAttributeValues>
</TestTask>
<TestTask>
<Name>Set_Passive_CoS_Supplier_Ref</Name>
<DLMSTask>SetAttribute</DLMSTask>
<ObisCode>0.0.65.1.1.255</ObisCode>
<InterfaceClass>114</InterfaceClass>
<Index>12</Index>
<DLMSAttributeValues>
<OctetString Value="73757072656632" /></DLMSAttributeValues>
</TestTask>
<TestTask>
<Name>Set_CoS_Changeover_Datetime</Name>
<DLMSTask>SetAttribute</DLMSTask>
<ObisCode>0.0.65.1.1.255</ObisCode>
<InterfaceClass>114</InterfaceClass>
<Index>14</Index>
<DLMSAttributeValues>
<OctetString Value="07E00106FF0D0000008000FF" /></DLMSAttributeValues>

Page 150
 MultiDrive Web API 2.8 User Guide

</TestTask>
<TestTask>
<Name>Apply_Config</Name>
<DLMSTask>SetAttribute</DLMSTask>
<ObisCode>0.0.96.128.4.255</ObisCode>
<InterfaceClass>1</InterfaceClass>
<Index>2</Index>
<DLMSAttributeValues>
<Unsigned Value="01" /></DLMSAttributeValues>
</TestTask>
</TestTasks>

Page 151