Using tasks

The Task object represents a pickup, delivery, visit or any other transaction event that is performed by a Driver on a Trip. A Task can have a destination and an ETA, and can be tracked in real-time by customers - on the web or inside an app.

In this guide, we will cover how to assign Tasks to Drivers, and implement Trips for your use-case.

Assigning Tasks to Driver

The simple use-case for Tasks is assigning them to a Driver. When a task is assigned to a driver, a Trip starts. When the Task is completed, the Trip automatically ends.

This way, you can assign multiple Tasks to a Driver, and the Trip will end when all Tasks have been completed.

[info] Connect SDK

If the SDK in the app is connected with the same driver id, the app will start tracking at this point. Read more about the SDK integration.

curl -H "Authorization: token YOUR_SK_TOKEN" \
     -H "Content-Type: application/json" \
     -X POST \
     -d "{\"task_ids\": [\"6daacb03-6f02-4c60-b084-e9ffcd9eaf56\", \"37ae09b4-4801-48cb-bc50-99a7ee53f257\"]}" \

Reassigning Tasks

Before they get completed, Tasks can be reassigned to other Drivers, using the same API call.

Tasks on Trips

If you are looking for greater control over how Tasks are managed in a Trip, create a Trip.

Create a Trip with Tasks

Parameter Required Description
tasks No List of zero or more task ids to be assigned to the trip.
driver_id No Driver of the Trip. If not specified, a temporary Driver is created and the id is returned in the response.
has_ordered_tasks No Set as true if the tasks have a well defined sequence or route. The task ETAs can be inferred in this case. Default is false.
is_auto_ended No Set as false if the trip should be live after the last task has ended. Default is true.

[warning] End tracking

If is_auto_ended is false, you will need to end the trip manually with the id of the trip object.

curl -H "Authorization: token YOUR_PK_TOKEN" \
     -H "Content-Type: application/json" \
     -X POST \
     -d "{\"tasks\": [\"6daacb03-6f02-4c60-b084-e9ffcd9eaf56\", \"37ae09b4-4801-48cb-bc50-99a7ee53f257\"],
          \"driver_id\": \"d0ae4912-2074-45ef-a7c0-76be58639ea9\"}" \

[info] Optional parameters

All parameters in this API call are optional. If you do not specify a driver_id, a new temporary driver object will be created.

Add Tasks to a live Trip

You can add Tasks to a live Trip with the add_task API call. Only tasks that have not been completed can be added to a new Trip. For this API call, you will need the trip_id and the task_id.

curl -H "Authorization: token test_token" \
     -H "Content-Type: application/json" \
     -X POST \
     -d "{\"task_id\":\"3a36b6df-a7e7-40d0-86b7-b5aae1ce3a2b\"}" \

Remove Tasks from a live Trip

It is possible to remove an existing Task from a live Trip. Tasks that are removed can be reassigned to other Trips. For this API call, you will need the trip_id and the task_id.

Keep in mind that not all Tasks can be removed. Tasks which have started cannot be removed, but they can be canceled. Tasks which have been completed cannot be modified.

curl -H "Authorization: token test_token" \
     -H "Content-Type: application/json" \
     -X POST \
     -d "{\"task_id\":\"3a36b6df-a7e7-40d0-86b7-b5aae1ce3a2b\"}" \

Changing the sequence of Tasks

The sequence of Tasks in a live Trip can also be modified. For this API call, you need the trip_id and the new sequence of task_ids. The new sequence needs to have all task_ids of the Trip, including the ones that are completed.

curl -H "Authorization: token test_token" \
     -H "Content-Type: application/json" \
     -X POST \
     -d "{\"task_order\":[\"3a36b6df-a7e7-40d0-86b7-b5aae1ce3a2b\", \"77b9a3fa-a3ab-4840-aadb-cd33442ca45b\"]}" \

Was this helpful? Yes, thanks! Not really

results matching ""

    No results matching ""