⇠ Back to Dev HubSupport Center ›API Status ›Engineering Blog ›

Create task

Create task

Note that you can provide the IDs of an existing Recipients or Destinations or simply include their details as objects in the API request to have these created automatically.

Body parameters

NameTypeDescription
merchantstringOptional. The ID of the organization that will be displayed to the recipient of the task. Defaults to the creating organization. If you perform deliveries on behalf of a connected organization and want to display their name, logo, and branded notifications, provide their organization ID.
executorstringOptional. The ID of the organization that will be responsible for fulfilling the task. Defaults to the creating organization. If you delegate your deliveries to a third party, provide their organization ID.
destinationstring or objectThe ID of the task's destination or a valid Destination object.
recipientsstring array
or object array		An array containing zero or one IDs of the task's recipients or a valid array of zero or one Recipient objects.
completeAfternumberOptional. A timestamp in unix time for the earliest time the task should be completed, in milliseconds precision.
completeBeforenumberOptional. A timestamp in unix time for the latest time the task should be completed, in milliseconds precision.
pickupTaskbooleanOptional. Whether the task is a pickup task.
dependenciesstring arrayOptional. One or more IDs of tasks which must be completed prior to this task.
notesstringOptional. Notes for the task. Field length cannot exceed 10,000 characters.
autoAssignobjectOptional. Automatic assignment options to on-duty (state=1,2) drivers. You may not provide a container if using automatic assignment.
containerobjectOptional. The container to which to append this task. Defaults to the creator organization container.
quantitynumberOptional. The number of units to be dropped off while completing this task, for route optimization purposes.
serviceTimenumberOptional. The number of minutes to be spent by the worker on arrival at this task's destination, for route optimization purposes.
recipientNamestringOptional override parameter. Override the recipient name for this task only.
recipientNotesstringOptional override parameter. Override the recipient notes for this task only.
recipientSkipSMSNotificationsbooleanOptional override parameter. Override the recipient notification settings for this task only.
useMerchantForProxybooleanOptional override parameter. Override the organization ID to use the merchant orgID when set to true for this task only.
requirementsobjectOptional. Set signature, photo, and/or notes completion requirement(s) for this task only. Please see Completion Requirements for more information.
scanOnlyRequiredBarcodesbooleanOptional. Set restrictions to block the scanning of non-required barcodes.
appearanceobjectOptional. Set triangle colored pins on the map.

🚧

Override Feature

Despite the task object response contains a JSON blob named override, you should be passing the override parameters as a normal body parameter when creating a task.

❗️

Override Exception

The general override parameter works on the specific task when the parameter is successfully stored, the only exception being recipientSkipSMSNotifications. The condition for recipientSkipSMSNotifications override to work is when the recipient's skipSMSNotification flag is set to false.

In summary, if a recipient opted-out to receive SMS notification, task-level override for SMS notifications would not be applied.

👍

Customizing Map Pins

The appearance object is now supported and is configurable through a triangleColor parameter. 

"appearance": {"triangleColor": 1}

The triangleColor parameter accepts 3 values: 0 for teal, 1 for orange, and 2 for magenta.

📘

Unix

Onfleet API only accepts time formatted in Unix to the millisecond precision. Any other formats are not accepted and may produce unexpected results. For more information please see Data Types and Response Formats or free conversion tool online here.

curl -X POST "https://onfleet.com/api/v2/tasks" \
       -u "cd3b3de84cc1ee040bf06512d233719c:" \
       -d '{"destination":{"address":{"unparsed":"2829 Vallejo St, SF, CA, USA"},"notes":"Small green door by garage door has pin pad, enter *4821*"},"recipients":[{"name":"Blas Silkovich","phone":"650-555-4481","notes":"Knows Neiman, VIP status."}],"completeAfter":1455151071727,"notes":"Order 332: 24oz Stumptown Finca El Puente, 10 x Aji de Gallina Empanadas, 13-inch Lelenitas Tres Leches","autoAssign":{"mode":"distance"}}'

