Dockless Vehicles Developer Guide

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

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.

Step 1b:  Get Work Order Information

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

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: "

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"

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 4a:  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:

Step 4b:  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." 

Step 4c:  Update the Actual Finish Date NEW

There is one final step before closing or redirecting the work order below.  Use the WorkOrder/Update API method to update the work order and indicate the date/time you finished your evaluation.

For example:

• If you went to the field and resolved the submitted issue, the ActualFinishDate should reflect the date/time that resolution occurred. 
• If you evaluated the request and determined that the work order needed to be redirected (belongs to another operator), then the Actual Finish Date should reflect the date/time that determination occurred.

Expected date/time format:  "YYYY-MM-DDTHH:MM:SS".  This time value is made in Eastern Standard Time (EST).   For example:

• February 1st, 2022 at 11:35am:  "2022-02-01T11:35:00"

• February 2nd, 2022 at 3:31pm:  "2022-02-02T15:31:00"

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

• 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?