Workers.

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"}}'

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:

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:"

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

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:"

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
      }
    }
  ]
}

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:"

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

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"
      }
  ]
}

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.

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:

# Workers

# Create worker

# Body parameters

# List workers

# Query parameters

# Get workers by location

# Query parameters

# Get single worker

# Query parameters

# Update worker

# Delete worker

# Get worker's schedule

# Set worker's schedule

Workers

Create worker

Body parameters

List workers

Query parameters

Get workers by location

Query parameters

Get single worker

Query parameters

Update worker

Delete worker

Get worker's schedule

Set worker's schedule