# Open311

> 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.

App · 6 actions. Web page: https://docs.lodol.com/docs/integrations/open311

## Actions

### 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_code`, text, required): The type of request, such as a pothole or missed trash pickup.
- Description (`description`, text): What the problem is, in the reporter's words.
- Address (`address`, text): Where the problem is, such as 1 City Hall Square. Give an address, or a latitude and longitude, or both.
- Latitude (`latitude`, number): The latitude of the problem, such as 42.3601. From -90 to 90.
- Longitude (`longitude`, number): The longitude of the problem, such as -71.0589. From -180 to 180.
- Answers to the service type's questions (`attributes`, object): The extra questions the chosen service type asks, filled in for you once a service type is picked.
- Photo address (`media_url`, text): The https:// address of a photo of the problem.
- Reporter email (`email`, text): The reporter's email address, for the city's updates.
- Reporter first name (`first_name`, text): The reporter's first name.
- Reporter last name (`last_name`, text): The reporter's last name.
- Reporter phone (`phone`, text): The reporter's phone number.

**Outputs**

- `account_id` (text): The reporter's account with the city, if any
- `filed` (true/false): True once the city gave an id or a token
- `service_notice` (text): What the city says to expect
- `service_request_id` (text): The new request's id, empty while the city is still filing it
- `token` (text): A token to look the id up with later

**Example output**

```json
{
  "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_id`, text, required): The request's id, from 'List service requests' or an earlier step.

**Outputs**

- `request` (object): The request

**Example output**

```json
{
  "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 (`token`, text, required): The token from 'File a service request'.

**Outputs**

- `ready` (true/false): True once the request has an id
- `service_request_id` (text): The request's id, empty until it has one
- `token` (text): The token looked up

**Example output**

```json
{
  "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_code`, text, required): The type of request, such as a pothole or missed trash pickup.

**Outputs**

- `attributes` (list): The questions, in the order the city asks them
- `count` (number): How many
- `required_codes` (list): The codes of the questions that need an answer
- `service_code` (text): The service type

**Example output**

```json
{
  "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_code`, text): Only requests of this type. Leave empty for every type.
- Status (`status`, text): Only open or only closed requests. Leave empty for both. One of: `open`, `closed`.
- Filed after (`requested_after`, date 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_before`, date and time): Only requests filed at or before this time.
- Most results (`max_results`, number): 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**

- `count` (number): How many
- `requests` (list): The service requests
- `total_returned` (number): How many the city sent, before 'Most results'

**Example output**

```json
{
  "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**

- `count` (number): How many
- `services` (list): The service types

**Example output**

```json
{
  "count": 1,
  "services": [
    {
      "description": "",
      "group": "Street Cleaning",
      "keywords": "",
      "metadata": true,
      "service_code": "155a5e9b-8c3a-4279-bbab-f6bba6ddb0d0",
      "service_name": "Litter & Debris",
      "type": "batch"
    }
  ]
}
```
