Workers

Workers (also known as drivers in the dashboard) are the members of an organization who perform actions via the Bponi Storeopen in new window mobile applications. They may belong to teams managed by any number of administrators in their own organization. Workers have a vehicle with which tasks are completed.

Create worker

Creating a new worker generates a temporary password which is sent to the worker’s phone by SMS along with download details for the worker iOS and Android mobile apps.

The worker will be able to set a permanent password when first logging in to the application.

Body parameters

NameTypeDescription
namestringThe worker’s complete name.
phonestringA valid phone number as per the worker’s organization’s country.
teamsstring arrayOne or more team IDs of which the worker is a member.
vehicleobjectOptional. The worker’s vehicle; providing no vehicle details is equivalent to the worker being on foot.
capacitynumberOptional. The maximum number of units this worker can carry, for route optimization purposes.
displayNamestringOptional. This value is used in place of the worker's actual name within sms notifications, delivery tracking pages, and across organization boundaries (connections).

🔔 Worker Image

Note that a worker's image can only be set through the dashboard or by themselves on the mobile app.

curl -X POST "https://store.bponi.com/api/v2/workers" \
       -u "cd3b3de84cc1ee040bf06512d233719c:" \
       -d '{"name":"A Swartz","phone":"617-342-8853","teams":["nz1nG1Hpx9EHjQCJsT2VAs~o"],"vehicle":{"type":"CAR","description":"Tesla Model 3","licensePlate":"FKNS9A","color":"purple"}}'
1
2
3
{
  "id": "sFtvhYK2l26zS0imptJJdC2q",
  "timeCreated": 1455156653000,
  "timeLastModified": 1455156653214,
  "organization": "yAM*fDkztrT3gUcz9mNDgNOL",
  "name": "A Swartz",
  "displayName": "AS",
  "phone": "+16173428853",
  "activeTask": null,
  "tasks": [],
  "onDuty": false,
  "timeLastSeen": null,
    "capacity": 0,
  "userData": {
    "appVersion": "1.2.0",
    "batteryLevel": 0.99,
    "deviceDescription": "iPhone XS",
    "platform": "IOS"
  },
  "accountStatus": "ACCEPTED",
  "metadata": [],
  "imageUrl":  null,
  "teams": [
    "nz1nG1Hpx9EHjQCJsT2VAs~o"
  ],
  "delayTime": null,
  "vehicle": {
    "id": "tN1HjcvygQWvz5FRR1JAxwL8",
    "type": "CAR",
    "description": "Tesla Model 3",
    "licensePlate": "FKNS9A",
    "color": "purple",
    "timeLastModified": 154086815176
  }
}
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
{
  "code": "InvalidArgument",
  "message": {
    "error": 1900,
    "message": "One or more parameters required for this request are either missing or have an invalid format.",
    "cause": "Team IDs array missing",
    "request": "bc41a8eb-a604-4a1c-aa5a-e86a975c141b"
  }
}
1
2
3
4
5
6
7
8
9
{
  "code": "InvalidContent",
  "message": {
    "error": 1000,
    "message": "The values of one or more parameters are invalid.",
    "cause": "Invalid phone number format",
    "request": "fff8ed50-4ca0-4ff9-9230-b73096eb8502"
  }
}
1
2
3
4
5
6
7
8
9
{
  "code": "InvalidContent",
  "message": {
    "error": 1004,
    "message": "The values of one or more parameters break a uniqueness constraint.",
    "cause": {
      "type": "duplicateKey",
      "key": "unknown",
      "value": "unknown"
    },
    "request": "3eafc877-278c-40d1-993b-2acf2575c7d8"
  }
}
1
2
3
4
5
6
7
8
9
10
11
12
13

A vehicle has the following properties:

NameTypeDescription
typestringThe vehicle’s type, must be one of CAR, MOTORCYCLE, BICYCLE or TRUCK.
descriptionstringOptional. The vehicle’s make, model, year, or any other relevant identifying details.
licensePlatestringOptional. The vehicle’s license plate number.
colorstringOptional. The vehicle's color.

