This guide is intended for all dockless vehicle companies who are permitted to operate within Washington, DC.

In order to follow this guide, you must have a Cityworks username/password from DDOT's IT department. If you do not have one, please contact the DDOT Dockless Program Manager (Sharada Strasmore) and they will request one on your behalf.

Workflow Diagram

Below is a draft diagram of the workflow

DDOT Workflows

The below information is provided to give some background/context about how the data starts at 311 and eventually is provided to an operator.

Step A: 311 Request for Dockless Vehicle Issue

The process kicks off with a dockless vehicle complaint/issue request in the DC 311 system. The resident will submit a request and provide information on the issue they see. These requests are called "Service Requests". The user shall provide;

the vehicle type;
the address or XY coordinates;
the company responsible for the vehicle;
the issue with the vehicle; and
may provide a picture.

Step B: DDOT Processes Dockless Vehicles Issues

As part of an established process, DDOT accesses the 311 system and captures all service requests which fall under DDOT's responsibility. This will now include dockless vehicle complaints. In this step, DDOT inspects the service request for the dockless vehicle operator (a required field from 311) and will create a Work Order at the same location for that specific operator. (note: in the diagram to the right, we use the hypothetical operator 'XYZ')

Dockless Operator Workflows

Review the Documentation

Review the introductory API documentation. This will give you guidance and examples on how to authenticate, make requests and what responses you should expect.

See official Cityworks API documentation. This is the current documentation available on our public-facing 'Demo' server. The CW Demo server be your test environment prior to building for production.

Step 0: Authentication

Use the Authentication/Authenticate method, passing in your username and password to retrieve a token. You will pass this token with every request you make to the Cityworks API.

Step 1a: Query for open work orders

Using the WorkOrder/Search method, you can provide your specific template IDs and Status = Open as a filtering attribute to get a list of all Open Work Orders. You should store this work order ID in your internal system to reference it later.

Please limit your Open Work Order query frequency to a maximum of one request every 5 minutes. This will help to reduce load on our servers and allow them to perform optimally.

We reserve the right to suspend accounts of those users who violate this

Step 1b: Get Work Order Information

Below are some of the relevant fields that are important for the Dockless vehicle company:

Cityworks WO Fieldname	Definition
WorkOrderId	The ID number for the Cityworks work order
Location	The nearest address to the complaint location. 311 This text location may not identically match to the map coordinates listed below. In most cases, the map coordinates should represent a more precise location.
WOTemplateId	The Cityworks work order template ID. (unique to each company)
WOXCoordinate	The X Coordinate 311 All map coordinates are presented in Maryland State Plane coordinate system (WKID: 26985). If you need to convert to Lat/Long or another projection, there are a number of online tools available. See the linked guidance on the topic.
WOYCoordinate	The Y Coordinate 311 All map coordinates are presented in Maryland State Plane coordinate system (WKID: 26985). If you need to convert to Lat/Long or another projection, there are a number of online tools available. See the linked guidance on the topic.
InitiatedDate	The datetime the Cityworks work order was created.
Status	The current status of the Cityworks work order. Open - the initial status of the work order Pending - the status you will update to and indicate you have the work order information Closed - this status indicates that you have investigated the problem and resolved the issue QA Rejected - this status indicates that you have investigated the issue and found the vehicle does not belong to you. (see 'Redirect' workflow below)
TEXT1	Which company operates this dockless device? 311
TEXT2	Where is this vehicle located? 311
TEXT3	What is the vehicle ID? (Located on top of vehicle) 311
TEXT4	What is the parking issue that you are reporting about the vehicle? 311
TEXT5	See Comments if photo/images available 311

Step 1c: Get Image URL(s) if Available

The TEXT5 field in the Work Order will let you know if one or more photos is available with the text "Check comment section for images". If this text appears, please query the WorkOrder/Comments method to retrieve the picture URLs. Each image will be preceded by the text "Image From 311: "

The URL may need to be decoded prior to using (remove ampersands, etc)

Step 2: Acknowledge Receipt of the Complaint

Now that you have all the details about each work order, you must update the status for each work order to Pending. This status change essentially signals to DDOT that you acknowledge the request and that action will be taken.

