Cityworks API
Cityworks (now part of Trimble) is a GIS-centric asset lifecycle management platform used by local governments, utilities, airports, and public works agencies to manage infrastructure from permitting through operations and maintenance. An unofficial API lets you programmatically pull work orders, service requests, permits, cases, inspections, and asset records—and push updates like new work orders, service requests, permit applications, and inspection results back into Cityworks across its AMS and PLL modules.
What is Cityworks?
Cityworks, now part of Trimble, is a GIS-centric asset lifecycle management system that helps organizations manage public infrastructure from permitting through operation and maintenance. Local governments, utilities, airports, counties, and public works agencies use Cityworks to run work order management and field operations, permitting and licensing, inspections and compliance, citizen service requests, and risk assessment and maintenance planning—all anchored to their ArcGIS asset inventory.
Core product areas include:
- Respond (work management, service requests, and work orders)
- OpX (project, permitting, and licensing management)
- Storeroom (inventory and materials tracking)
- Workload (crew, labor, and resource management)
- Operational Insights (risk assessment and maintenance planning)
Common data entities:
- Work Orders, Tasks, Labor, Equipment, Materials, Costs
- Service Requests, Citizen Submissions, Comments, Attachments
- Permits, Cases, Licenses, Fees, Payments (PLL)
- Inspections, Checklists, Conditions, Approvals
- Assets, GIS Features, Entity Types, Asset Groups
- Employees, Crews, Departments, Domains
The Cityworks Integration Challenge
Agencies run mission-critical operations on Cityworks daily, but turning a GIS-centric, deployment-specific platform into API-driven automation is non-trivial:
- Per-deployment configuration: Domains, entity types, custom fields, and templates are tailored per agency—generic integrations break across tenants
- Token auth changes: Cityworks 23 changed authentication, passing the token in the Authorization header as cityworks {token}, which differs from older query-parameter token flows
- GIS coupling: Work orders, service requests, and inspections are tied to ArcGIS features, so calls must reconcile Cityworks entities with the agency's spatial data
- Module spread: AMS (Asset Management) and PLL (Permitting, Licensing, Land) have distinct object models, IDs, and lifecycle states
- On-prem and cloud variability: Endpoint coverage and base URLs differ between self-hosted, Cityworks Online, and version-specific deployments
- Permission and domain scoping: Group permissions, domains, and entity-type access control which records a session can read or write
How Supergood Creates Cityworks APIs
Supergood reverse-engineers authenticated sessions and the Cityworks REST API to deliver a resilient, normalized API layer for your Cityworks deployment—across AMS and PLL, on-prem or Cityworks Online.
- Handles token authentication, including the Cityworks 23 Authorization header format, and renews tokens automatically
- Maintains session continuity with automated refresh and change detection across version upgrades
- Normalizes responses across Work Orders, Service Requests, Permits, Cases, and Inspections so you integrate once and rely on consistent objects
- Aligns with agency-specific domains, entity types, custom fields, and group permissions to ensure compliant access
Use Cityworks with AI agents: Cityworks MCP Server →
Getting Started
- Schedule Integration Assessment
Book a 30-minute session to confirm your modules, deployment model, and authentication setup.
- Supergood Generates and Validates Your API
We deliver a hardened, production-ready Cityworks adapter tailored to your agency configuration and permissions.
- Deploy with Monitoring
Go live with continuous monitoring and automatic adjustments as Cityworks evolves.
API Endpoints
Authentication
/authenticateAuthenticate to a Cityworks deployment and obtain a session token, passed on downstream calls via the Authorization header.
Work Management
/work_ordersList work orders with filters for status, entity type, crew, domain, and date range across the AMS module.
Work Management
/create_work_orderCreate a new work order against a GIS asset or entity, including tasks, labor, equipment, and materials.
Service Requests
/service_requestsRetrieve citizen and internal service requests with status, problem code, and location filters.
Permitting
/permitsPull permits, cases, and licenses from the PLL module with status, type, fee, and applicant filters.
Inspections
/submit_inspectionSubmit inspection results, checklist answers, and conditions against a work order, case, or permit.
Use Cases
Sync work orders and service requests into downstream systems
- Pull work orders, tasks, labor, and cost data from AMS into a single warehouse - Stream citizen service requests and status changes to 311, CRM, and BI tools - Reconcile asset and GIS feature records across systems for unified reporting
Automate permitting and licensing workflows
- Push new permit applications and cases into the PLL module without portal clicks - Pull fees, payments, and approval status back for finance and applicant portals - Trigger downstream notifications when a permit or license changes state
Streamline field inspections and compliance
- Submit inspection results, checklists, and conditions from mobile or third-party apps - Pull inspection schedules and outcomes for compliance dashboards - Auto-create follow-up work orders when an inspection fails
Keep asset and inventory data in sync
- Sync assets, entity types, and GIS features between Cityworks and external systems - Reconcile Storeroom inventory and materials usage against work order costs - Surface crew, labor, and equipment utilization to workforce planning tools
Technical Specifications
Authentication
Token authentication, including the Cityworks 23 Authorization header format (cityworks {token}), handled in a managed session
Connectivity
Authenticated sessions over the Cityworks REST API across AMS, PLL, and GIS services
Response format
Normalized JSON across Work Orders, Service Requests, Permits, Cases, and Inspections
Rate limits
Adaptive throttling tuned to your deployment to avoid server-side limits on self-hosted or Cityworks Online instances
Session management
Automatic token renewal, session refresh, and credential rotation
Data freshness
Near real-time pulls for work orders, service requests, and permits with optional scheduled batch syncs
Security
Encrypted credential vault, scoped access tokens, SOC 2-aligned controls, and audit logging
Webhooks
Event-style callbacks for work order, service request, permit, case, and inspection status changes
Latency
Sub-second reads on cached entities; multi-second writes when posting work orders and inspections
Throughput
Horizontally scaled workers sized to multi-module volume across AMS and PLL
Reliability
Retry, backoff, and idempotency keys for work order, permit, and inspection transactions
Adaptation
Continuous monitoring of Cityworks releases, version upgrades, and agency-specific configuration drift
Frequently asked questions
Yes. Supergood normalizes data across the Asset Management System (AMS) and Permitting, Licensing, and Land (PLL) modules, so work orders, service requests, permits, cases, and inspections share one consistent API surface.
Yes. Supergood adapts to either deployment model, working against your base URL and authenticated REST surface whether you self-host or run on Cityworks Online, with network configuration tuned to your environment.
Supergood handles token authentication including the Cityworks 23 format, where the token is passed in the Authorization header as cityworks {token}, and renews tokens automatically so headless automation stays connected.
Each deployment is profiled against its configured domains, entity types, custom fields, and group permissions. Supergood preserves agency-specific fields and lifecycle states rather than forcing a generic schema.
Yes. Because Cityworks is GIS-centric, work orders, service requests, and inspections are tied to ArcGIS features. Supergood reconciles Cityworks entities with the associated spatial features so downstream systems get both attribute and location context.