onfleet.tasks.create(body={"destination":{"address":{"unparsed":"2829 Vallejo St, SF, CA, USA"},"notes":"Small green door by garage door has pin pad, enter *4821*"},"recipients":[{"name":"Blas Silkovich","phone":"650-555-4481","notes":"Knows Neiman, VIP status."}],"completeAfter":1455151071727,"notes":"Order 332: 24oz Stumptown Finca El Puente, 10 x Aji de Gallina Empanadas, 13-inch Lelenitas Tres Leches","autoAssign":{"mode":"distance"}})

onfleet.tasks.create({"destination":{"address":{"unparsed":"2829 Vallejo St, SF, CA, USA"},"notes":"Small green door by garage door has pin pad, enter *4821*"},"recipients":[{"name":"Blas Silkovich","phone":"650-555-4481","notes":"Knows Neiman, VIP status."}],"completeAfter":1455151071727,"notes":"Order 332: 24oz Stumptown Finca El Puente, 10 x Aji de Gallina Empanadas, 13-inch Lelenitas Tres Leches","autoAssign":{"mode":"distance"}});

$onfleet->tasks->create([ "destination" =>  [ "address" =>  [ "unparsed" =>  "2829 Vallejo St, SF, CA, USA"] ,"notes" =>  "Small green door by garage door has pin pad, enter *4821*"] ,"recipients" =>  [[ "name" =>  "Blas Silkovich","phone" =>  "650-555-4481","notes" =>  "Knows Neiman, VIP status."] ],"completeAfter" =>  1455151071727,"notes" =>  "Order 332 =>   24oz Stumptown Finca El Puente, 10 x Aji de Gallina Empanadas, 13-inch Lelenitas Tres Leches","autoAssign" =>  [ "mode" =>  "distance"] ] );

{
  "id": "kc8SS1tzuZ~jqjlebKGrUmpe",
  "timeCreated": 1455156667000,
  "timeLastModified": 1455156667234,
  "organization": "yAM*fDkztrT3gUcz9mNDgNOL",
  "shortId": "8f983639",
  "trackingURL": "https://onf.lt/8f98363993",
  "worker": "1LjhGUWdxFbvdsTAAXs0TFos",
  "merchant": "yAM*fDkztrT3gUcz9mNDgNOL",
  "executor": "yAM*fDkztrT3gUcz9mNDgNOL",
  "creator": "EJmsbJgHiRLPjNVE7GEIPs7*",
  "dependencies": [],
  "state": 0,
  "completeAfter": 1455151071727,
  "completeBefore": null,
  "pickupTask": false,
  "notes": "Order 332: 24oz Stumptown Finca El Puente, 10 x Aji de Gallina Empanadas, 13-inch Lelenitas Tres Leches",
  "completionDetails": {
    "events": [],
    "time": null
  },
  "feedback": [],
  "metadata": [],
  "overrides": {
    "recipientSkipSMSNotifications": null,
    "recipientNotes": null,
    "recipientName": null
  },
  "container": {
    "type": "WORKER",
    "worker": "1LjhGUWdxFbvdsTAAXs0TFos"
  },
  "recipients": [
    {
      "id": "G7rcM2nqblmh8vj2do1FpaOQ",
      "organization": "yAM*fDkztrT3gUcz9mNDgNOL",
      "timeCreated": 1455156667000,
      "timeLastModified": 1455156667229,
      "name": "Blas Silkovich",
      "phone": "+16505554481",
      "notes": "Knows Neiman, VIP status.",
      "skipSMSNotifications": false,
      "metadata": []
    }
  ],
  "destination": {
    "id": "zrVXZi5aDzOZlAghZaLfGAfA",
    "timeCreated": 1455156667000,
    "timeLastModified": 1455156667220,
    "location": [
      -122.4438337,
      37.7940329
    ],
    "address": {
      "apartment": "",
      "state": "California",
      "postalCode": "94123",
      "country": "United States",
      "city": "San Francisco",
      "street": "Vallejo Street",
      "number": "2829"
    },
    "notes": "Small green door by garage door has pin pad, enter *4821*",
    "metadata": []
  },
  "didAutoAssign": true
}