To change the status of a Work Order, you must use the by using the WorkOrder/Update method, passing in WorkOrderId = "the Work Order ID"

It is required for you to update the status to "Pending" within 11 minutes of the Initiated Date (this is the time the Work Order was created).

Step 3: Operator Investigates the Problem

At this step, the dockless operator will go to the location, using the X,Y geographic location provided in the work order.

Take a picture of the problem location, even if the vehicle is not there. (this will prove that an investigation was done)
If the vehicle in question belongs to the Dockless Operator, they will resolve the issue. Notes/comments are optional.
If the vehicle belongs to another operator, the Dockless Operator will make a note of which operator the vehicle belongs to and provide a comment/note about the misassigned issue.

Step 4: Update the Work Order with the Resolution

Upload Picture to Work Order. Each work order must have a picture uploaded showing the investigation. Preferably, this is a picture of the status of the vehicle prior to the resolution. For example, a 311 complaint is submitted for a scooter that is hanging on a fence. DDOT would like a picture of the location prior to removing the scooter from the fence. To upload a picture on the work order, you must use Attachments/AddWorkOrderAttachment method, passing in WorkOrderId, Filename as well as optional Comments.
- Make as a 'POST' request
- As an example, your 'data' object should be passed like so: data={"Comments": null,"Filename": "MyScooterPic.png","TaskId": null,"WorkOrderId": "1019195"}

Below is an example screen capture from Postman of how this call should be made:

Add a comment (conditional). Operators are welcome to provide a comment in Cityworks about the work that was performed. For typical cases, this is not requirement. To make a comment on the work order, you must use WorkOrder/AddComments method, passing in WorkOrderId = "the Work Order ID" as well as Comments = "Your work order comments."

NOTE: If in your investigation you find that the vehicle belongs to a different operator, you are required to add a comment and note which operator it belongs to.

Step 5: Close or Complete Updates on the Work Order

Resolved Issue. If you have gone to the location, found your vehicle and corrected the issue, you must close the work order in the Cityworks system. In order to close a work order, you must use WorkOrder/Close

If you are Resolving multiple work order issues, you are allowed to perform a bulk closure of work orders. Simply pass a listing of Work Order IDs when using WorkOrder/Close

Need to Redirect Issue. If you have investigated the issue and found that the vehicle belongs to another company, you must perform two additional updates to the work order:
- Update Status to "QA Rejected"
- Update TEXT6 to <insert the name of the company the vehicle belongs to>. The acceptable list of options is below:
- Values
  Bird
  Lime
  Lyft
  Helbiz
  Spin
  Jump
  Other

- If 'Other', then a comment is required on the work order. See Step 4 for guidance on comments.

Step 6: Done

Process is now complete! Return to Step 1a to query for more open work orders.

Frequently Asked Questions (FAQ)

Who Can We Contact if we Have Questions?

Email to DDOT's Dockless Program Manager sharada.strasmore@dc.gov for all other issues/questions:
Email to ddotgis@dc.gov for any technical issues with the Cityworks system.

What happens if Cityworks API service(s) Go Down?

Send email to ddotgis@dc.gov if there is an issue persisting beyond 11 mins. Please provide:
- Full error message data
- Request URL + parameters attempted
- Step-by-step summary of workflow and attempted calls preceding the error
- Screenshots, if helpful

How Do We Get Access to the Cityworks API?

Please contact the DDOT Dockless Program Manager Sharada Strasmore at sharada.strasmore@dc.gov.

What are the Fields in DC's 311 Request for Dockless Vehicle Complaints?

311 Form Question	Response Type	Required?
Which company operates this dockless device?	Bird (scooter) Lime (scooter) Lyft (scooter) Helbiz (scooter) Spin (scooter) Lime (bike)	REQUIRED
Please provide further information about the location of this vehicle?	<free text response>	REQUIRED
What is the vehicle ID?	<free text response>	REQUIRED
What is the parking issue that you are reporting about the vehicle?	<free text response>	REQUIRED
Please attach a photo of this issue	<File/image>
Any other information that you would like to share?	<free text response>

Browser not supported