delayTime is a special property providing the amount of time in seconds that a worker is delayed by, based on the maximum delayTime of all assigned tasks, or null if the worker is not delayed. This is updated every minute if the worker is on-duty, or every 10 minutes if the worker is off-duty. To find out more about delayed statuses, see the delayTime part of our Tasks section or check out this support center entry. imageUrl will also be provided if a worker image has been configured.

The required parameters will need to be correctly formatted in order for the request to go through. In cases where duplicated phone numbers are used within your organization, a duplicateKey error will be returned.

List workers

Returns a collection of all workers in your organization.

Query parameters

NameTypeDescription
filterstringOptional. A comma-separated list of fields to return, if all are not desired. For example, name, location.
teamsstringOptional. A comma-separated list of the team IDs that workers must be part of.
statesstringOptional. A comma-separated list of worker states, where 0 is off-duty, 1 is idle (on-duty, no active task) and 2 is active (on-duty, active task).
phonesstringOptional. A comma-separated list of workers' phone numbers.
curl -X GET "https://store.bponi.com/api/v2/workers?states=1" \
       -u "cd3b3de84cc1ee040bf06512d233719c:"
1
2
[
  {
    "id": "h*wSb*apKlDkUFnuLTtjPke7",
    "timeCreated": 1455049674000,
    "timeLastModified": 1455156646529,
    "organization": "yAM*fDkztrT3gUcz9mNDgNOL",
    "name": "Andoni",
    "displayName": "Andoni",
    "phone": "+14155558442",
    "activeTask": null,
    "tasks": [
      "11z1BbsQUZFHD1XAd~emDDeK"
    ],
    "onDuty": true,
    "timeLastSeen": 1455156644323,
    "capacity": 0,
    "userData": {
        "appVersion": "1.2.0",
      "batteryLevel": 0.99,
      "deviceDescription": "Simulator (iOS 12.1.0)",
      "platform": "IOS"
    },
    "accountStatus": "ACCEPTED",
    "metadata": [
          {
        "name": "nickname",
        "type": "string",
        "value": "Puffy",
        "visibility": [
          "api"
        ]
      },
      {
        "name": "otherDetails",
        "type": "object",
        "value": {
          "availability": {
            "mon": "10:00",
            "sat": "16:20",
            "wed": "13:30"
          },
          "premiumInsurance": false,
          "trunkSize": 9.5
        },
        "visibility": [
          "api"
        ]
      }
    ],
    "imageUrl": null,
    "teams": [
      "R4P7jhuzaIZ4cHHZE1ghmTtB"
    ],
    "delayTime": null,
    "location": [
      -122.4015496466794,
      37.77629837661284
    ],
    "vehicle": null
  },
  {
    "id": "1LjhGUWdxFbvdsTAAXs0TFos",
    "timeCreated": 1455049755000,
    "timeLastModified": 1455072352267,
    "organization": "yAM*fDkztrT3gUcz9mNDgNOL",
    "name": "Yevgeny",
    "displayName": "YV",
    "phone": "+14155552299",
    "activeTask": null,
    "tasks": [
      "*0tnJcly~vSI~9uHz*ICHXTw",
      "PauBfRH8gQCjtMLaPe97G8Jf"
    ],
    "onDuty": true,
    "timeLastSeen": 1455156649007,
    "capacity": 0,
    "userData": {
        "appVersion": "1.2.0",
      "batteryLevel": 0.97,
      "deviceDescription": "Galaxy S8",
      "platform": "Android"
    },
    "accountStatus": "ACCEPTED",
    "metadata": [],
    "location": [
      -122.4016366,
      37.7764098
    ],
    "imageUrl": null,
    "teams": [
      "9dyuPqHt6kDK5JKHFhE0xihh",
      "yKpCnWprM1Rvp3NGGlVa5TMa",
      "fwflFNVvrK~4t0m5hKFIxBUl"
    ],
    "delayTime": null,
    "vehicle": {
      "id": "ArBoHNxS4B76AiBKoIawY9OS",
      "type": "CAR",
      "description": "Lada Niva",
      "licensePlate": "23KJ129",
      "color": "Red",
      "timeLastModified": 1545086815176
    }
  }
]
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
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105

