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[]	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.
additionalCapacities	object	Optional. This option is only available for customer with this feature enabled.

📘
Worker Image
Note that a worker's image can only be set through the dashboard or by the worker using the mobile app.

vehicle Object 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.

Example Requests

curl -X POST "https://onfleet.com/api/v2/workers" \
     -u "<your_api_key>:" \
     -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.

additionalCapacities Object Properties

Name	Type	Descriptions
capacityA	number	Arbitrary Capacity unit for type A
capacityB	number	Arbitrary Capacity unit for type B
capacityC	number	Arbitrary Capacity unit for type C

"additionalCapacities": {
   "capacityA": 10,
   "capacityB": 50,
   "capacityC": 99999
}

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