Skip to main content

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.
  • 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.

Request body:

  • None.

Response​

Success:

  • 200 OK
  • Body type: List[dict]

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
    },
    "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"
    }
  }
]

Notes:

  • request_data is polymorphic. Its shape depends on the matched request_type.
  • 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.

Field-level constraints: