pn-new-crm/docs/umami-api-capabilities.md

Umami v2 / v3 API capabilities — reference for flesh-out planning

Verified against: analytics.portnimara.com (Umami v3.1.0), 2026-05-19. Auth: username/password → JWT via POST /api/auth/login, Bearer on every request, 1h TTL (we cache 55min). Companion code: src/lib/services/umami.service.ts (currently wraps stats/pageviews/metrics/active).

Endpoints below are listed by topic area, with what we currently use, what's available but unused, and where it could plug into the CRM.

---

1. Stats & traffic snapshots — /api/websites/:id/stats

Currently used. Returns the flat aggregate over the requested window plus a comparison block for the prior window of equal length.

{
  "pageviews": 2081, "visitors": 726, "visits": 872,
  "bounces": 457, "totaltime": 109519,
  "comparison": { "pageviews": 1935, "visitors": 642, ... }
}

Unused fields we could surface:

• totaltime — total seconds on site → derive avg session time (totaltime / visits).
• bounces / visits → bounce-rate KPI.
• Period-over-period deltas (already wired for trend arrows, but the full comparison object has more we could use for a "what changed since last period" panel).

Filters supported (per Umami docs, mostly untested by us): url, referrer, title, query, event, host, os, browser, device, country, region, city — meaning every stats call can be sliced. Big unlock: show stats for a specific landing-page URL on the berth detail (e.g. /berths/A12 stats), or filter by referrer to see which channels drove signed EOIs.

---

2. Time-series — /api/websites/:id/pageviews

Currently used for the trend chart. Returns {pageviews: [{x, y}], sessions?: [{x, y}]} (sessions only when compare is requested).

Parameters: startAt, endAt, unit (year|month|day|hour), timezone, compare (untapped), filters (untapped).

Unused: compare=prev gives the same series for the previous period — could power a dual-line "vs last period" overlay on the chart.

---

3. Top-N metrics — /api/websites/:id/metrics

Currently used for Top Pages / Referrers / Countries (limit 10). Returns [{x, y}].

Available type values (we surface 4, Umami offers 17):

Type	What it returns	CRM use case
path	Top URLs	✅ Already shown (we mis-typed as url, now fixed)
referrer	Top referring sites	✅ Already shown
country	Visitors by country	✅ Already shown
browser / os / device	Tech breakdown	Not surfaced — useful for "is mobile traffic converting?"
region / city	Geographic drill-down	Strong fit for marina marketing
language	Visitor browser language	Could feed i18n decisions
screen	Resolution	Low value
event	Top custom events	Big unlock — see §6 below
tag	Event tags	Same
query	Top URL query strings	UTM-debug surface
entry / exit	First/last page in session	Funnel analysis
title	Top page titles (vs paths)	Better labels for non-slug URLs
hostname	Multi-domain sites	Probably N/A
distinctId	Custom user identifiers	If we ever pipe CRM user IDs into Umami

---

4. Live visitors — /api/websites/:id/active

Currently used for the green-dot "N active right now" indicator. Returns {visitors: number} (last-5-min count).

Alternative for richer realtime: /api/realtime/:websiteId (live realtime feed) returns far more — current top URLs being viewed, current top countries, recent event stream, a 30-minute time-series, totals, plus a timestamp you can poll against. We could surface a "live" panel on the dashboard showing the most-viewed pages right now.

---

