Tasks.

Tasks

Tasks represent units of work, defined by one destination and one recipient, that administrators create and assign to workers for completion.

Task assignment, state and dependencies are important concepts that you should understand well prior to using the task endpoints.

Create task

Note that you may provide the IDs of an existing recipient or destination if these are available, or simply include their details as objects to have these created automatically in a single request.

Body parameters

Name	Type	Description
merchant	string	Optional. The ID of the organization that will be displayed to the recipient of the task. Defaults to the creating organization. If you perform deliveries on behalf of a connected organization and want to display their name, logo, and branded notifications, provide their organization ID.
executor	string	Optional. The ID of the organization that will be responsible for fulfilling the task. Defaults to the creating organization. If you delegate your deliveries to a third party, provide their organization ID.
destination	string or object	The ID of the task's destination or a valid Destination object.
recipients	string array or object array	An array containing zero or one IDs of the task's recipients or a valid array of zero or one Recipient objects.
completeAfter	number	Optional. A timestamp for the earliest time the task should be completed.
completeBefore	number	Optional. A timestamp for the latest time the task should be completed.
pickupTask	boolean	Optional. Whether the task is a pickup task.
dependencies	string array	Optional. One or more IDs of tasks which must be completed prior to this task.
notes	string	Optional. Notes for the task. Field length should not exceed 10,000 characters.
autoAssign	object	Optional. Automatic assignment options to on-duty (state=1,2) drivers. You may not provide a container if using automatic assignment.
container	object	Optional. The container to which to append this task. Defaults to the creator organization container.
quantity	number	Optional. The number of units to be dropped off while completing this task, for route optimization purposes.
serviceTime	number	Optional. The number of minutes to be spent by the worker on arrival at this task's destination, for route optimization purposes.
recipientName	string	Optional override parameter. Override the recipient name for this task only.
recipientNotes	string	Optional override parameter. Override the recipient notes for this task only.
recipientSkipSMSNotifications	boolean	Optional override parameter. Override the recipient notification settings for this task only.
useMerchantForProxy	boolean	Optional override parameter. Override the organization ID to use the merchant orgID when set to true for this task only.
requirements	object	Optional. Set signature, photo, and/or notes completion requirement(s) for this task only.
scanOnlyRequiredBarcodes	boolean	Optional. Set restrictions to block the scanning of non-required barcodes.
appearance	object	Optional. Set triangle colored pins on the map.

curl -X POST "https://store.bponi.com/api/v2/tasks" \
       -u "cd3b3de84cc1ee040bf06512d233719c:" \
       -d '{"destination":{"address":{"unparsed":"2829 Vallejo St, SF, CA, USA"},"notes":"Small green door by garage door has pin pad, enter *4821*"},"recipients":[{"name":"Blas Silkovich","phone":"650-555-4481","notes":"Knows Neiman, VIP status."}],"completeAfter":1455151071727,"notes":"Order 332: 24oz Stumptown Finca El Puente, 10 x Aji de Gallina Empanadas, 13-inch Lelenitas Tres Leches","autoAssign":{"mode":"distance"}}'

1
2
3

