Skip to main content
Developers

Open311 API documentation

Read and submit City of Smithville 311 service requests from your own app. The API follows Open311 GeoReport v2, so tools built for other cities work here too.

Getting started

Every endpoint lives under https://clear311.cloud.sweent.net/api/v2. Reading is open to everyone; submitting requests needs an API key. Try it from a terminal:

curl "https://clear311.cloud.sweent.net/api/v2/services.json"
  1. List services to get the service_code for each kind of problem.
  2. Read a service definition for the questions that service asks.
  3. Submit a request with your key, then follow it with Get one request or Status updates.

The full standard is on the Open311 wiki. Requests from the API land in the same queue as the website’s, and residents’ names and contact details are never returned.

Authentication and API keys

Send your key in the X-API-Key header (best), or as api_key in the query string or the body. Each key only reaches the endpoints the City allowed for it; other endpoints answer 403.

  • Reading services, requests and updates works without a key, at a lower rate limit.
  • Submitting a request needs a key.
  • Posting a status update always needs a key.
  • When the City issues a new key for your app, the old one stops working at once. Update your app as soon as you get it.

To request an API key, contact the City of Smithville 311 team with your app’s name, what it does and a contact address.

Formats (JSON and XML)

End any path with .json or .xml to choose the format, or add ?format=xml. Without either you get JSON. POST bodies can be a form (application/x-www-form-urlencoded) or JSON, up to 100 KB.

curl "https://clear311.cloud.sweent.net/api/v2/services.xml"

<?xml version="1.0" encoding="utf-8"?><services><service><service_code>POTHOLE</service_code>…</service></services>

Rate limits

  • Without a key: 10 calls a minute per IP address.
  • With a key: 60 calls a minute per key by default. The City can set a different limit for each key.
  • Discovery is not limited.

Every limited response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (Unix time when the minute ends). Over the limit you get 429 with a Retry-After header in seconds.

Errors

Errors use the Open311 form: a list with one entry per problem.

[
  {
    "code": "400",
    "description": "service_code: Choose what the problem is"
  }
]
StatusMeaning
400A parameter is missing or not valid (one entry per field), or an unknown jurisdiction_id.
401The key is missing, wrong, revoked or expired.
403The key is not allowed to call this endpoint.
404Unknown endpoint, service or request, or the City has turned the API off.
413The body is larger than 100 KB.
429Too many calls this minute. Wait for Retry-After.
500Something went wrong on our side. Try again.
GET/api/v2/discovery.json

Discovery

Where the API lives, which formats it speaks and where to ask for a key. Start here if your app works with many cities.

Access: Open to everyone, no key and no rate limit.

Parameters for Discovery
ParameterRequiredDescription
jurisdiction_idNoThis city’s ID (see discovery). Any other value is rejected with 400.
curl "https://clear311.cloud.sweent.net/api/v2/discovery.json"
Example response · 200 OK
{
  "changeset": "2026-09-01T00:00:00Z",
  "contact": "City of Smithville 311",
  "key_service": "https://clear311.cloud.sweent.net/developers",
  "endpoints": [
    {
      "specification": "http://wiki.open311.org/GeoReport_v2",
      "url": "https://clear311.cloud.sweent.net/api/v2",
      "changeset": "2026-09-01T00:00:00Z",
      "type": "production",
      "formats": [
        "application/json",
        "text/xml"
      ]
    }
  ]
}

Try it

GET https://clear311.cloud.sweent.net/api/v2/discovery.json

GET/api/v2/services.json

List services

Every kind of problem residents can report, with its service_code. metadata is true when the service asks extra questions (see the service definition).

Access: Open to everyone. With a key, 60 calls a minute unless the City set another limit for it; without one, 10 a minute per IP address.

Parameters for List services
ParameterRequiredDescription
jurisdiction_idNoThis city’s ID (see discovery). Any other value is rejected with 400.
api_keyNoYour key, if you have one: calls count against its limit instead of the anonymous one. Or send it as an X-API-Key header.
curl "https://clear311.cloud.sweent.net/api/v2/services.json"
Example response · 200 OK
[
  {
    "service_code": "POTHOLE",
    "service_name": "Pothole",
    "description": "A hole or broken pavement in a street",
    "metadata": true,
    "type": "realtime",
    "keywords": "road,street,asphalt,hole",
    "group": "Streets & Roads"
  },
  {
    "service_code": "SIDEWALK",
    "service_name": "Sidewalk damage",
    "description": "Cracked, raised or missing sidewalk and curb ramps",
    "metadata": false,
    "type": "realtime",
    "keywords": "sidewalk,trip,curb,ramp",
    "group": "Streets & Roads"
  }
]

Try it

GET https://clear311.cloud.sweent.net/api/v2/services.json

GET/api/v2/services/{service_code}.json

Service definition

The extra questions one service asks, in order. Send the answers as attribute[code] when you submit a request.

Access: Open to everyone. With a key, 60 calls a minute unless the City set another limit for it; without one, 10 a minute per IP address.