5. Sessions API — /api/websites/:id/sessions/*

Not currently used. Multiple endpoints worth integrating:

• GET /sessions — list every session in a range with full device/geo/visits/views columns. Pageable. Could power a "recent visitors" surface — see who's browsing the berth detail pages right now.
• GET /sessions/stats — summary aggregate (pageviews, visitors, visits, countries, events) keyed by session.
• GET /sessions/:sessionId — drill into a single session: device, OS, browser, country, subdivision, city, screen, language, firstAt, lastAt, visits, views, events, totaltime.
• GET /sessions/:sessionId/activity — full event timeline for one session (urlPath, eventName, referrerDomain, timestamps).
• GET /sessions/:sessionId/properties — custom session properties (email, name, etc. — if Umami's identify() is called from the marketing site).
• GET /session-data/properties + /session-data/values — aggregate custom session properties.
• GET /sessions/weekly — heatmap of session count by hour-of-week. Direct fit for an "engagement heatmap" widget.

Big unlock: if marketing site calls umami.identify({email}) after EOI form submit, sessions can be linked back to a specific client. We could then show "this client's website journey" on their CRM detail page.

---

6. Events API — /api/websites/:id/events/*

Not currently used. Umami auto-tracks pageviews; custom events are fired explicitly (e.g. button clicks, form submits, video plays). Endpoints:

• GET /events — list custom events in a range.
• GET /events/stats — totals.
• GET /events/series — time-series per event.
• GET /event-data/* — aggregate over event payload properties.

High-leverage CRM use cases:

• Fire an event on the marketing site when someone clicks "Inquire about berth A12" → CRM Activity feed shows it in real-time on the inquiry record.
• Fire an event when someone downloads a brochure → see which brochures convert.
• Fire an event on EOI form-step completions → drop-off funnel analysis.

We'd need to add umami.track('event-name', {payload}) calls on the marketing site (~1-2h work there) and a new admin surface to define/view these events.

---

7. Reports API — /api/reports/*

Not currently used. Umami's "saved reports" system. Endpoints:

• GET /reports + GET /reports/:id — list / retrieve saved reports.
• POST /reports/insights — slice-and-dice with arbitrary filters/dimensions.
• POST /reports/funnel — multi-step conversion analysis.
• POST /reports/retention — cohort retention over time.
• POST /reports/utm — UTM-tagged campaign performance.
• POST /reports/journey — most common navigation paths.
• POST /reports/goals — pageview/event-goal completion tracking.
• POST /reports/revenue — revenue attribution (if we fire purchase events with amount).
• POST /reports/attribution — first/last-click attribution modelling.

Best fits for the CRM:

• Funnel report for the EOI flow: /berths → /berths/A12 → /inquire?berth=A12 → form submit → CRM EOI signed. Surface drop-off percentages on the Pulse-style dashboard.
• Journey report to see "what paths do visitors take before signing an EOI?" — informs marketing-site IA.
• UTM report to plumb campaign attribution into the lead-source breakdown (currently CRM-side; could be cross-validated against marketing's UTM-tagged traffic).
• Attribution report to give Pipeline-by-Source a "first-click vs last-click" toggle.

---

8. Send events from CRM → Umami — /api/send

Not currently used. The collect endpoint accepts page hits + custom events from any client. CRM doesn't currently push events, but we could:

• Fire umami.track('signed-eoi', {berth: 'A12', deal_value: 50000}) from the CRM after EOI completion — closes the loop between marketing-site funnel and CRM outcome.
• Fire umami.track('contract-signed'), umami.track('deposit-received') — full funnel visible in Umami without leaving it.

---

9. Multi-website + team admin — /api/websites, /api/teams, /api/users

Not currently used. We hard-code a single umami_website_id per port. Useful if a port runs multiple sites (e.g. main marina + residential subdomain): admin UI could list-and-pick from the configured Umami instance's websites instead of requiring manual ID copy-paste. Same for team membership.

---

Prioritized opportunity list

Ranked by leverage-vs-effort, assuming the v3.1.0 fix in this commit is the baseline:

1. Avg session time + bounce rate KPI tiles (~20 min) — already in the /stats response, just need new tiles.
2. compare=prev overlay on the pageviews trend chart (~30 min) — dual-line "vs last period" surface.
3. Country choropleth heatmap (~4-6h) — already queued in Bucket 3 of the UAT findings doc as "World-map heatmap of Umami visitor origins."
4. Surface top browsers / OS / devices (~30 min) — additional TopList columns; pure UI work.
5. Fire CRM-side events back into Umami (~2-3h marketing-site + CRM hook) — closes the funnel between marketing and outcomes.
6. EOI funnel via /api/reports/funnel (~3-4h) — drop-off analysis from berth view → inquiry → signed EOI.
7. Identify visitors → link sessions to clients (~4-6h spread across marketing site + CRM detail surfaces) — biggest unlock but needs marketing-site changes.
8. Sessions-list "recent visitors" panel (~2-3h) — see who's browsing right now, drill into individual sessions.
9. Saved-reports admin surface (~6-10h) — let admins create + share Umami reports without leaving the CRM. Bigger product surface; defer until #1-#5 land.

---

Service-layer additions needed to support the above

src/lib/services/umami.service.ts currently exports: getStats, getPageviewsSeries, getMetric, getActiveVisitors, testConnection. To unlock the opportunities above, add:

• getSessions(portId, range, opts) → /sessions (paged)
• getSession(portId, sessionId) → single-session drill-in
• getSessionActivity(portId, sessionId, range) → event timeline
• getSessionsWeekly(portId, range) → heatmap source
• getEvents(portId, range) + getEventsStats(portId, range) + getEventsSeries(portId, range, eventName, unit) → custom events
• getRealtime(portId, range) → /api/realtime/:id for the live panel
• getReport(portId, reportType, body) → POST wrappers for funnel/retention/journey/utm/goals/revenue/attribution
• trackEvent(portId, name, payload) → POST to /api/send for CRM → Umami event emission

Each is a thin wrapper around the existing umamiFetch (or a new umamiPost variant for the reports endpoints). The auth + JWT cache + retry logic already in place handles them all.

---

Known gotchas (verified against v3.1.0)

• Metric type=url returns 400 — use type=path (handled in our code via back-compat alias).
• /api/websites/:id/pageviews returns sessions only when compare is in the query string — keep .sessions optional in TS types.
• Stats response is flat (pageviews: number), not nested (pageviews: {value, prev}). The v1 nested shape isn't in v2/v3.
• /api/auth/login returns a JWT with no expires_in field — we assume 1h and refresh proactively at 55min.
• Visiting /api in a browser returns nothing — base path has no GET handler. Use /api/heartbeat to check liveness.
• Filters are passed as query params (e.g. &country=DE), NOT as a JSON filters body, per actual API behaviour (docs occasionally show JSON which doesn't work for GET endpoints).