API Catalog & Developer Docs

The demonstrable integration surface: read-only REST endpoints with API-key authentication, an import/export inventory, and honest capability statements for MultiSpeak and vendor adapters.

Authentication

All endpoints require an API key — the key is managed server-side and never exposed to browser code

Header: x-api-key: <project DEMO_API_KEY secret>

Keys are issued from Project Settings → Secrets and verified server-side with a constant-time comparison. The in-app “Try it” buttons below call through a server function so no key ever reaches the browser. Missing or invalid keys return 401.

curl -H "x-api-key: $DEMO_API_KEY" \
  "https://<host>/api/public/v1/accounts?limit=25&accountNumber=5000"

REST endpoints (read-only, demonstrable today)

Synthetic dataset only — every response carries a disclosure field

GET/api/public/v1/accounts

List synthetic accounts with customer and service-address context.

Params: limit (≤100), offset, accountNumber

Response schema: { data: [{ id, accountNumber, accountClass, status, currentBalance, autopay, ebill, openedAt, customerName, serviceAddress }], count, limit, offset, disclosure }

GET/api/public/v1/accounts/{id}

Single account detail including services and parcel ID.

Params: path: account UUID

Response schema: { data: { id, accountNumber, accountClass, status, currentBalance, openedAt, customerName, serviceAddress, parcelId, services[] }, disclosure }

GET/api/public/v1/bills

Bills with period, status, and balance, filterable by account, status, and issue-date range.

Params: limit (≤100), accountNumber, status, from, to (YYYY-MM-DD)

Response schema: { data: [{ id, billNumber, accountNumber, periodStart, periodEnd, issueDate, dueDate, status, subtotal, lateFee, total, balanceDue }], count, disclosure }

GET/api/public/v1/payments

Posted payments, filterable by posted-date range, amount range, and method.

Params: limit (≤100), from, to, min, max, method

Response schema: { data: [{ id, paymentNumber, accountNumber, paidAt, amount, method, channel, status }], count, disclosure }

GET/api/public/v1/stormwater

Parcel-level stormwater attributes: impervious area, ERU, credit, and source status.

Params: limit (≤200), parcelId

Response schema: { data: [{ premiseId, premiseNumber, parcelId, serviceAddress, imperviousSqft, eruValue, creditPct, sourceSystem, sourceStatus }], count, disclosure }

Export catalog

Downloadable artifacts available in the app today

Executive dashboard briefing (PDF)/ → Export dashboard PDF
Meter reading route file (PDF route sheet or CSV)/metering → Build route file
Account list (CSV)/accounts → Export CSV
GL / revenue distribution (CSV)/payments → Search & ERP → GL export

Import catalog

Safe preview-first import workflows

IAS-style impervious surface CSV (preview + audited apply)/stormwater → IAS import adapter
Meter read CSV (route-file counterpart)Planned — route file export exists today at /metering

MultiSpeak capability statement

Compatibility adapter position — not a live protocol certification

Status: adapter design only. MultiSpeak is a SOAP/XML message standard. Connecting it requires the utility's (or vendor's) MultiSpeak endpoint URL, specification version (e.g. 3.0 / 4.1), service credentials, and a message-by-message field mapping workshop.

The platform's contribution would be a translation adapter between MultiSpeak SOAP messages and the JSON REST surface documented above. No MultiSpeak endpoint is connected in this prototype, and no certification is claimed.

Required to proceed

Utility/vendor MultiSpeak endpoint + version
Service account credentials
Agreed message set (usage reads, account sync, service orders)

Illustrative payload shape (compatibility adapter demo)

<MultiSpeakMessage xmlns="http://www.multispeak.org/Version_4.1_Release">
  <Body>
    <GetUsageReadsRequest>
      <accountNumber>50000001</accountNumber>
      <serviceType>Water</serviceType>
    </GetUsageReadsRequest>
  </Body>
</MultiSpeakMessage>

No external system is connected in this prototype. All third-party activity shown is simulated.

How integrations occur

RFP Q1/Q22 — the honest summary

Built today: read-only REST APIs (this page), CSV import adapters with safe preview, and PDF/CSV exports. Configuration needed: Cityworks, Esri, Tyler MUNIS, IAS World, Itron Temetra, and Microsoft Entra SSO each require vendor endpoints, credentials, and a mapping/validation engagement — see Integrations and Compatibility & Compliance.