Back to Documentation Overview

Switch from Ridehail APIs to Dispatch APIs

This guide will help you migrate from our Ridehail API to our new Dispatch API.

Fleets

ActionRidehail Call(s)Example RequestDispatch Call(s)Example Request
Get all fleets for account ride-hail-operations/v1/
GetFleets		 
{}
dispatch-fleets/v3/
GetAllFleets		 ```json {} ```
Create a new Fleet ride-hail-operations/v1/
CreateFleet		 
{
  "id": "fleet-1",
  "info": {
    "displayName": "Fleet 1",
    "properties": { 
      "key": "value" 
    }
  },
  "optimizationSettings": {
    "forcePrivateRides": true
  }
}
dispatch-fleets/v3/
CreateFleet		 
{
  "fleetId": "fleet-1",
  "displayName": "Fleet 1",
  "metadata": {
    "data": { 
      "key": "value" 
    }
  },
  "optimizationSettings": {
    "forcePrivateRides": true
  }
}
Update an existing fleet ride-hail-operations/v1/
UpdateFleet		 
{
 "id": "fleet-1",
 "updatedFleetInfo": {
   "displayName": "Fleet 1 (New)",
   "properties": {
     "properties": { 
       "key": "value (New)" 
     }
   },
   "optimizationSettings": {
     "forcePrivateRides": false
   }
 }
}
dispatch-fleets/v3/
UpdateFleet		 
{
 "fleetId": "fleet-1",
 "updatedDisplayName": "Fleet 1 (New)",
 "updatedMetadata": {
   "data": { 
     "key": "value (New)" 
   }
 },
 "updatedOptimizationSettings": {
   "forcePrivateRides": false
 }
}
Remove an existing fleet ride-hail-operations/v1/
RemoveFleet		 
{
  "id": "fleet-1"
}
dispatch-fleets/v3/
DeleteFleet		 
{
  "fleetId": "fleet-1"
}

Vehicles

ActionRidehail Call(s)Example RequestDispatch Call(s)Example Request
Create new vehicle ride-hail-driver/v1/
CreateVehicle		 
{
  "id": "vehicle-1",
  "fleetId": "fleet-1",
  "definition": {
    "riderCapacity": 4
  },
  "info": {
    "licensePlate": "abc123",
    "driverInfo": {
      "contactInfo": {
        "name": "name",
        "phoneNumber": "123-4567",
        "contactUrl": "web.com"
      }
    },
    "properties": {
      "key": "value"
    }
  }
}
dispatch-vehicles/
v3/
CreateVehicle		 
{
  "vehicleId": "vehicle-1",
  "fleetId": "fleet-1",
  "vehicleCapacities": [
    {
      "capacityType": "seats",
      "value": 4
    }
  ],
  "metadata": {
    "data": {
      "license-plate": "abc123",
      "driver-name": "name",
      "driver-phone": "123-4567",
      "driver-url": "web.com",
      "key": "value"
    }
  }
}
Get all vehicles in fleet ride-hail-operations/v1/
GetVehicles		 
{
  "fleetId": "fleet-1"
}
dispatch-vehicles/
v3/
GetVehiclesInFleet		 
{
  "fleetId": "fleet-1"
}
Update an existing vehicle ride-hail-driver/v1/
UpdateVehicle

OR

ride-hail-operations/v1/
UpdateVehicle		 
{
  "id": "vehicle-1",
  "fleetId": "fleet-1",
  "updatedVehicleInfo": {
    "licensePlate": "n3w",
    "driverInfo": {
      "contactInfo": {
        "name": "name",
        "phoneNumber": "123-4567",
        "contactUrl": "web.com"
      }
    },
    "properties": {
      "properties": {
        "key": "value (New)"
      }
    }
  }
}
dispatch-vehicles/v3/
UpdateVehicle		 
{
  "vehicleId": "vehicle-1",
  "updatedMetadata": {
    "data": {
      "license-plate": "n3w",
      "driver-name": "name",
      "driver-phone": "123-4567",
      "driver-url": "web.com",
      "key": "value (New)"
    }
  }
}
Update whether a vehicle is accepting new tasks ride-hail-driver/v1/
UpdateVehicleState

OR

ride-hail-operations/v1/
UpdateVehicleState		 
{
  "id": "vehicle-1",
  "setToAcceptRides": {}
}
dispatch-vehicle-state/v3/
UpdateVehicleState		 
{
  "vehicleId": "vehicle-1",
  "updatedAcceptingAssignments": true
}
Update a vehicle’s position ride-hail-driver/v1/
UpdateVehicleState		 
{
  "id": "vehicle-1",
  "updatedPosition": {
    "position": {
      "latitude": 35,
      "longitude": 36
    }
  },
  "updatedHeading": 90,
  "recordedAt": "2020-07-22T22:50:46Z"
}
dispatch-vehicle-position/v3/
UpdateVehiclePosition		 
{
  "vehicleId": "vehicle-1",
  "vehiclePosition": {
    "position": {
      "latitude": 35,
      "longitude": 36
    },
    "heading": 90
  },
  "recordedAt": "2020-07-22T22:50:46Z"
}
Remove an existing vehicle ride-hail-driver/v1/
RemoveVehicle		 
{
  "id": "vehicle-1"
}
dispatch-vehicles/v3/
DeleteVehicle		 
{
  "vehicleId": "vehicle-1"
}
Get eyeball ETAs to rider position ride-hail-rider/v1/
GetVehicleEtasToPosition		 
{
  "fleetId": "fleet-1",
  "position": { 
    "latitude": 35,
    "longitude": 36
  }
}
dispatch-vehicle-eta/v3/
GetVehicleEtasToPosition		 
{
  "fleetId": "fleet-1",
  "position": { 
    "latitude": 35,
    "longitude": 36
  }
}

