Open311
App · 6 actions
Read and file 311 service requests with any city on Open311 (GeoReport v2): list service types and their questions, find and read requests by type, status and date, file new ones, and run when a request comes in or is closed.
Actions
| Action | What it does |
|---|---|
| File a service request | File a new service request (a 311 report) with the city, at an address or a point, with answers to the service type's questions and a photo. |
| Get service request | Get one service request: its status and the city's notes, the address and when it was filed and updated. |
| Get service request ID from token | Look up the id of a request filed with a token. |
| Get service type questions | Get the extra questions a service type asks when a request is filed, with the answers each allows and which are required. |
| List service requests | List the city's service requests, newest first, by type, status and when they were filed. |
| List service types | List every type of request the city takes (potholes, graffiti, missed pickups and so on) with its code, group and whether it asks extra questions. |
File a service request
File a new service request (a 311 report) with the city, at an address or a point, with answers to the service type's questions and a photo. Needs the city's API key.
Inputs
- Service type
service_codetextRequired - The type of request, such as a pothole or missed trash pickup.
- Description
descriptiontext - What the problem is, in the reporter's words.
- Address
addresstext - Where the problem is, such as 1 City Hall Square. Give an address, or a latitude and longitude, or both.
- Latitude
latitudenumber - The latitude of the problem, such as 42.3601.From -90 to 90.
- Longitude
longitudenumber - The longitude of the problem, such as -71.0589.From -180 to 180.
- Answers to the service type's questions
attributesobject - The extra questions the chosen service type asks, filled in for you once a service type is picked.
- Photo address
media_urltext - The https:// address of a photo of the problem.
- Reporter email
emailtext - The reporter's email address, for the city's updates.
- Reporter first name
first_nametext - The reporter's first name.
- Reporter last name
last_nametext - The reporter's last name.
- Reporter phone
phonetext - The reporter's phone number.
Outputs
account_idtext- The reporter's account with the city, if any
filedtrue/false- True once the city gave an id or a token
service_noticetext- What the city says to expect
service_request_idtext- The new request's id, empty while the city is still filing it
tokentext- A token to look the id up with later
Example output
{
"account_id": "",
"filed": true,
"service_notice": "The city will review this within 2 business days.",
"service_request_id": "",
"token": "9a4805cb-45e7-46d8-b8b7-04613bd57f3b"
}Get service request
Get one service request: its status and the city's notes, the address and when it was filed and updated.
Inputs
- Service request ID
service_request_idtextRequired - The request's id, from 'List service requests' or an earlier step.
Outputs
requestobject- The request
Example output
{
"request": {
"address": "60 Paul Sullivan Way, Boston, MA 02118",
"address_id": "",
"agency_responsible": "",
"description": "Litter in the bushes by the front door.",
"expected_datetime": "",
"lat": 42.342921,
"long": -71.0643375,
"media_url": "",
"requested_datetime": "2026-10-30T21:18:12Z",
"service_code": "155a5e9b-8c3a-4279-bbab-f6bba6ddb0d0",
"service_name": "Litter & Debris",
"service_notice": "",
"service_request_id": "47078e67-964d-4090-b9d2-155ae4d4f094",
"status": "open",
"status_notes": "",
"token": "9a4805cb-45e7-46d8-b8b7-04613bd57f3b",
"updated_datetime": "2026-10-30T22:45:57Z",
"zipcode": ""
}
}Get service request ID from token
Look up the id of a request filed with a token. Some cities give an id only once the request has been filed in their system; until then the id is empty.
Inputs
- Token
tokentextRequired - The token from 'File a service request'.
Outputs
readytrue/false- True once the request has an id
service_request_idtext- The request's id, empty until it has one
tokentext- The token looked up
Example output
{
"ready": true,
"service_request_id": "47078e67-964d-4090-b9d2-155ae4d4f094",
"token": "9a4805cb-45e7-46d8-b8b7-04613bd57f3b"
}Get service type questions
Get the extra questions a service type asks when a request is filed, with the answers each allows and which are required.
Inputs
- Service type
service_codetextRequired - The type of request, such as a pothole or missed trash pickup.
Outputs
attributeslist- The questions, in the order the city asks them
countnumber- How many
required_codeslist- The codes of the questions that need an answer
service_codetext- The service type
Example output
{
"attributes": [
{
"code": "BOSArePeoplePresentId",
"datatype": "singlevaluelist",
"datatype_description": "",
"description": "Are there people present?",
"order": 1,
"required": true,
"values": [
{
"key": "801fa657-2584-4ee7-b577-6d87c909d337",
"name": "Yes"
},
{
"key": "be13e3e4-bf04-4e91-9aa5-b311e3252869",
"name": "No"
}
],
"variable": true
}
],
"count": 1,
"required_codes": [
"BOSArePeoplePresentId"
],
"service_code": "8638e79a-2a0a-4d3a-9624-792ec40b0691"
}List service requests
List the city's service requests, newest first, by type, status and when they were filed.
Inputs
- Service type
service_codetext - Only requests of this type. Leave empty for every type.
- Status
statustext - Only open or only closed requests. Leave empty for both.One of:
open,closed. - Filed after
requested_afterdate and time - Only requests filed at or after this time. Most cities return the last 90 days when no range is given.
- Filed before
requested_beforedate and time - Only requests filed at or before this time.
- Most results
max_resultsnumber - How many requests to return at most, newest first, 1 to 1,000. Defaults to 100. Cities also cap how many they send at once.From 1 to 1000.
Outputs
countnumber- How many
requestslist- The service requests
total_returnednumber- How many the city sent, before 'Most results'
Example output
{
"count": 1,
"requests": [
{
"address": "60 Paul Sullivan Way, Boston, MA 02118",
"address_id": "",
"agency_responsible": "",
"description": "Litter in the bushes by the front door.",
"expected_datetime": "",
"lat": 42.342921,
"long": -71.0643375,
"media_url": "",
"requested_datetime": "2026-10-30T21:18:12Z",
"service_code": "155a5e9b-8c3a-4279-bbab-f6bba6ddb0d0",
"service_name": "Litter & Debris",
"service_notice": "",
"service_request_id": "47078e67-964d-4090-b9d2-155ae4d4f094",
"status": "open",
"status_notes": "",
"token": "9a4805cb-45e7-46d8-b8b7-04613bd57f3b",
"updated_datetime": "2026-10-30T22:45:57Z",
"zipcode": ""
}
],
"total_returned": 1
}List service types
List every type of request the city takes (potholes, graffiti, missed pickups and so on) with its code, group and whether it asks extra questions.
Inputs
None.
Outputs
countnumber- How many
serviceslist- The service types
Example output
{
"count": 1,
"services": [
{
"description": "",
"group": "Street Cleaning",
"keywords": "",
"metadata": true,
"service_code": "155a5e9b-8c3a-4279-bbab-f6bba6ddb0d0",
"service_name": "Litter & Debris",
"type": "batch"
}
]
}