Parameters for Service definition
ParameterRequiredDescription
service_codein the pathYesFrom List services, e.g. POTHOLE. Unknown or retired codes return 404.
jurisdiction_idNoThis city’s ID (see discovery). Any other value is rejected with 400.
api_keyNoYour key, if you have one: calls count against its limit instead of the anonymous one. Or send it as an X-API-Key header.
curl "https://clear311.cloud.sweent.net/api/v2/services/POTHOLE.json"
Example response · 200 OK
{
  "service_code": "POTHOLE",
  "attributes": [
    {
      "variable": true,
      "code": "size",
      "datatype": "singlevaluelist",
      "required": true,
      "datatype_description": null,
      "order": 1,
      "description": "Approximate size",
      "values": [
        {
          "key": "small",
          "name": "Smaller than a dinner plate"
        },
        {
          "key": "medium",
          "name": "Up to a car tire"
        },
        {
          "key": "large",
          "name": "Larger than a car tire"
        }
      ]
    }
  ]
}

Try it

GET https://clear311.cloud.sweent.net/api/v2/services/POTHOLE.json

GET/api/v2/requests.json

Search requests

Public requests, newest first. Residents’ names and contact details are never included, and requests held for review are left out.

Access: Open to everyone. With a key, 60 calls a minute unless the City set another limit for it; without one, 10 a minute per IP address.

Parameters for Search requests
ParameterRequiredDescription
service_request_idNoOne or more request IDs or tracking numbers, comma-separated.
service_codeNoOne or more service codes, comma-separated.
statusNoopen or closed.
start_dateNoReported on or after this ISO 8601 date and time.
end_dateNoReported on or before this ISO 8601 date and time.
agency_responsibleNoDepartment ID or name, e.g. Department of Public Works.
lat, longNoSearch around a point (WGS84). Send both or neither.
radiusNoMeters around lat, long (default 1000).
pageNoPage number, from 1 (default 1).
page_sizeNoResults per page, 1 to 100 (default 50). The X-Total-Count header has the total.
jurisdiction_idNoThis city’s ID (see discovery). Any other value is rejected with 400.
api_keyNoYour key, if you have one: calls count against its limit instead of the anonymous one. Or send it as an X-API-Key header.
curl "https://clear311.cloud.sweent.net/api/v2/requests.json?service_code=POTHOLE&status=open"
Example response · 200 OK
[
  {
    "service_request_id": "service_request:7eee1ff7-b340-4bcf-beb0-c91f3587b556",
    "token": "L2RLZN7X",
    "status": "open",
    "status_detail": "new",
    "service_name": "Pothole",
    "service_code": "POTHOLE",
    "description": "Pothole next to the crosswalk, bikes are hitting it",
    "agency_responsible": "Department of Public Works",
    "service_notice": "Sent to the Department of Public Works.",
    "requested_datetime": "2026-09-26T16:17:03.566Z",
    "updated_datetime": "2026-09-26T16:17:03.566Z",
    "expected_datetime": null,
    "closed_datetime": null,
    "address": "5th Ave & Main St",
    "address_id": null,
    "zipcode": null,
    "lat": 40.716248,
    "long": -73.99973,
    "media_url": null,
    "merged_into": null
  }
]

Try it

GET https://clear311.cloud.sweent.net/api/v2/requests.json?service_code=POTHOLE&status=open

GET/api/v2/requests/{id}.json

Get one request

One public request, by its ID or its 8-character tracking number.

Access: Open to everyone. With a key, 60 calls a minute unless the City set another limit for it; without one, 10 a minute per IP address.

Parameters for Get one request
ParameterRequiredDescription
idin the pathYesThe service_request_id or the tracking number (token).
jurisdiction_idNoThis city’s ID (see discovery). Any other value is rejected with 400.
api_keyNoYour key, if you have one: calls count against its limit instead of the anonymous one. Or send it as an X-API-Key header.
curl "https://clear311.cloud.sweent.net/api/v2/requests/L2RLZN7X.json"
Example response · 200 OK
{
  "service_request_id": "service_request:7eee1ff7-b340-4bcf-beb0-c91f3587b556",
  "token": "L2RLZN7X",
  "status": "open",
  "status_detail": "new",
  "service_name": "Pothole",
  "service_code": "POTHOLE",
  "description": "Pothole next to the crosswalk, bikes are hitting it",
  "agency_responsible": "Department of Public Works",
  "service_notice": "Sent to the Department of Public Works.",
  "requested_datetime": "2026-09-26T16:17:03.566Z",
  "updated_datetime": "2026-09-26T16:17:03.566Z",
  "expected_datetime": null,
  "closed_datetime": null,
  "address": "5th Ave & Main St",
  "address_id": null,
  "zipcode": null,
  "lat": 40.716248,
  "long": -73.99973,
  "media_url": null,
  "merged_into": null
}

Try it

GET https://clear311.cloud.sweent.net/api/v2/requests/L2RLZN7X.json

