{ "openapi": "3.0.0", "info": { "title": "New POWWR Utility Meter Lookup Service", "description": "---\nMulti-step Electricity and Gas meter lookup service, to be used at the start of a meter quote journey.\n\n**Typical Usage**\n1. Obtain an OAuth token from the POWWR Auth Server\n2. Call `/addressSearch` with the site PostCode to retrieve the meter points for the address.\n3. Call `/meterSearch` with the desired MeterAddressId or MPAN/MPRN to fetch the meter properties\n\nIf MPAN/MPRN is known in advance, step 2 can be skipped.\n\n---\nVersion History\n\n1.0.0\n+ Initial Schema\n\n1.0.1\n+ Added Version history, description, and property examples & descriptions\n+ Added error response formats RFC7807\n+ Remove Building and Sub Building on address request\n\n1.1.0\n+ Added MeterMechanismCode to GasMeter\n\n2.0.0\n+ Removed IsSmart and CurrentSupplierPowwrId\n\n2.1.0\n+ Added OrganisationPowwrId, ApplicationId, and UserId\n+ Added information on MPAN redaction for AddressSearch\n\n2.2.0\n+ Added ElectricMeter.GreenDealStatus\n+ Added GasMeter.Ldz\n+ Added MeterPointLocation.DeliveryPointAlias\n+ Added MeterPointLocation.AdministrativeArea\n\n2.3.0\n+ Added ElectricMeter.TradingStatus\n+ Corrected casing on example responses\n+ Fixed camelCase of property names to match API\n+ Changed /addressSearch and /meterSearch response from array to object\n+ Removed incorrect quotes on example responses\n\n2.4.0 \n+ Added Supplier object, with fields Mpid, ShortCode, Name, EffectiveDate, and PowwrId\n+ Added MeterCapacity, DailyMeteredQuantity, CurrentSupplier, IncomingSupplier, and AdditionalInformation to GasMeter\n+ Added EnergisationStatusEffectiveDate, CurrentSupplier, SMETSVersion, and AdditionalInformation to ElectricMeter\n+ Removed parameters for IncludeConsumption and IncludeCurrentSupplier - these are no longer required as Consumption and Current Supplier are now always returned\n\n2.5.0 \n+ Added meterModel to GasMeter\n", "version": "2.5.0" }, "security": [ { "ApiKeyAuth": [] } ], "paths": { "/Search/addressSearch": { "description": "Performs a lookup on the provided postcode. Returns a set of addresses found in ECOES and XOSERVE data, including IDs for subsequent MeterSearch calls.", "post": { "requestBody": { "description": "the address search criteria", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddressSearchRequest" } } }, "required": true }, "responses": { "200": { "description": "search results matching criteria", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddressSearchResults" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsRfc7807" } } } } } } }, "/Search/meterSearch": { "post": { "requestBody": { "description": "the search criteria", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MeterSearchRequest" }, "examples": { "ById": { "value": { "callerIdentification": { "organisationPowwrId": "EXAMPLE-001-B" }, "meterAddressId": "U10023061032A0085759074G1M1610028163246N2PM224DB" } }, "ByMPAN": { "value": { "callerIdentification": { "organisationPowwrId": "EXAMPLE-001-B" }, "mpan": "1610028163246" } }, "ByMPRN": { "value": { "callerIdentification": { "organisationPowwrId": "EXAMPLE-001-B" }, "mprn": "14097001" } } } } }, "required": true }, "responses": { "200": { "description": "search results matching criteria", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MeterSearchResults" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsRfc7807" } } } } } } } }, "components": { "schemas": { "AddressSearchRequest": { "required": [ "callerIdentification", "postCode" ], "type": "object", "properties": { "callerIdentification": { "$ref": "#/components/schemas/CallerIdentification" }, "postCode": { "type": "string", "description": "Full postcode 6-8 characters; space is expected; no results will be found for a partial postcode", "example": "M22 4DB" } } }, "AddressSearchResults": { "type": "object", "properties": { "meterAddresses": { "type": "array", "items": { "$ref": "#/components/schemas/MeterAddress" } } } }, "MeterAddress": { "type": "object", "properties": { "meterAddressId": { "type": "string", "example": "U10023061032A0085759074G1M1610028163246N2PM224DB" }, "fullAddress": { "type": "string", "example": "PARKWAY HOUSE, PALATINE ROAD, MANCHESTER, M22 4DB" }, "mpanCount": { "type": "integer", "example": 2 }, "mpans": { "type": "array", "description": "The unique identification numbers of the meters associated with the meter point. Note that these are not guaranteed to return and will be redected to leave the last 3 digits only when they do. The MpanCount will always report the true number.", "example": [ "**********273", "**********231" ], "items": { "type": "string" } }, "mprnCount": { "type": "integer", "description": "The number of gas meters associated with the meter point", "example": 1 }, "mprns": { "type": "array", "description": "The unique identification numbers of the meters associated with the meter point. Note that these are not guaranteed to return. The MprnCount will always report the true number.", "items": { "type": "string", "example": "*****001" } } } }, "MeterSearchRequest": { "required": [ "callerIdentification" ], "type": "object", "properties": { "callerIdentification": { "$ref": "#/components/schemas/CallerIdentification" }, "meterAddressId": { "type": "string" }, "mpan": { "type": "string" }, "mprn": { "type": "string" } } }, "MeterPointLocation": { "type": "object", "properties": { "addressLine1": { "type": "string" }, "addressLine2": { "type": "string" }, "addressLine3": { "type": "string" }, "addressLine4": { "type": "string" }, "addressLine5": { "type": "string" }, "addressLine6": { "type": "string" }, "addressLine7": { "type": "string" }, "addressLine8": { "type": "string" }, "addressLine9": { "type": "string" }, "deliveryPointAlias": { "type": "string" }, "subBuilding": { "type": "string" }, "buildingName": { "type": "string" }, "buildingNumber": { "type": "string" }, "dependentThoroughfare": { "type": "string" }, "thoroughfare": { "type": "string" }, "dependentLocality": { "type": "string" }, "locality": { "type": "string" }, "administrativeArea": { "type": "string" }, "postCode": { "type": "string" }, "fullAddress": { "type": "string" } } }, "Supplier": { "type": "object", "properties": { "mpid": { "type": "string" }, "shortCode": { "type": "string" }, "name": { "type": "string" }, "effectiveDate": { "type": "string", "format": "yyyy-MM-dd" }, "powwrId": { "type": "string" } } }, "ElectricMeter": { "type": "object", "properties": { "meterPointLocation": { "$ref": "#/components/schemas/MeterPointLocation" }, "mpan": { "type": "string" }, "gspId": { "type": "string" }, "energisationStatus": { "type": "string" }, "energisationStatusEffectiveDate": { "type": "string", "format": "yyyy-MM-dd" }, "profileClass": { "type": "string" }, "meterTimeswitchClass": { "type": "string" }, "lineLossFactor": { "type": "string" }, "standardSettlementConfiguration": { "type": "string" }, "measurementClass": { "type": "string" }, "isDomesticConsumer": { "type": "boolean" }, "serialNumber": { "type": "string" }, "meterType": { "type": "string" }, "currentSupplierName": { "type": "string", "description": "Note that this field is deprecated and will be removed in a future release. Please use Current Supplier field." }, "currentSupplier": { "$ref": "#/components/schemas/Supplier" }, "annualConsumption": { "type": "integer" }, "greenDealStatus": { "type": "string", "enum": [ "Active", "Expired", "None", "Pending" ] }, "tradingStatus": { "type": "string", "description": "N/R/T/X" }, "smetsVersion": { "type": "string" }, "additionalInformation": { "type": "object", "description": "Dictionary of key-value pairs" } } }, "GasMeter": { "type": "object", "properties": { "meterPointLocation": { "$ref": "#/components/schemas/MeterPointLocation" }, "mprn": { "type": "string" }, "isIGT": { "type": "boolean" }, "ldz": { "type": "string" }, "exitZone": { "type": "string" }, "serialNumber": { "type": "string" }, "meterType": { "type": "string" }, "meterCapacity": { "type": "integer" }, "meterMechanismCode": { "type": "string" }, "dailyMeteredQuantity": { "type": "integer" }, "currentSupplierName": { "type": "string", "description": "Note that this field is deprecated and will be removed in a future release. Please use Current Supplier field." }, "currentSupplier": { "$ref": "#/components/schemas/Supplier" }, "incomingSupplier": { "$ref": "#/components/schemas/Supplier" }, "annualConsumption": { "type": "integer" }, "additionalInformation": { "type": "object", "description": "Dictionary of key-value pairs" }, "meterModel": { "type": "string" } } }, "MeterSearchResults": { "type": "object", "properties": { "electricMeters": { "type": "array", "example": [ { "mpan": "1610028163273", "gspId": "_G", "energisationStatus": "E", "energisationStatusEffectiveDate": "2024-02-14", "profileClass": "03", "meterTimeswitchClass": "801", "lineLossFactor": "631", "standardSettlementConfiguration": "0393", "measurementClass": "A", "isDomesticConsumer": false, "serialNumber": "D07W551948", "meterType": "N", "currentSupplierName": "", "currentSupplier": { "mpid": "ENRD", "name": "British Gas Business", "effectiveDate": "2024-02-14", "powwrId": "BRITISHG-001-S" }, "annualConsumption": 12345, "meterPointLocation": { "fullAddress": "1ST FLOOR EAST WING, PARKWAY HOUSE, PALATINE ROAD, MANCHESTER, LANCASHIRE, M22 4DB", "AddressLine1": "", "AddressLine2": "1ST FLOOR EAST WING", "AddressLine3": "PARKWAY HOUSE", "AddressLine4": "", "AddressLine5": "PALATINE ROAD", "AddressLine6": "", "AddressLine7": "", "AddressLine8": "MANCHESTER", "AddressLine9": "LANCASHIRE", "Postcode": "M22 4DB" }, "greenDealStatus": "Active", "tradingStatus": "T", "smetsVersion": "SMETS1", "additionalInformation": { "dataAggregatorMpid": "ACCU", "dataCollectorMpid": "ACCU", "meterOperatorMpid": "OESL" } }, { "mpan": "1620000546231", "gspId": "_G", "energisationStatus": "E", "energisationStatusEffectiveDate": "2024-02-14", "profileClass": "04", "meterTimeswitchClass": "874", "lineLossFactor": "661", "standardSettlementConfiguration": "0151", "measurementClass": "A", "isDomesticConsumer": false, "serialNumber": "212397267", "meterType": "RCAMY", "currentSupplierName": "", "currentSupplier": { "mpid": "ENRD", "name": "British Gas Business", "effectiveDate": "2024-02-14", "powwrId": "BRITISHG-001-S" }, "annualConsumption": 12345, "meterPointLocation": { "fullAddress": "1ST FLOOR EAST WING, PARKWAY HOUSE, PALATINE ROAD, MANCHESTER, LANCASHIRE, M22 4DB", "AddressLine1": "", "AddressLine2": "1ST FLOOR EAST WING", "AddressLine3": "PARKWAY HOUSE", "AddressLine4": "", "AddressLine5": "PALATINE ROAD", "AddressLine6": "", "AddressLine7": "", "AddressLine8": "MANCHESTER", "AddressLine9": "LANCASHIRE", "Postcode": "M22 4DB" }, "greenDealStatus": "Active", "tradingStatus": "T", "smetsVersion": "SMETS2", "additionalInformation": { "dataAggregatorMpid": "ACCU", "dataCollectorMpid": "ACCU", "meterOperatorMpid": "OESL" } } ], "items": { "$ref": "#/components/schemas/ElectricMeter" } }, "gasMeters": { "type": "array", "example": [ { "mprn": "14097001", "isIGT": false, "exitZone": "NW2", "ldz": "NW", "serialNumber": "M040K0283013D6", "meterType": "Synthetic", "meterCapacity": 6, "meterMechanismCode": "CR", "dailyMeteredQuantity": 100, "currentSupplierName": "Scottish Power Energy Retail Limited", "currentSupplier": { "shortCode": "SCT", "name": "Scottish Power", "effectiveDate": "2022-03-20", "powwrId": "SCOTTISH-001-S" }, "incomingSupplier": { "shortCode": "EOD", "name": "E.On Next", "powwrId": "EONNEXT-001-S", "effectiveDate": "2024-03-18" }, "annualConsumption": 54321, "meterPointLocation": { "subBuilding": "", "buildingName": "PARKWAY HOUSE", "buildingNumber": "", "dependentThoroughfare": "", "thoroughfare": "PALATINE ROAD", "dependentLocality": "", "locality": "MANCHESTER", "postCode": "M22 4DB", "fullAddress": "PARKWAY HOUSE, PALATINE ROAD, MANCHESTER, M22 4DB," }, "additionalInformation": { "amrIndicator": "N", "meterDeviceStatus": "LI", "meterNumberOfDials": "05", "previousSupplierName": "Octopus Energy Limited" } } ], "items": { "$ref": "#/components/schemas/GasMeter" } } } }, "CallerIdentification": { "required": [ "organisationPowwrId" ], "type": "object", "properties": { "organisationPowwrId": { "pattern": "^[A-Z0-9]{1,8}-\\d{3}-[SB]$", "type": "string" }, "applicationId": { "type": "string", "description": "An optional string to identify which of your backend services made the call which can be shown in usage reports.", "nullable": true, "example": "mySystemName" }, "userId": { "type": "string", "description": "An optional string to identify the user in your system that initiated the call which call be shown in usage reports.", "nullable": true, "example": "user@myorg.com" } }, "description": "Information used for logging and billing. The organisationPowwrId is required and validated against authentication. ApplicationId and UserId are optional, but can be used to support logging and reporting" }, "ProblemDetailsRfc7807": { "type": "object", "properties": { "type": { "type": "string", "example": "https://httpstatuses.com/400" }, "title": { "type": "string", "example": "Bad Request" }, "status": { "type": "integer", "example": 400 }, "detail": { "type": "string", "example": "Error validating request against JSON Schema for type AddressSearchRequest." }, "extensions": { "$ref": "#/components/schemas/ProblemDetailsRfc7807_extensions" } } }, "Issue": { "required": [ "description" ], "type": "object", "properties": { "entity": { "type": "string", "enum": [ "MeterSearchRequest", "AddressSearchRequest" ] }, "description": { "type": "string", "example": "Schema Error: (2, 18) StringExpected" }, "type": { "type": "string", "example": "ValueIsInvalid", "enum": [ "UnexpectedProperty", "ValueIsMissing", "ValueIsInvalid" ] }, "properties": { "type": "array", "items": { "$ref": "#/components/schemas/EntityProperty" } } }, "description": "An issue with the request or deal" }, "EntityProperty": { "required": [ "path" ], "type": "object", "properties": { "path": { "type": "string", "description": "The path to the property in the request object hierarchy", "example": "$.postCode" }, "providedValue": { "type": "object", "example": 123 } } }, "ProblemDetailsRfc7807_extensions": { "type": "object", "properties": { "errors": { "type": "array", "items": { "$ref": "#/components/schemas/Issue" } }, "warnings": { "type": "array", "items": { "$ref": "#/components/schemas/Issue" } } } } }, "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "name": "apiKey", "in": "header" } } } }