GET /requests/v1/{mpid}

Searches supplier processes and returns process metadata plus typed request_data for each matched process.

Request

Method and path:

• GET /requests/v1/{mpid}

Headers:

• X-API-KEY (required): string, API key in UUID format.

Path parameters:

• mpid (required): string supplier MPID.

Query parameters:

• mpan_id (optional): integer MPAN core filter.
• request_id (optional): UUID process identifier.
• request_type (optional): string process type filter.
• request_status (optional): string process status filter. Use one or more comma-separated values: Pending, Success, Failed.
• start_date (optional): parseable date or datetime string. If only a date is provided, 00:00:00 is applied.
• end_date (optional): parseable date or datetime string. If only a date is provided, 23:59:59 is applied. If omitted, it defaults to the current day at 23:59:59.
• show_messages (optional): boolean, default false. When true, message fields are included for request types that provide them.
• page (optional): integer, minimum 1. Must be provided with page_size.
• page_size (optional): integer, minimum 1, maximum 200. Must be provided with page.
• sort_direction (optional): string, either asc or desc. Defaults to desc.

Request body:

• None.

Response

Success:

• 200 OK
• Body type: List[dict] when pagination is not requested.
• Body type: paginated response object when page and page_size are provided.

Unpaginated responses return a list. Each item has this top-level shape:

[
  {
    "metadata": {
      "request_id": "72f30f06-afcc-4ad8-8c1f-78e556ea9cbc",
      "request_type": "consumption-amendment",
      "request_status": "Pending",
      "initiated_by": null,
      "description": "Consumption Amendment Process",
      "created_at": "2026-03-11T14:04:22+00:00",
      "last_updated_at": "2026-03-11T14:04:22+00:00",
      "mpan_core": 1234567890123,
      "errors": []
    },
    "request_data": {
      "supplier_reference": "CA-2026-0001",
      "period_start_date": "2026-02-01T00:00:00+00:00",
      "period_end_date": "2026-02-29T00:00:00+00:00",
      "measurement_quantity_id": "AI",
      "gross_revised_consumption": "3500.125",
      "reason_code": "A"
    }
  }
]

Paginated responses wrap the same items in data and include pagination details:

{
  "data": [
    {
      "metadata": {
        "request_id": "72f30f06-afcc-4ad8-8c1f-78e556ea9cbc",
        "request_type": "change-of-supplier",
        "request_status": "Failed",
        "initiated_by": null,
        "description": "Change of Supplier Process",
        "created_at": "2026-03-11T14:04:22+00:00",
        "last_updated_at": "2026-03-11T14:05:11+00:00",
        "mpan_core": 1234567890123,
        "errors": [
          {
            "code": "COS_CSS2380_REJECTED",
            "title": "Change of supplier rejected",
            "message": "The change of supplier request was rejected during CSS validation.",
            "severity": "ERROR",
            "details": {
              "response_code": "R",
              "message_type": "CSS2380"
            }
          }
        ]
      },
      "request_data": {
        "supply_start_date": "2026-03-20T00:00:00+00:00",
        "domestic_indicator": true
      }
    }
  ],
  "pagination": {
    "page": 1,
    "page_size": 10,
    "total_count": 25
  }
}

Notes:

• request_data is polymorphic. Its shape depends on the matched request_type.
• metadata.errors is always returned as an array. It is empty when no alerts have been recorded for the request.
• The route currently maps at least these request types: 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, and consumption-amendment.
• For metering-changes, show_messages does not change the wrapper shape.

Bad request case:

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

Field-level constraints:

• Schema Reference