Requests Status Schema Reference

Headers and Parameters

Field	Location	Required	Type	Format / Constraints
X-API-KEY	Header	Yes	string	UUID format
mpid	Path	Yes	string	Supplier MPID
mpan_id	Query	No	integer	MPAN core filter
request_id	Query	No	string	UUID filter
request_type	Query	No	string	Process type name filter
request_status	Query	No	string	Process status filter
start_date	Query	No	string	Parseable date or datetime; date-only values use 00:00:00
end_date	Query	No	string	Parseable date or datetime; date-only values use 23:59:59
show_messages	Query	No	boolean	Defaults to false

Search Response Shape

The endpoint returns List[dict]. Each list item has this common structure:

Field	Required	Type	Format / Constraints
metadata	Yes	object	Process metadata object
metadata.request_id	Yes	string	UUID
metadata.request_type	Yes	string	Process type name
metadata.request_status	Yes	string(enum)	Pending, Success, Failed
metadata.initiated_by	No	string or null	Initiator identifier
metadata.description	No	string or null	Process description
metadata.created_at	Yes	string(datetime)	ISO 8601 datetime
metadata.last_updated_at	Yes	string(datetime)	ISO 8601 datetime
metadata.mpan_core	Yes	integer	MPAN core
request_data	Yes	object	Shape depends on request_type

Request Data Variants Used by This Route

These request_type values are currently supported:

• traditional-transfer-of-reads
• change-of-supplier
• loss-of-supplier
• change-of-reg-details
• smart-transfer-of-reads
• data-service-appointment
• metering-service-appointment
• contact-details-update
• annual-consumption-change
• disconnection-request
• psr-details
• change-of-energisation
• metering-changes
• consumption-amendment

show_messages=true includes message fields for request types that provide them.

Common Metadata Schema

Field	Required	Type	Format / Constraints
request_id	Yes	string	UUID
request_type	Yes	string	Process type name
request_status	Yes	string(enum)	Pending, Success, Failed
initiated_by	No	string or null	Optional
description	No	string or null	Optional
created_at	Yes	string(datetime)	ISO 8601 datetime
last_updated_at	Yes	string(datetime)	ISO 8601 datetime
mpan_core	Yes	integer	MPAN core