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	One or more comma-separated values: Pending, Success, Failed
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
page	Query	No	integer	Minimum 1; must be provided with page_size
page_size	Query	No	integer	Minimum 1, maximum 200; must be provided with page
sort_direction	Query	No	string(enum)	asc or desc; defaults to desc

Search Response Shape

Without pagination, 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
metadata.errors	Yes	array	Empty array when the request has no recorded alerts
request_data	Yes	object	Shape depends on request_type

When page and page_size are provided, the endpoint returns a paginated wrapper:

Field	Required	Type	Format / Constraints
data	Yes	array	List of matching request records using the item shape above
pagination	Yes	object	Pagination metadata
pagination.page	Yes	integer	Requested page number
pagination.page_size	Yes	integer	Requested page size
pagination.total_count	Yes	integer	Total number of matching records across all pages

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
errors	Yes	array of alert objects	Empty array when no alerts have been recorded

Alert Error Schema

Alerts are returned in metadata.errors.

Field	Required	Type	Format / Constraints
code	Yes	string	Alert code
title	Yes	string	Short alert title
message	Yes	string	User-facing alert message
severity	Yes	string	Alert severity
details	No	object or null	Additional alert details when available

Bad Request Cases

The endpoint returns 400 when:

• start_date or end_date cannot be parsed.
• Only one of page or page_size is provided.
• sort_direction is not asc or desc.
• request_status contains unsupported values.
• request_status only contains empty comma-separated tokens.