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

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).
address.routingobjectOptional. 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:

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.
curl -X POST "https://onfleet.com/api/v2/workers" \
       -u "cd3b3de84cc1ee040bf06512d233719c:" \
       -d '{"name":"A Swartz","phone":"619-555-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:

NameTypeDescription
address.routingstringThe destination object id created using the Create destination endpoint.
objectThis 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"
            }
        }
    }
}