API Reference

UK Utility Reporter exposes two API channels. The Public API requires no authentication and is suitable for reading live report data. The Company API (v1) is authenticated and gives registered utility companies full read/write access to reports in their coverage area.

All responses are JSON. All timestamps are Unix milliseconds.

https://ukutilityreporter.co.uk

Authentication — Company API Include your API key in the request header on every v1 call:
X-API-Key: utl-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Keys are issued when you register at /portal. Known utility company domains are auto-approved after email verification. Other domains are reviewed manually — usually within 24 hours.

Public API No auth required

GET

/api/reports

List all active reports. Suitable for maps, dashboards, or integrations.

Query parameters

Name	Type	Description
type	string	Filter by type: water, gas, electricity, telecoms, roads, flooding, sewage, fire, ufo, cropcircle. Comma-separate for multiple: `?type=ufo,cropcircle`
status	string	Filter by status: reported, acknowledged, resolved. Omit for active only.
since	number	Unix ms — return only reports submitted after this time
limit	number	Max results (default 200, max 500)

Response

{
  "ok": true,
  "count": 12,
  "reports": [
    {
      "id": "mptx4ldjajmb",
      "ref": "UTL-PDS163",
      "type": "electricity",
      "severity": "urgent",          // routine | urgent | emergency
      "postcode": "NG1 5AA",
      "address": "Market Square, Nottingham",
      "lat": 52.954,
      "lon": -1.15,
      "description": "Streetlights out on three consecutive lamp posts",
      "status": "acknowledged",       // reported | acknowledged | resolved
      "affected_count": 4,
      "submitted_at": 1748880000000,  // Unix ms
      "expires_at":   1749052800000,
      "resolved_at":  null,
      "photo_url": "https://ukutilityreporter.co.uk/photos/mptx4ldjajmb",
      "company_name": "Vantage Utilities",
      "map_url": "https://ukutilityreporter.co.uk/?report=UTL-PDS163",
      "evidence_url": null,             // UFO/UAP: YouTube/TikTok/social link; null otherwise
      "diameter": null                  // Crop circle: formation diameter in metres; null otherwise
    }
  ]
}

GET

/api/reports/{id}

Single report with full details and any company updates.

Response

{
  "ok": true,
  "report": { /* same shape as list item */ },
  "updates": [
    {
      "id": "upd_abc123",
      "company_name": "Vantage Utilities",
      "message": "Engineers on site — estimated 2 hours to repair.",
      "is_emergency": false,
      "posted_at": 1748890000000
    }
  ]
}

GET

/api/reports/{id}/updates

Company updates for a single report.

Response

{
  "ok": true,
  "updates": [ { "id", "company_name", "message", "is_emergency", "posted_at" } ]
}

GET

/api/routing

Resolve which utility company covers a given postcode and issue type.

Query parameters

Name	Type	Description
postcode	string	UK postcode — full or district (e.g. NG1 or NG1 5AA)
type	string	Issue type (water, gas, electricity, telecoms, roads)

Response

{
  "ok": true,
  "routing": {
    "company_key": "vantage",
    "name": "Vantage Utilities",
    "email": "faults@vantage.example.com",
    "phone": "0800 000 0000"
  }
}

POST

/api/reports/{id}/affected

Increment the affected count for a report. Deduplicated per IP per report (7 days).

Response

{ "ok": true }
// or if already counted:
{ "ok": true, "already": true }

PATCH

/api/reports/{id}/resolve

Mark a report resolved (removes it from the public map). Rate limited — 5 per IP per hour.

Response

{ "ok": true, "resolved": true }

DELETE

/api/reports/{id}/photo

Remove an inappropriate photo from a report. Shares the resolve rate limit (5 per IP per hour).

Response

{ "ok": true }
// or if already removed:
{ "ok": true, "already": true }

Company API — v1 X-API-Key required

GET

/api/v1/ping

Health check. Confirms your API key is valid and returns your company details.

Response

{
  "ok": true,
  "company": "Vantage Utilities",
  "company_key": "vantage",
  "coverage": "DE, LE, NG"
}

GET

/api/v1/reports

