Skip to content

Documentation

v2.8 Updated Oct 2026

CivicFlow documentation

Set up your workspace, model your city’s services and roll CivicFlow out to every department — with guides written by the team that builds it.

Short, task-focused guides for admins and department leads.

Quickstart

Go from an empty workspace to your first routed incident in about 30 minutes. You need an Admin role and the CivicFlow CLI, or you can follow the same steps under Settings in the web app.

  1. Install the CLI and sign in

    The CLI talks to the same REST API as the web app. Sign in with your work account; the token is stored in your system keychain, never in a file.

    Shell Terminal
    # Install the CivicFlow CLI and sign in to your workspacenpm install --global @civicflow/clicivicflow login --workspace aurora# Signed in as m.lindqvist@aurora.gov (Admin) · EU region
  2. Import your service categories

    Categories describe what residents can report and which SLA applies. Start from your existing 311 list — you can rename, merge or retire categories later without breaking history.

    JSON categories.json
    [  {    "key": "lighting",    "name": "Streetlight outage",    "department": "public-works",    "sla": { "acknowledge_h": 4, "resolve_h": 48 }  },  {    "key": "waste",    "name": "Missed collection",    "department": "sanitation",    "sla": { "acknowledge_h": 8, "resolve_h": 24 }  }]
  3. Create a routing rule

    Rules run top to bottom on every new incident, and route work to the teams you created. This one sends streetlight reports in the north district to the electrical crew and raises the priority after dark.

    JSON rules/north-lighting.json
    {  "name": "North lighting → electrical crew",  "when": { "category": "lighting", "district": "north" },  "then": [    { "route": "elec-4" },    { "prioritize": "high", "between": ["19:00", "07:00"] }  ]}
  4. Open intake and go live

    Enable the resident web portal and email intake, then send a test report. It appears on the operations map within seconds, already categorized and assigned.

    Shell Terminal
    civicflow import categories.json --dry-runcivicflow rules apply rules/north-lighting.jsoncivicflow channels enable web-portal email# Send a test report — it appears on the map in secondscivicflow incidents create --category lighting --at "Linden St & 4th Ave"

Core concepts

Seven objects describe how work moves through CivicFlow. Every screen, report and API endpoint is built from them.

Incident
A single issue reported by a resident, a staff member or an integration — with a location, category, status, history and attachments.
Category
The type of issue (e.g. Streetlight outage). It sets the intake form, the default SLA and which department owns the work.
Queue
An ordered list of incidents waiting for a team, sorted by priority and SLA due time.
Team
A group of staff or a field crew that works a queue — with members, shifts and a service area.
SLA
The target time to acknowledge and resolve an incident. Policies can vary by category, priority, district and business hours.
Rule
A condition and an action — route, prioritize, notify or merge — evaluated on every new or updated incident.
Resident
A person who reports or follows an incident. Contact details are personal data, protected by your retention policy.

Workspace setup

A workspace is one city or organization. Choose its data region (EU or US) when you create it — the region cannot be changed later, because every record, file and backup stays inside it.

  • Profile: official name, logo, time zone and working hours used by SLA clocks.
  • Districts: import boundaries as GeoJSON or draw them on the map; incidents are assigned a district automatically.
  • Languages: enable the languages residents can report in. Category names and notifications are translated per language.
  • Invite admins: add at least two admins so access never depends on one person.

Guides 6 min read

Configure categories & SLAs

Model your services and set response targets that match council commitments.

Each category has an intake form, an owning department and an SLA policy. Keep the list short and resident-friendly: “Streetlight not working” works better than an internal asset code.

SLA policies combine a target to acknowledge and a target to resolve, counted in business or calendar hours. Add overrides for priority or district — for example, 4 hours instead of 48 for urgent road hazards.

Changes apply to new incidents only. Existing incidents keep the SLA they were created with, so your reports stay honest.

Guides 5 min read

Routing rules

Send every incident to the right team automatically, with clear fallbacks.

Rules are evaluated top to bottom; the first matching route action wins, while notify and prioritize actions always run. Conditions can use category, district, keywords, asset type, time of day and the AI priority score.

  • End every rule set with a catch-all route to a triage queue.
  • Use Test rules to replay last week’s incidents before you publish.
  • Every rule change is versioned and recorded in the audit log.

Guides 4 min read

Field app rollout

Get crews working from the mobile app in their first week.

Start with one crew and one category for a week, then expand by district. Crews sign in with SSO or a one-time code; devices can be shared between shifts.

The field app works offline: crews can view assigned work, add photos and close incidents without coverage, and changes sync when the device reconnects. Before-and-after photos are required to resolve by default — you can relax this per category.

Guides 3 min read

Public status pages

Show residents what is being fixed, without exposing personal data.

Public status pages publish live service levels and an anonymized map of open work. Names, contact details and photos of people are never published; exact addresses are rounded to the nearest block.

Choose which categories appear, the refresh interval (hourly by default) and your own domain. Pages meet WCAG 2.1 AA and are available in every language enabled for the workspace.

Guides 5 min read

CivicFlow AI

Prioritize, cluster and summarize incidents — with staff always in control.

CivicFlow AI suggests a category and priority for every new incident, groups duplicate reports into one cluster and drafts replies for staff to review. Suggestions show their evidence, and nothing is sent to a resident without a person approving it.

Models run in your workspace’s data region. Your data is not used to train models shared with other customers. AI features can be turned off per category or for the whole workspace.

Administration 7 min read

SSO & SCIM

Sign in with your identity provider and keep accounts in sync automatically.

CivicFlow supports SAML 2.0 and OpenID Connect with any standards-based identity provider. Once SSO is enforced, password sign-in is disabled for everyone except break-glass admins.

With SCIM 2.0, users and groups are created, updated and deactivated from your directory. Map directory groups to CivicFlow roles and teams so access follows people when they change departments. Available on Enterprise.

Administration 4 min read

Roles & permissions

Give every person exactly the access their job needs.

Five built-in roles cover most cities:

  • Admin — workspace settings, billing, users and integrations.
  • Manager — rules, SLAs and reports for their departments.
  • Agent — triage, assign and reply to residents.
  • Field — assigned work in the field app.
  • Viewer — read-only dashboards, e.g. for council members.

Permissions can be scoped to departments or districts. Custom roles are available on Enterprise.

Administration 3 min read

Audit logs

See who did what, and when — for every change in the workspace.

The audit log records sign-ins, permission changes, rule and SLA edits, exports, API key usage and every change to an incident. Entries are append-only and cannot be edited, even by admins.

Filter by person, object or date, export to CSV, or stream events to your SIEM. Logs are kept for 12 months by default and up to 7 years on Enterprise.

Administration 4 min read

Data retention

Keep records as long as the law requires — and not a day longer.

Retention policies decide when resident contact details are anonymized and when closed incidents are deleted. A common setup anonymizes residents 12 months after resolution and keeps anonymized incidents for statistics.

Policies run nightly and are recorded in the audit log. Residents’ access and erasure requests can be handled from the resident profile, or through the Residents API.

Can’t find what you need?

Our support team answers within one business day — faster on Growth and Enterprise. Check the status page first if something seems off.