Sentra 311311 service requests
Guides

Open311, webhooks and an OpenAPI file: notes for city IT

For the IT team: how Sentra 311 connects to other systems, how it keeps cities separate, and what the API conventions are.

By the Sentra 311 team · · 4 min read

This article is for city IT staff and integrators. It covers how Sentra 311 talks to other systems and the rules the API follows. If you're evaluating 311 software, these are the questions your IT team should ask any vendor.

Open311 GeoReport v2

Sentra 311 supports the Open311 GeoReport v2 standard at /open311/v2. Open311 is a common, published format for 311 data, used by apps and by researchers. Services (your request types) and public requests are available in that format, so tools that already speak Open311 can work with Sentra 311.

Webhooks

Webhooks let another system react when something happens in Sentra 311, without polling. Admins set them up in the portal under Admin › Webhooks. Events include:

  • request.created
  • request.assigned
  • request.status_changed
  • request.closed
  • request.reopened

Each delivery is a JSON POST signed with HMAC-SHA256 over a timestamp and the body. The X-Sentra 311-Timestamp and X-Sentra 311-Signature headers let your receiver check the message came from Sentra 311 and reject old replays. If your endpoint is down, deliveries are retried with increasing delays, up to six attempts.

Common uses: creating a work order in an asset management system when a request is assigned, posting to a Teams channel when an urgent request comes in, or updating a data warehouse.

The staff API

Everything the portal does goes through the same API, documented in an OpenAPI 3 file kept in the repository and updated with every endpoint. A test fails if any endpoint is missing from the documentation. The conventions are consistent:

  • One error format with a code, a message and field errors.
  • Cursor paging on lists.
  • If-Match on updates. Every update must send the version it was based on. Without it you get a 428; with an old version you get a 409. This stops two people silently overwriting each other's changes.
  • Idempotency-Key on creates, so a retried request doesn't create a duplicate.

Keeping cities separate

Sentra 311 serves many cities from one platform. Every table has a city ID, and all queries go through one city-scoped helper. Our test suite includes a cross-city test that calls every endpoint as one city and checks it can't see or change another city's data. A new endpoint that isn't covered fails the build.

Permissions

Roles are city admin, department head, dispatcher, call-taker and field worker. Permissions are enforced in the API, not only hidden in the screens. A field worker sees only their department's requests and never sees resident contact details. Department heads see their departments' reports. Departments can be marked restricted so call-takers don't see them.

Exports

Requests export to CSV with one column per custom form field. Reports export to CSV and PDF. Scheduled reports can be emailed to any address.

Sign-in

Staff sign in through Clerk. Single sign-on with your city's Microsoft or Google accounts is on our roadmap.

GIS

Sentra 311 reads ArcGIS layers for lookups and map display. See using your city's GIS layers. Writing features back to ArcGIS is on our roadmap.

Work order systems

Direct connectors to work order systems such as Cityworks, Cartegraph and Lucity are on our roadmap, built as customers need them. In the meantime, webhooks and the API cover most integrations, and we're glad to help your team build one.

A simple integration, step by step

Say public works uses a separate work order system and wants a work order whenever a pothole is assigned:

  1. In Sentra 311, add a webhook for request.assigned, pointing at an endpoint your team controls.
  2. When a delivery arrives, check the signature with the shared secret, and reject it if the timestamp is old.
  3. Read the request ID from the payload, and call the Sentra 311 API for the full request if you need more fields.
  4. Create the work order, and store the Sentra 311 request number on it.
  5. When the work order closes, call the Sentra 311 API to change the request's status, sending the version you read so nobody's changes are overwritten.

Because every update needs the current version, your integration can't silently undo a change a dispatcher just made. If the versions don't match, re-read and try again.

Questions to ask any vendor

  1. Is there a published API, and is it documented?
  2. How are cities kept separate, and how is that tested?
  3. Are permissions enforced in the API or only in the screens?
  4. Are webhooks signed?
  5. What happens when two people edit the same request at once?
  6. Can I get all of my data out, any time, in a standard format?

Related articles