List all reports routed to your company. Includes private customer data when provided by the reporter.

Query parameters

Name	Type	Description
status	string	reported \| acknowledged \| resolved \| all (default: all)
type	string	Filter by issue type
since	number	Unix ms — reports submitted after this time
limit	number	Max results (default 200, max 500)

Response

{
  "ok": true,
  "company": "Vantage Utilities",
  "company_key": "vantage",
  "since": 0,
  "count": 3,
  "reports": [
    {
      "id": "mptx4ldjajmb",
      "ref": "UTL-PDS163",
      "type": "electricity",
      "severity": "urgent",
      "postcode": "NG1 5AA",
      "address": "Market Square, Nottingham",
      "lat": 52.954,
      "lon": -1.15,
      "description": "Streetlights out on three consecutive lamp posts",
      "status": "acknowledged",
      "affected_count": 4,
      "email_sent": true,
      "submitted_at": 1748880000000,
      "expires_at": 1749052800000,
      "resolved_at": null,
      "photo_url": "https://ukutilityreporter.co.uk/photos/mptx4ldjajmb",
      "map_url": "https://ukutilityreporter.co.uk/?report=UTL-PDS163",
      "customer": {
        "name": "Jane Smith",
        "phone": "07700900000",
        "account_ref": "ACC-12345",
        "tech_ref": "1012345678901",   // MPAN, MPRN, or SPID
        "wants_contact": true,
        "customer_contacted": false
      }
      // customer is null if reporter did not provide contact details
    }
  ]
}

Privacy: The customer object is never included in the public API — only authenticated company API responses.

PATCH

/api/v1/reports/{id}/status

Update a report's status. The new status is shown immediately on the public map popup.

Request body

{ "status": "acknowledged" }   // reported | acknowledged | resolved

Response

{ "ok": true }

Note: Setting status to resolved marks the report for expiry — it will be removed from the public map within 24 hours.

POST

/api/v1/reports/{id}/updates

Post a public update on a report. Visible immediately on the map popup to everyone nearby.

Request body

{
  "message": "Engineers on site — estimated repair time 2 hours.",
  "is_emergency": false    // true = red Emergency Notice banner on popup
}

Response

{
  "ok": true,
  "update": {
    "id": "upd_abc123",
    "message": "Engineers on site — estimated repair time 2 hours.",
    "is_emergency": false,
    "posted_at": 1748890000000
  }
}

Limit: Messages are capped at 500 characters.

DELETE

/api/v1/reports/{id}/updates/{updateId}

Delete one of your company's updates from a report.

Response

{ "ok": true }

DELETE

/api/v1/reports/{id}/photo

Remove a photo from one of your reports. Deletes permanently from storage.

Response

{ "ok": true }
// or if no photo exists:
{ "ok": true, "already": true }

PATCH

/api/v1/reports/{id}/contacted

Mark whether a customer has been contacted. Updates the badge state in the portal dashboard.

Request body

{ "contacted": true }

Response

{ "ok": true, "contacted": true }

GET

/api/v1/settings

Get your company's notification preferences.

Response

{
  "ok": true,
  "settings": {
    "notify_new_reports": true   // email alert on new report routed to your company
  }
}

PATCH

/api/v1/settings

Update your company's notification preferences.

Request body

{ "notify_new_reports": false }

Response

{ "ok": true }

Rate limits

Report submission5 per IP per hour

Remove / flag photo5 per IP per hour (shared)

Company registration3 per IP per day

Company API (v1)No rate limit (authenticated)

Rate-limited responses return HTTP 429 with {"ok":false,"error":"..."}.

Errors

All error responses use standard HTTP status codes and the same JSON envelope:

{ "ok": false, "error": "Description of what went wrong." }

Status	Meaning
400	Bad request — missing or invalid parameter
401	Missing or invalid API key
403	API key valid but not authorised for this report
404	Report or resource not found
409	Duplicate — similar report already submitted from this location
429	Rate limit exceeded

Looking for utility phone numbers and email addresses? See the 🔌 Utility Contact Directory →

Questions, integration help, or feature requests — hello@ukutilityreporter.co.uk