The index of each id in the tasks array indicates the order of assigned tasks for that worker.

Get workers by location

You may provide a coordinate pair along with a radius to get a list of workers who are currently within a certain target area.

Query parameters

NameTypeDescription
longitudenumberThe longitude component of the coordinate pair.
latitudenumberThe latitude component of the coordinate pair.
radiusnumberOptional. The length in meters of the radius of the spherical area in which to look for workers. Defaults to 1000 if missing. Maximum value is 10000.
curl -X GET "https://store.bponi.com/api/v2/workers/location?longitude=-122.41275787353516&latitude=37.78998061344339&radius=6000" \
       -u "cd3b3de84cc1ee040bf06512d233719c:"
1
2
{
  "workers": [
    {
      "id": "h*wSb*apKlDkUFnuLTtjPke7",
      "timeCreated": 1458416497000,
      "timeLastModified": 1478383350446,
      "organization": "yAM*fDkztrT3gUcz9mNDgNOL",
      "name": "Andoni",
      "displayName": "Andoni",
      "phone": "+14155558442",
      "activeTask": "kc8SS1tzuZ~jqjlebKGrUmpe",
      "tasks": [
        "11z1BbsQUZFHD1XAd~emDDeK",
        "kc8SS1tzuZ~jqjlebKGrUmpe"
      ],
      "onDuty": true,
      "isResponding": true,
      "timeLastSeen": 1480385504517,
      "capacity": 0,
      "userData": {
         "appVersion": "1.2.0",
         "batteryLevel": 0.99,
         "deviceDescription": "Simulator (iOS 12.1.0)",
         "platform": "IOS"
      },
      "accountStatus": "ACCEPTED",
      "metadata": [],
      "imageUrl": null,
      "capacity": 0,
      "userData": {},
      "location": [
        -122.4088934,
        37.7593079
      ],
      "delayTime": 1650,
      "vehicle": {
        "id": "ArBoHNxS4B76AiBKoIawY9OS",
        "type": "CAR",
        "description": "Tesla Roadster",
        "licensePlate": "ELON4PREZ",
        "color": "black",
        "timeLastModified": 1478383350431
      }
    },
    {
      "id": "sFtvhYK2l26zS0imptJJdC2q",
      "timeCreated": 1473361545000,
      "timeLastModified": 1480384608044,
      "organization": "yAM*fDkztrT3gUcz9mNDgNOL",
      "name": "Hitachino",
      "displayName": "HT",
      "phone": "+16175552820",
      "activeTask": null,
      "tasks": [],
      "onDuty": true,
      "isResponding": true,
      "timeLastSeen": 1480385496759,
      "capacity": 0,
      "userData": {
        "deviceDescription": "iPhone 6S (iOS 9.3.2)",
        "batteryLevel": 0.43,
        "appVersion": "0.9.65",
        "platform": "IOS"
      },
      "accountStatus": "ACCEPTED",
      "metadata": [],
      "imageUrl": null,
      "location": [
        -122.4431349803903,
        37.75080475959717
      ],
      "delayTime": null,
      "vehicle": {
        "id": "tN1HjcvygQWvz5FRR1JAxwL8",
        "type": "CAR",
        "description": null,
        "licensePlate": null,
        "color": null,
        "timeLastModified": 1473361545335
      }
    }
  ]
}
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
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83

Get single worker

Basic worker duty event, traveled distance (meters) and time analytics are optionally available by specifying the query parameter analytics as true.

You may also provide both from and to timestamps as query parameters (up to a maximum duration of 24 hours) to target a specific time range. If you omit these parameters, the worker analytics for the last week will be provided.

Query parameters

NameTypeDescription
filterstring arrayOptional. A comma-separated list of fields to return, if all are not desired. For example, [ name, location ].
curl -X GET "https://store.bponi.com/api/v2/workers/1LjhGUWdxFbvdsTAAXs0TFos?analytics=true" \
       -u "cd3b3de84cc1ee040bf06512d233719c:"