POST/api/v2/requests.json

Create a service request

Submits a new request into the same queue as the website. Send the fields as a form (application/x-www-form-urlencoded) or as JSON. Give a location as lat + long, or as address_string.

Access: Needs an API key allowed to submit. 60 calls a minute per key by default.

Parameters for Create a service request
ParameterRequiredDescription
api_keyYesYour key, or send it as an X-API-Key header.
service_codeYesFrom List services, e.g. POTHOLE.
descriptionYesWhat’s wrong, 10 to 4,000 characters.
lat, longOne ofWGS84 coordinates inside city limits.
address_stringOne ofStreet address.
address_idNoYour own ID for the address.
zipcodeNoPostal code.
attribute[code]VariesAnswers to the service’s questions (Service definition). Required questions must be answered.
emailNoThe resident’s email, for updates. Never shown publicly.
phoneNoThe resident’s phone, with area code. Never shown publicly.
first_name, last_nameNoThe resident’s name. Never shown publicly.
device_idNoYour app’s ID for the device, used to spot repeated reports.
media_urlNoLink to one photo.
jurisdiction_idNoThis city’s ID (see discovery). Any other value is rejected with 400.
curl -X POST "https://clear311.cloud.sweent.net/api/v2/requests.json" \
  -H "X-API-Key: YOUR_KEY" \
  --data-urlencode "service_code=POTHOLE" \
  --data-urlencode "lat=40.7162" \
  --data-urlencode "long=-73.9997" \
  --data-urlencode "description=Deep pothole in the right lane" \
  --data-urlencode "attribute[size]=large"
Example response · 200 OK
[
  {
    "service_request_id": "service_request:7eee1ff7-b340-4bcf-beb0-c91f3587b556",
    "token": "L2RLZN7X",
    "service_notice": "Sent to the Department of Public Works.",
    "account_id": null
  }
]
GET/api/v2/servicerequestupdates.json

Status updates

Public updates on requests, newest first: status changes and notes from the City. Poll this to keep your copy of requests current.

Access: Open to everyone. With a key, 60 calls a minute unless the City set another limit for it; without one, 10 a minute per IP address.

Parameters for Status updates
ParameterRequiredDescription
service_request_idNoOne or more request IDs or tracking numbers, comma-separated.
start_dateNoUpdated on or after this ISO 8601 date and time.
end_dateNoUpdated on or before this ISO 8601 date and time.
pageNoPage number, from 1 (default 1).
page_sizeNoResults per page, 1 to 100 (default 50). The X-Total-Count header has the total.
jurisdiction_idNoThis city’s ID (see discovery). Any other value is rejected with 400.
api_keyNoYour key, if you have one: calls count against its limit instead of the anonymous one. Or send it as an X-API-Key header.
curl "https://clear311.cloud.sweent.net/api/v2/servicerequestupdates.json?page_size=10"
Example response · 200 OK
[
  {
    "update_id": "service_request_update:service_request:7eee1ff7-b340-4bcf-beb0-c91f3587b556:2026-09-27T09-16-03-566Z:1feb33e3",
    "service_request_id": "service_request:7eee1ff7-b340-4bcf-beb0-c91f3587b556",
    "token": "L2RLZN7X",
    "status": "in_progress",
    "description": "A crew is scheduled for Thursday.",
    "updated_datetime": "2026-09-27T09:16:03.566Z",
    "updated_by": null,
    "media_url": null
  }
]

Try it

GET https://clear311.cloud.sweent.net/api/v2/servicerequestupdates.json

POST/api/v2/servicerequestupdates.json

Post a status update

For partner systems that do the work (a contractor’s work-order system, say): moves a request to a new status with a public note, as long as the move is allowed from its current status.

Access: Always needs an API key allowed to post updates. 60 calls a minute per key by default.

Parameters for Post a status update
ParameterRequiredDescription
api_keyYesYour key, or send it as an X-API-Key header.
service_request_idYesThe request ID or tracking number.
statusYesThe new status, e.g. in_progress or fixed.
descriptionYesThe public note residents will see.
update_idNoYour own ID for this update.
media_urlNoLink to one photo.
jurisdiction_idNoThis city’s ID (see discovery). Any other value is rejected with 400.
curl -X POST "https://clear311.cloud.sweent.net/api/v2/servicerequestupdates.json" \
  -H "X-API-Key: YOUR_KEY" \
  --data-urlencode "service_request_id=L2RLZN7X" \
  --data-urlencode "status=fixed" \
  --data-urlencode "description=Patched the pothole."
Example response · 200 OK
{
  "update_id": "service_request_update:service_request:7eee1ff7-b340-4bcf-beb0-c91f3587b556:2026-09-28T14-02-11-020Z:0a1b2c3d",
  "service_request_id": "service_request:7eee1ff7-b340-4bcf-beb0-c91f3587b556",
  "status": "success"
}

Questions about the API? Contact the City of Smithville 311 team, or read about City of Smithville 311.