Trips

ActionRidehail Call(s)Example RequestDispatch Call(s)Example Request
Get static information about a trip ride-hail-rider/v1/
GetTripDefinition

OR

ride-hail-rider/v1/
GetTripInfo

OR

ride-hail-driver/v1/
GetTripInfo		 
{
  "id": "trip-1"
}
dispatch-tasks/v3/
GetTask		 
{
  "taskId": "trip-1"
}
Get all active trips in a fleet ride-hail-operations/v1/
GetTrips		 
{
  "fleetId": "fleet-1"
}
dispatch-tasks/v3/
GetTasksByTime		 
{
  "fleetId": "fleet-1"
}
Get a trip’s state and information about the assigned vehicle ride-hail-rider/v1/
GetTripStateRC		 
{
  "id": "trip-1"
}
dispatch-tasks/v3/
GetTask
(returns assigned vehicle ID)		 
{
  "taskId": "trip-1"
}
dispatch-vehicle-position/v3/
GetVehiclePosition		 
{
  "vehicleId": "assigned-vehicle"
}
dispatch-vehicle-state/v3/
GetVehicleState		 
{
  "vehicleId": "assigned-vehicle"
}
dispatch-vehicle-eta/v3/
GetVehicleStepEtas		 
{
  "vehicleId": "assigned-vehicle"
}
Request a new passenger trip ride-hail-rider/v1/
RequestTripRC		 
{
  "id": "trip-1",
  "riderId": "rider-1",
  "fleetId": "fleet-1",
  "definition": {
    "pickupDropoff": {
      "pickup": {
        "position": {
          "latitude": 35,
          "longitude": 36
        }
      },
      "dropoff": {
        "position": {
          "latitude": 37,
          "longitude": 38
        }
      },
      "riderCount": 4
    }
  },
  "info": {
    "riderInfo": {
      "contactInfo": {
        "name": "name",
        "phoneNumber": "123-4567",
        "contactUrl": "web.com"
      }
    },
    "properties": {
      "key": "value"
    }
  },
  "dispatchParameters": {
    "timeoutInMs": 60000
  }
}
dispatch-tasks/v3/
CreateTask		 
{
  "taskId": "trip-1",
  "fleetId": "fleet-1",
  "taskDefinition": {
    "pickupDropoffTask": {
      "uniqueResourcePickup": {
        "pickupLocation": {
          "position": {
            "latitude": 35,
            "longitude": 36
          }
        },
        "uniqueResource": {
          "requiredCapacities": [
            {
              "capacityType": "seats",
              "value": 4
            }
          ],
          "metadata": {
            "data": {
              "rider-name": "name",
              "rider-phone": "123-4567",
              "rider-url": "web.com"
            }
          }
        }
      },
      "dropoff": {
        "position": {
          "latitude": 37,
          "longitude": 38
        }
      }
    },
    "dispatchParameters": {
      "timeout": "60s"
    },
    "requestorId": "rider-1"
  },
  "metadata": {
    "data": {
      "key": "value"
    }
  }
}
Complete one or more steps in a trip ride-hail-driver/v1/
CompleteSteps		 
{
  "vehicleId": "vehicle-1",
  "tripId": "trip-1",
  "stepsToComplete": [
    {
      "stepId": "step-1",
      "completionTime": "2020-07-22T22:50:46Z"
    }
  ]
}
dispatch-tasks/v3/
CompleteSteps		 
{
  "taskId": "trip-1",
  "stepsToComplete": [
    {
      "stepId": "step-1",
      "timeOfCompletion": "2020-07-22T22:50:46Z"
    }
  ]
}
Cancel an active trip ride-hail-driver/v1/
CancelTrip

OR

ride-hail-rider/v1/
CancelTrip

OR

ride-hail-operations/v1/
CancelTrip		 
{
  "id": "trip-1",
  "description": "oops"
}
dispatch-tasks/v3/
CancelTask		 
{
  "taskId": "trip-1",
  "source": "VEHICLE",
  "description": "oops"
}
Reject a trip assigned to a vehicle ride-hail-driver/v1/
RejectTrip		 
{
  "tripId": "trip-1",
  "vehicleId": "vehicle-1",
  "description": "no time"
}
dispatch-tasks/v3/
RejectTask		 
{
  "taskId": "trip-1",
  "rejectingVehicleId": "vehicle-1",
  "description": "no time"
}
Unassign a trip from a vehicle ride-hail-operations/v1/
UnassignTrip		 
{
  "tripId": "trip-1",
  "vehicleId": "vehicle-1"
}
dispatch-tasks/v3/
UnassignTask		 
{
  "taskId": "trip-1",
  "vehicleId": "vehicle-1"
}
Update trip metadata ride-hail-operations/v1/
UpdateTrip		 
{
  "id": "trip-1",
  "propertyUpdate": {
    "properties": {
      "key": "value"
    }
  }
}
dispatch-tasks/v3/
UpdateTask		 
{
  "taskId": "trip-1",
  "updatedMetadata": {
    "data": {
      "key": "value"
    }
  }
}