Sentra 311311 service requests
Platform › API & integrations

Sentra 311 API & integrations

A documented REST API, Open311, a public API for your report page and signed webhooks, so Sentra 311 fits with the systems your city already runs.

Get a demoRead the API docs
The webhooks admin page with endpoints, events and the delivery log.

Four ways to connect

REST API v1

Everything staff can do in the portal, at {city}.sentra311.com/api/v1, with a signed-in staff session.

Public API

What the report page, widget and resident app use, at api.sentra311.com/public/v1 with your city’s public key.

Open311 GeoReport v2

The open standard for service requests, so civic apps and other tools can read your services and requests.

Webhooks

Sentra 311 calls your system when a request is created, assigned, changes status, is closed or reopened.

How a webhook integration works

  1. Sentra 311

    A request changes

    A resident files it, staff assign it, a crew closes it. Every change is recorded on the request’s timeline.

  2. Sentra 311

    Sentra 311 sends a webhook

    A JSON event goes to each endpoint subscribed to it, signed with HMAC SHA-256 and your endpoint’s secret.

  3. Side path:

    Failed deliveries are retried

    Up to six attempts with backoff: after 10 seconds, 1 minute, 5 minutes, 30 minutes and 2 hours.

    Every attempt in the delivery log

  4. Your system

    Your system acts on it

    Create a work order, update a data warehouse or notify a team. Read more through the REST API or Open311.

The interactive Sentra 311 API reference, generated from the OpenAPI 3 file, with the API conventions.

Documented with OpenAPI 3

About 150 endpoints, described in one OpenAPI 3 file that’s updated with every endpoint, with interactive docs served by the API.

  • Docs at /api/docs; the spec at /api/openapi.yaml
  • JSON in and out, with one error shape: {"error": {"code", "message", "fields"}}
  • Cursor paging: ?limit=50&cursor=… returns data and next_cursor
  • Updates need If-Match with the record’s version: 428 without it, 409 when it’s stale
  • Creates take an Idempotency-Key, so a retried request doesn’t act twice
  • Rate limits per staff session, and per IP and city key on the public API

Webhooks

Admins add endpoints and pick events in Admin › Webhooks, where every delivery and its response code is logged.

  • Events:
    • request.created
    • request.assigned
    • request.status_changed
    • request.closed
    • request.reopened
  • Headers: X-Civic311-Event, X-Civic311-Delivery, X-Civic311-Timestamp and X-Civic311-Signature
  • Signature: sha256= plus an HMAC SHA-256 of {timestamp}.{body} with the endpoint’s secret
  • Up to six attempts with backoff when your endpoint doesn’t answer with success
  • HTTPS endpoints on public addresses only; payloads carry the work, not residents’ personal data

Open311 GeoReport v2

Open311 lists your public request types and requests, with jurisdiction_id set to your city’s subdomain. Private and emergency types and residents’ personal data are never exposed.

  • GET /open311/v2/services.json
  • GET /open311/v2/services/{code}.json
  • GET /open311/v2/requests.json
  • POST /open311/v2/requests.json
  • GET /open311/v2/requests/{id}.json
  • Posting a request needs your city’s public key as api_key

Public API

The report page, the website widget and the resident app all use the same public API, chosen by your city’s public key in X-City-Key.

  • Request types, city settings and map layers
  • File a request, with photos
  • Track a request by number, follow it, leave feedback
  • Nearby requests
  • AI chat
  • Knowledge base search and articles
  • Public performance numbers
  • Resident accounts, saved places and “My requests”

Sign-in, exports, maps and security

The staff API uses the same sign-in as the portal; data leaves the system only in ways your admins control.

  • Staff API calls use a signed-in staff session (Authorization: Bearer); permissions are enforced in the API by role and department
  • Machine-to-machine API keys and single sign-on are coming
  • Exports: requests as CSV, the audit log as CSV, and reports as CSV or PDF, also on a schedule by email
  • Migration: the importer reads a CSV export from your old system, with undo
  • Maps: your ArcGIS layers add lookups such as district and trash day to each request; Mapbox or Esri base maps; street routing for dispatch
  • Every city’s data is separated, and changes are recorded in an audit log
  • Work-order connectors such as Cityworks are coming

Code samples

File a request through the public API

curl -X POST https://api.sentra311.com/public/v1/requests \
  -H "X-City-Key: $CITY_PUBLIC_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"category_id": "<id from GET /public/v1/categories>",
       "lat": 36.7378, "lng": -119.7871, "address": "2600 Fresno St",
       "answers": {}, "contact": {"email": "[email protected]"},
       "language": "en", "source": "web"}'

# 201 Created
# {"number": 1342, "tracking_token": "…", "track_url": "…", "status": "Received"}

Verify a webhook signature (Python)

import hashlib, hmac, time

def verify(secret: str, headers: dict, raw_body: bytes) -> bool:
    ts = headers["X-Civic311-Timestamp"]
    signed = ts.encode() + b"." + raw_body          # "{timestamp}.{body}"
    expected = "sha256=" + hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
    if not hmac.compare_digest(expected, headers["X-Civic311-Signature"]):
        return False
    return abs(time.time() - int(ts)) < 300           # your choice: reject old deliveries

Read the full reference in the API docs, or see Open311, webhooks & API.

Questions cities ask

Is there an API key for server-to-server integrations?

Not yet. Machine-to-machine API keys are on our roadmap. Today, integrations use webhooks (Sentra 311 calls your system), Open311 and the public API with your city’s public key, and the staff REST API with a signed-in staff session.

Where is the API reference?

The API serves interactive docs at /api/docs and the OpenAPI 3 file at /api/openapi.yaml, kept up to date with every endpoint.

Do webhooks include residents’ personal data?

No. Payloads carry the work — request number, type, status, priority, department, district, assignee, address and location — not the resident’s name, email or phone.

Can we try the API before signing?

Yes. We can set up a demo city for your team to explore the API docs and the public API. Demo cities never call outside systems, so webhook testing happens in your own city’s setup.

Does Sentra 311 connect to our work-order system?

Through webhooks and the REST API today. Ready-made connectors for work-order systems such as Cityworks are coming.

Is single sign-on available for staff?

Staff sign in through Clerk today. Single sign-on with your city’s identity provider is coming.