Create worker

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).

address.routing

object

Optional. This value is used to set the worker's address.

📘

Worker Image

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

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.

curl -X POST "https://onfleet.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"}}'
onfleet.workers.create(body={"name":"A Swartz","phone":"617-342-8853","teams":["nz1nG1Hpx9EHjQCJsT2VAs~o"],"vehicle":{"type":"CAR","description":"Tesla Model 3","licensePlate":"FKNS9A","color":"purple"}})
onfleet.workers.create({"name":"A Swartz","phone":"617-342-8853","teams":["nz1nG1Hpx9EHjQCJsT2VAs~o"],"vehicle":{"type":"CAR","description":"Tesla Model 3","licensePlate":"FKNS9A","color":"purple"}});
$onfleet->workers->create(["name"=>"A Swartz","phone"=>"617-342-8853","teams"=>["nz1nG1Hpx9EHjQCJsT2VAs~o"],"vehicle"=>["type"=>"CAR","description"=>"Tesla Model 3","licensePlate"=>"FKNS9A","color"=>"purple"]])
{
  "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
  }
}
{
  "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"
  }
}
{
  "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"
  }
}
{
  "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"
  }
}

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.

An address.routing object has the following properties:

Name

Type

Description

address.routing

string

The destination object id created using the Create destination endpoint.

object

This object requires both coordinate array and address object from Create Destination endpoint.

Example of address.routing object when creating an worker

{
    "name": "API User",
    "phone": "+17145559977",
    "teams": [
        "kq5MFBzYNWhp1rumJEfGUTqS"
    ],
    "addresses": {
        "routing": "VBY1jRCp*GFWWjz*aN8HPNvj"
    }
}
{
    "name": "API User",
    "phone": "+17145559977",
    "teams": [
        "kq5MFBzYNWhp1rumJEfGUTqS"
    ],
    "addresses": {
        "routing": {
            "location": [
                -117.8764687,
                33.8078476
            ],
            "address": {
                "apartment": "APT# 12345",
                "state": "California",
                "postalCode": "92806",
                "number": "2695",
                "street": "East Katella Avenue",
                "city": "Anaheim",
                "country": "United States"
            }
        }
    }
}