1
2
{
  "id": "1LjhGUWdxFbvdsTAAXs0TFos",
  "timeCreated": 1455049755000,
  "timeLastModified": 1455072352267,
  "organization": "yAM*fDkztrT3gUcz9mNDgNOL",
  "name": "Yevgeny",
  "phone": "+14155552299",
  "activeTask": null,
  "tasks": [
    "*0tnJcly~vSI~9uHz*ICHXTw",
    "PauBfRH8gQCjtMLaPe97G8Jf"
  ],
  "onDuty": true,
  "timeLastSeen": 1455156649007,
  "delayTime": null,
  "teams": [
    "9dyuPqHt6kDK5JKHFhE0xihh",
    "yKpCnWprM1Rvp3NGGlVa5TMa",
    "fwflFNVvrK~4t0m5hKFIxBUl"
  ],
  "metadata": [],
  "location": [
    -122.4016366,
    37.7764098
  ],
  "vehicle": {
    "id": "ArBoHNxS4B76AiBKoIawY9OS",
    "type": "CAR",
    "description": "Lada Niva",
    "licensePlate": "23KJ129",
    "color": "Red"
  },
  "analytics": {
    "events": [
      {
        "action": "onduty",
        "time": 1455072352164
      },
      {
        "action": "offduty",
        "time": 1455072485603
      }
    ],
    "distances": {
      "enroute": 0,
      "idle": 0
    },
    "times": {
      "enroute": 0,
      "idle": 132.18
    },
    "taskCounts": {
      "succeeded": 0,
      "failed": 0
    }
  }
}
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

The analytics query parameter being set to true will result in a more detailed response.

Update worker

Note that it is not possible to programmatically update a worker's phone. The request to update a worker's phone number will not trigger an error.

curl -X PUT "https://store.bponi.com/api/v2/workers/sFtvhYK2l26zS0imptJJdC2q" \
       -u "cd3b3de84cc1ee040bf06512d233719c:" \
       -d '{"name":"Laura P","teams":["lHCUJFvh6v0YDURKjokZbvau"]}'
1
2
3
{
  "id": "sFtvhYK2l26zS0imptJJdC2q",
  "timeCreated": 1455156653000,
  "timeLastModified": 1455156654558,
  "organization": "yAM*fDkztrT3gUcz9mNDgNOL",
  "name": "Laura P",
  "phone": "+16173428853",
  "activeTask": null,
  "tasks": [],
  "onDuty": false,
  "timeLastSeen": null,
  "delayTime": null,
  "teams": [
    "lHCUJFvh6v0YDURKjokZbvau"
  ],
  "metadata": [],
  "vehicle": {
    "id": "tN1HjcvygQWvz5FRR1JAxwL8",
    "type": "CAR",
    "description": "Tesla Model 3",
    "licensePlate": "FKNS9A",
    "color": "purple"
  }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

Delete worker

Note that workers with an active task cannot be deleted until the task has been completed.

curl -X DELETE "https://store.bponi.com/api/v2/workers/sFtvhYK2l26zS0imptJJdC2q" \
       -u "cd3b3de84cc1ee040bf06512d233719c:"
1
2
HTTP/1.1 200 OK
1

Get worker's schedule

Retrieves all of the schedule entries for a worker.

curl -X POST "https://store.bponi.com/api/v2/workers/GPOQQjU84QPN~fP*pbunT2CW/schedule" -u "cd3b3de84cc1ee040bf06512d233719c:"
1
{
  "entries":[
    {
      "date": "2017-07-20",
      "shifts": [[1500591600000,1500613200000]],
      "timezone": "America/Los_Angeles"
    },
      {
        "date": "2017-07-17",
        "shifts": [[1500307200000,1500314400000], [1500323100000,1500336000000]],
        "timezone": "America/Los_Angeles"
      }
  ]
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14

Set worker's schedule

Uses the provided list of entry objects to set the worker's schedule. Entries earlier than the start of the current week will not be saved. The structure of an entry list is as follows.

NameTypeDescription
datestringA YYYY-MM-DD formatted date.
timezonestringA valid timezone.
shiftsarrayeach element is a two element array which contains the start and end times of the shift as timestamps.

Notice that some entries were removed:

Last Updated: 11/29/2021, 10:25:26 PM