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
Name | Type | Description |
---|---|---|
name | string | The worker’s complete name. |
phone | string | A valid phone number as per the worker’s organization’s country. |
teams | string array | One or more team IDs of which the worker is a member. |
vehicle | object | Optional. The worker’s vehicle; providing no vehicle details is equivalent to the worker being on foot. |
capacity | number | Optional. The maximum number of units this worker can carry, for route optimization purposes. |
displayName | string | Optional. 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"}}'
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
}
}
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"
}
}
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"
}
}
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"
}
}
2
3
4
5
6
7
8
9
10
11
12
13
A vehicle
has the following properties:
Name | Type | Description |
---|---|---|
type | string | The vehicle’s type, must be one of CAR, MOTORCYCLE, BICYCLE or TRUCK. |
description | string | Optional. The vehicle’s make, model, year, or any other relevant identifying details. |
licensePlate | string | Optional. The vehicle’s license plate number. |
color | string | Optional. 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
Name | Type | Description |
---|---|---|
filter | string | Optional. A comma-separated list of fields to return, if all are not desired. For example, name, location. |
teams | string | Optional. A comma-separated list of the team IDs that workers must be part of. |
states | string | Optional. 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). |
phones | string | Optional. A comma-separated list of workers' phone numbers. |
curl -X GET "https://store.bponi.com/api/v2/workers?states=1" \
-u "cd3b3de84cc1ee040bf06512d233719c:"
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
}
}
]
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
Name | Type | Description |
---|---|---|
longitude | number | The longitude component of the coordinate pair. |
latitude | number | The latitude component of the coordinate pair. |
radius | number | Optional. 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:"
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
}
}
]
}
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
Name | Type | Description |
---|---|---|
filter | string array | Optional. 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:"
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
}
}
}
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"]}'
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"
}
}
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:"
2
HTTP/1.1 200 OK
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:"
{
"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"
}
]
}
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.
Name | Type | Description |
---|---|---|
date | string | A YYYY-MM-DD formatted date. |
timezone | string | A valid timezone. |
shifts | array | each element is a two element array which contains the start and end times of the shift as timestamps. |
Notice that some entries were removed: