MPAN Schema Reference
This page summarizes the request and response contract for MPAN API endpoints.
Constraint notation:
- "Not specified" means no explicit min/max/pattern constraint is documented for the endpoint response/request schema.
- MPAN values are represented as 13-digit numbers in API requests and responses.
Request Parameters
| Field | Location | Required | Type | Length / Format | Notes |
|---|---|---|---|---|---|
X-API-KEY | Header | Yes | string | UUID format | Authentication header required for both endpoints. |
mpid | Path | Yes | string | Not specified | Supplier MPID used for tenant/supplier authorization checks. |
mpan_id | Query (GET /mpan/v1/{mpid}) | Yes | integer | 13 digits | MPAN core identifier. |
List Response Schema (MpanResponseSchema)
Top-level
| Field | Required | Type | Length / Format | Notes |
|---|---|---|---|---|
mpans | Yes | array of MpanResponseSchemaBase | N/A | Empty list is returned when no MPANs exist. |
Item schema: MpanResponseSchemaBase
| Field | Required | Type | Length / Format | Notes |
|---|---|---|---|---|
id | Yes | integer | 13 digits | MPAN core. |
address_line_1 | No | string or null | Not specified | Address line 1. |
address_line_2 | No | string or null | Not specified | Address line 2. |
address_line_3 | No | string or null | Not specified | Address line 3. |
address_line_4 | No | string or null | Not specified | Address line 4. |
address_line_5 | No | string or null | Not specified | Address line 5. |
address_line_6 | No | string or null | Not specified | Address line 6. |
address_line_7 | No | string or null | Not specified | Address line 7. |
address_line_8 | No | string or null | Not specified | Address line 8. |
address_line_9 | No | string or null | Not specified | Address line 9. |
postcode | No | string or null | Not specified | Metering point postcode. |
registration_id | No | string(UUID) or UUID or null | UUID (typically 36 characters when serialized as string) | CSS registration identifier. |
supply_start_date | No | string(datetime) or null | ISO 8601 datetime | Supply effective from date. |
registration_status | No | string or null | Enum values: Pending, Confirmed, Cancelled, SecuredActive, SecuredInactive, Active, Inactive | Current registration status. |
Single MPAN Response Schema (MpanSchema)
Base fields (MpanSchemaBase)
| Field | Required | Type | Length / Format | Notes |
|---|---|---|---|---|
id | Yes | integer | 13 digits | MPAN core. |
address_line_1 | No | string or null | Not specified | Address line 1. |
address_line_2 | No | string or null | Not specified | Address line 2. |
address_line_3 | No | string or null | Not specified | Address line 3. |
address_line_4 | No | string or null | Not specified | Address line 4. |
address_line_5 | No | string or null | Not specified | Address line 5. |
address_line_6 | No | string or null | Not specified | Address line 6. |
address_line_7 | No | string or null | Not specified | Address line 7. |
address_line_8 | No | string or null | Not specified | Address line 8. |
address_line_9 | No | string or null | Not specified | Address line 9. |
postcode | No | string or null | Not specified | Metering point postcode. |
gsp_group_id | No | string or null | Not specified | GSP Group identifier. |
distributor_dip_id | No | string or null | Not specified | Distributor DIP ID. |
distributor_mpid | No | string or null | Max length 4 | Distributor MPID. |
domestic_indicator | No | boolean or null | N/A | Domestic premise indicator. |
domestic_indicator_efd | No | string(datetime) or null | ISO 8601 datetime | Domestic indicator effective from date. |
energy_direction | No | string or null | Not specified | Energy direction code/value. |
metered_indicator | No | boolean or null | N/A | Metered indicator. |
duos_tariff_id | No | string or null | Not specified | DUoS tariff identifier. |
duos_tariff_efd | No | string(datetime) or null | ISO 8601 datetime | DUoS tariff effective from date. |
energisation_status | No | string or null | Not specified | Energisation status. |
energisation_status_efd | No | string(datetime) or null | ISO 8601 datetime | Energisation status effective from date. |
connection_type_indicator | No | string(enum) or null | Enum: W, L, H, E, U | Connection type indicator. |
connection_type_indicator_efd | No | string(datetime) or null | ISO 8601 datetime | Connection type effective from date. |
market_segment | No | string or null | Not specified | Market segment indicator. |
market_segment_efd | No | string(datetime) or null | ISO 8601 datetime | Market segment effective from date. |
annual_consumption | No | string or null | Not specified | Annual consumption value as stored. |
annual_consumption_efd | No | string(datetime) or null | ISO 8601 datetime | Annual consumption effective from date. |
annual_consumption_quality_indicator | No | string(enum) or null | Enum: A, 1, 2, 3, 4, 5, D | Quality indicator for annual consumption. |
metering_service_dip_id | No | string or null | Not specified | Current metering service DIP ID. |
metering_service_mpid | No | string or null | Not specified | Current metering service MPID. |
metering_service_efd | No | string(datetime) or null | ISO 8601 datetime | Metering service effective from date. |
metering_service_etd | No | string(datetime) or null | ISO 8601 datetime | Metering service effective to date. |
data_service_dip_id | No | string or null | Not specified | Current data service DIP ID. |
data_service_mpid | No | string or null | Not specified | Current data service MPID. |
data_service_efd | No | string(datetime) or null | ISO 8601 datetime | Data service effective from date. |
data_service_etd | No | string(datetime) or null | ISO 8601 datetime | Data service effective to date. |
mdr_dip_id | No | string or null | Not specified | Meter data retriever DIP ID. |
mdr_mpid | No | string or null | Not specified | Meter data retriever MPID. |
mdr_efd | No | string(datetime) or null | ISO 8601 datetime | Meter data retriever effective from date. |
customer_direct_contract_metering_service | No | boolean or null | N/A | Customer direct contract metering service flag. |
customer_direct_contract_metering_service_mpid | No | string or null | Not specified | Customer contracted metering service MPID. |
customer_direct_contract_metering_service_dip_id | No | string or null | Not specified | Customer contracted metering service DIP ID. |
customer_direct_contract_metering_service_efd | No | string(datetime) or null | ISO 8601 datetime | Customer contracted metering service effective from date. |
customer_direct_contract_metering_service_etd | No | string(datetime) or null | ISO 8601 datetime | Customer contracted metering service effective to date. |
customer_direct_contract_data_service | No | boolean or null | N/A | Customer direct contract data service flag. |
customer_direct_contract_data_service_mpid | No | string or null | Not specified | Customer contracted data service MPID. |
customer_direct_contract_data_service_dip_id | No | string or null | Not specified | Customer contracted data service DIP ID. |
customer_direct_contract_data_service_efd | No | string(datetime) or null | ISO 8601 datetime | Customer contracted data service effective from date. |
customer_direct_contract_data_service_etd | No | string(datetime) or null | ISO 8601 datetime | Customer contracted data service effective to date. |
dcc_service_flag | No | string or null | Not specified | DCC service flag. |
dcc_service_flag_efd | No | string(datetime) or null | ISO 8601 datetime | DCC service flag effective from date. |
ihd_install_status | No | string or null | Not specified | IHD install status. |
ihd_install_status_efd | No | string(datetime) or null | ISO 8601 datetime | IHD install status effective from date. |
smso_id | No | string or null | Not specified | SMSO identifier. |
smso_id_efd | No | string(datetime) or null | ISO 8601 datetime | SMSO effective from date. |
profile_class | No | string or null | Not specified | Profile class. |
profile_class_efd | No | string(datetime) or null | ISO 8601 datetime | Profile class effective from date. |
ssc | No | string or null | Not specified | SSC value. |
ssc_efd | No | string(datetime) or null | ISO 8601 datetime | SSC effective from date. |
registration_id | No | UUID or null | UUID (36 characters when serialized) | CSS registration ID. |
registration_status_efd | No | string(datetime) or null | ISO 8601 datetime | Registration status effective from date. |
supplier_mpid | No | string or null | Not specified | Supplier MPID associated to MPAN record. |
registration_status | No | string or null | Enum values: Pending, Confirmed, Cancelled, SecuredActive, SecuredInactive, Active, Inactive | Registration status. |
supply_start_date | No | string(datetime) or null | ISO 8601 datetime | Supply start date. |
supply_end_date | No | string(datetime) or null | ISO 8601 datetime | Supply end date. |
consent_granularity | No | string or null | Not specified | Consent granularity value. |
consent_granularity_efd | No | string(datetime) or null | ISO 8601 datetime | Consent granularity effective from date. |
measurement_class_id | No | string or null | Not specified | Measurement class identifier. |
Additional fields on MpanSchema
| Field | Required | Type | Length / Format | Notes |
|---|---|---|---|---|
updated | Yes | string(datetime) | ISO 8601 datetime | Last updated timestamp for the MPAN record. |
related_mpans | No | object or null | See nested shape below | Related MPAN relationships (if any). |
linked_mpans | No | object or null | See nested shape below | Linked import/export MPAN relationships (if any). |
migration_statuses | Yes | array of MigrationStatusSchema | N/A | Defaults to [] if no migration statuses. |
related_mpans nested object
| Field | Required | Type | Length / Format | Notes |
|---|---|---|---|---|
primary_mpan | Yes (when object present) | integer | 13 digits | MPAN returned by query. |
secondary_mpans | Yes (when object present) | array | N/A | Related secondary MPAN records. |
secondary_mpans[].mpan_core | Yes | integer | 13 digits | Related MPAN core. |
secondary_mpans[].effective_from | Yes | string(datetime) | ISO 8601 datetime | Relationship start datetime. |
secondary_mpans[].effective_to | No | string(datetime) or null | ISO 8601 datetime | Relationship end datetime. |
linked_mpans nested object
| Field | Required | Type | Length / Format | Notes |
|---|---|---|---|---|
import_mpan | Yes (when object present) | integer | 13 digits | Import MPAN core. |
import_supplier_mpid | Yes (when object present) | string | Not specified | Supplier MPID for import MPAN. |
export_mpans | Yes (when object present) | array | N/A | Linked export MPAN records. |
export_mpans[].mpan_core | Yes | integer | 13 digits | Export MPAN core. |
export_mpans[].effective_from | Yes | string(datetime) | ISO 8601 datetime | Relationship start datetime. |
export_mpans[].effective_to | No | string(datetime) or null | ISO 8601 datetime | Relationship end datetime. |
export_mpans[].export_supplier_mpid | Yes | string | Not specified | Supplier MPID for export MPAN. |
Migration Status Schema (MigrationStatusSchema)
| Field | Required | Type | Length / Format | Notes |
|---|---|---|---|---|
type | Yes | string(enum) | Enum: forward, reverse | Migration direction. |
mhhs_regime_end_date | No | string(datetime) or null | ISO 8601 datetime | MHHS regime end date. |
outgoing_metering_service_dip_id | No | string or null | Not specified | Outgoing metering service DIP ID. |
outgoing_metering_service_mpid | No | string or null | Not specified | Outgoing metering service MPID. |
outgoing_metering_service_effective_from_date | No | string(datetime) or null | ISO 8601 datetime | Outgoing metering service start. |
outgoing_metering_service_effective_to_date | No | string(datetime) or null | ISO 8601 datetime | Outgoing metering service end. |
outgoing_metering_service_deappointment_reason_code | No | string or null | Not specified | Deappointment reason. |
outgoing_data_service_dip_id | No | string or null | Not specified | Outgoing data service DIP ID. |
outgoing_data_service_mpid | No | string or null | Not specified | Outgoing data service MPID. |
outgoing_data_service_effective_from_date | No | string(datetime) or null | ISO 8601 datetime | Outgoing data service start. |
outgoing_data_service_effective_to_date | No | string(datetime) or null | ISO 8601 datetime | Outgoing data service end. |
outgoing_data_service_deappointment_reason_code | No | string or null | Not specified | Deappointment reason. |
incoming_mop_mpid | No | string or null | Not specified | Incoming MOP MPID. |
incoming_mop_effective_from_date | No | string(datetime) or null | ISO 8601 datetime | Incoming MOP start. |
incoming_dc_mpid | No | string or null | Not specified | Incoming DC MPID. |
incoming_dc_effective_from_date | No | string(datetime) or null | ISO 8601 datetime | Incoming DC start. |
incoming_supplier_mpid | Yes | string | Not specified | Incoming supplier MPID. |
incoming_supplier_dip_id | Yes | string | Not specified | Incoming supplier DIP ID. |
incoming_supplier_effective_from_date | Yes | string(datetime) | ISO 8601 datetime | Incoming supplier start date. |
old_supplier_mpid | No | string or null | Not specified | Previous supplier MPID. |
old_data_aggregator_mpid | No | string or null | Not specified | Previous DA MPID. |
old_data_aggregator_type | No | string or null | Not specified | Previous DA type. |
old_data_collector_mpid | No | string or null | Not specified | Previous DC MPID. |
old_data_collector_type | No | string or null | Not specified | Previous DC type. |
old_meter_operator_mpid | No | string or null | Not specified | Previous MOP MPID. |
old_meter_operator_type | No | string or null | Not specified | Previous MOP type. |