{
  "id": "kc8SS1tzuZ~jqjlebKGrUmpe",
  "timeCreated": 1455156667000,
  "timeLastModified": 1455156667234,
  "organization": "yAM*fDkztrT3gUcz9mNDgNOL",
  "shortId": "8f983639",
  "trackingURL": "https://bponi.com/8f98363993",
  "worker": "1LjhGUWdxFbvdsTAAXs0TFos",
  "merchant": "yAM*fDkztrT3gUcz9mNDgNOL",
  "executor": "yAM*fDkztrT3gUcz9mNDgNOL",
  "creator": "EJmsbJgHiRLPjNVE7GEIPs7*",
  "dependencies": [],
  "state": 0,
  "completeAfter": 1455151071727,
  "completeBefore": null,
  "pickupTask": false,
  "notes": "Order 332: 24oz Stumptown Finca El Puente, 10 x Aji de Gallina Empanadas, 13-inch Lelenitas Tres Leches",
  "completionDetails": {
    "events": [],
    "time": null
  },
  "feedback": [],
  "metadata": [],
  "overrides": {
    "recipientSkipSMSNotifications": null,
    "recipientNotes": null,
    "recipientName": null
  },
  "container": {
    "type": "WORKER",
    "worker": "1LjhGUWdxFbvdsTAAXs0TFos"
  },
  "recipients": [
    {
      "id": "G7rcM2nqblmh8vj2do1FpaOQ",
      "organization": "yAM*fDkztrT3gUcz9mNDgNOL",
      "timeCreated": 1455156667000,
      "timeLastModified": 1455156667229,
      "name": "Blas Silkovich",
      "phone": "+16505554481",
      "notes": "Knows Neiman, VIP status.",
      "skipSMSNotifications": false,
      "metadata": []
    }
  ],
  "destination": {
    "id": "zrVXZi5aDzOZlAghZaLfGAfA",
    "timeCreated": 1455156667000,
    "timeLastModified": 1455156667220,
    "location": [
      -122.4438337,
      37.7940329
    ],
    "address": {
      "apartment": "",
      "state": "California",
      "postalCode": "94123",
      "country": "United States",
      "city": "San Francisco",
      "street": "Vallejo Street",
      "number": "2829"
    },
    "notes": "Small green door by garage door has pin pad, enter *4821*",
    "metadata": []
  },
  "didAutoAssign": true
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67

🚧 Override Feature

Despite the task object response contains a JSON blob named override, you should be passing the override parameters as a normal body parameter when creating a task.

❗️ Override Exception

The general override parameter works on the specific task when the parameter is successfully stored, the only exception being recipientSkipSMSNotifications. The condition for recipientSkipSMSNotifications override to work is when the recipient's skipSMSNotification flag is set to false.

In summary, if a recipient opted-out to receive SMS notification, task-level override for SMS notifications would not be applied.

🔔 Customizing Map Pins

The appearance object is now supported and is configurable through a triangleColor parameter.

"appearance": {"triangleColor": 1} The triangleColor parameter accepts 3 values: 0 for teal, 1 for orange, and 2 for magenta.

In addition to the properties available for task creation, tasks that have been assigned and are not yet started include an estimatedCompletionTime, which is the time we estimate that a task will be completed. The ECT includes transit (travel time from the departure point to the destination) and service time (time required to reach the recipient or dropoff point, complete the delivery, and return to the vehicle). If a serviceTime has been provided, we will use this if the task is inactive and will take the maximum of this value and our service time estimate if the task has entered the active state. If the task has been route optimized, we will use the service time from the route optimization solution. Finally, if a service time is not provided, we will always use the value from our model based on your organization's past performance.

An eta property is also available for active tasks (and workers) which you can use to access the number of seconds left for the task's worker to reach the recipient's door. This property is calculated by considering the worker's remaining transit time plus a time to reach the door which may vary by vehicle type and location.

Create tasks in batch

You may create up to 500 tasks in a single request by using this batch endpoint.

This is particularly helpful if you want to create unassigned tasks quickly for future assignment or optimization, without having to worry about orchestrating requests to avoid excessive contention around the organization container lock.

Automatic assignment is not currently supported by this endpoint. You will also not receive taskCreated webhook requests for batch task creations if you have registered for this trigger.

Processing will take place for all the tasks provided and you will receive a response with tasks containing the full details of the successfully created tasks and errors with any issues that may have been found. These errors contain both the error as well as the body provided for the problematic task so your integration can more easily react to the problem. Make sure that you increase your timeout value for this request as it could take considerably longer than others.

Note that the structure of the errors you may get from this endpoint is slightly different from the errors we send back when a request responds with a non-200 code. Batch errors include the following top-level properties: statusCode (number), error (number), message (string) and cause (string).

Body parameters

Name	Type	Description
tasks	object array	An array containing one or more task objects. Refer to the Create task endpoint section for a complete definition of the task object.

State

In addition to the parameters detailed for each endpoint in this section, tasks also have a special property state to help you understand the task's most recent status. The following integer values are valid task states:

Value	Description
0	Unassigned: task has not yet been assigned to a worker.
1	Assigned: task has been assigned to a worker.
2	Active: task has been started by its assigned worker.
3	Completed: task has been completed by its assigned worker. Includes both successful and failed completions.

A Task's state cannot be modified explicitly with the exception of Complete task

Automatic Assignment

You also have the option to automatically assign tasks to one of your currently active workers, that is, workers who are idle or in transit in the dashboard (worker state=[1,2]). Note that this is a basic assignment where the newly-created task is appended to the end of the optimal worker's container.

The autoAssign object property available at task creation has the following structure:

Name	Type	Description
mode	string	The desired automatic assignment mode. Either `distance` or `load`.
team	string	Optional. The ID of a team from which to pick the workers to consider for automatic assignment.
maxAssignedTaskCount	number	Optional. The maximum number of tasks a worker can have assigned after the automatic assignment is made.
considerDependencies	boolean	Optional. Whether to include the target task's dependency family (parent and child tasks) in the resulting assignment operation.
excludedWorkerIds	string array	Optional. One or more IDs of workers that should not be considered in assignment calculations.

In both modes, we calculate the geodesic distance using Vincenty's formula for ellipsoids between destination coordinates, with one meter precision.

The distance mode finds the active worker whose last-known location is closest to the task's destination.

The load mode walks the distance from the active worker's last-known location to their active task, if there is one, and through to each of the ordered destinations corresponding to the worker's assigned tasks, with the final computation being from their last-assigned task to the newly-created one. The worker who has to travel the shortest distance is considered to have the lightest load, and as such will be assigned the task being created.

If an automatic assignment is requested and successful, didAutoAssign will be set to true and the task's container details will indicate which worker the task was appended to. If we fail to find a suitable worker because of an error or any other unexpected condition, didAutoAssign will be false.

Note: maxAssignedTaskCount does not consider tasks that have been started - only assigned tasks are counted.

# Tasks

# Create task

# Body parameters

# Create tasks in batch

# Body parameters

# State

# Automatic Assignment

Tasks

Create task

Body parameters

Create tasks in batch

Body parameters

State

Automatic Assignment