# Create task

## Create task

You can pass the IDs of existing [Recipients](https://docs.onfleet.com/reference/recipients) or [Destinations](https://docs.onfleet.com/reference/destinations) in the request body. Alternatively, you may include recipient or destination objects directly in the request body to automatically create them during task creation.

### Body parameters

<Table align={["left","left","left"]}>
  <thead>
    <tr>
      <th>
        Name
      </th>

      <th>
        Type
      </th>

      <th>
        Description
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        merchant
      </td>

      <td>
        string
      </td>

      <td>
        Optional. The ID of the organization displayed to the task recipient. If not provided, this defaults to the organization creating the task. If you are performing deliveries on behalf of a connected organization and want the recipient to see that organization’s name, logo, and branded notifications, include the connected organization’s ID in the request.
      </td>
    </tr>

    <tr>
      <td>
        executor
      </td>

      <td>
        string
      </td>

      <td>
        Optional. 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.
      </td>
    </tr>

    <tr>
      <td>
        destination
      </td>

      <td>
        string or object
      </td>

      <td>
        The ID of the task's destination or a valid [Destination](https://docs.onfleet.com/reference/destinations) object.
      </td>
    </tr>

    <tr>
      <td>
        recipients
      </td>

      <td>
        string array
        or object array
      </td>

      <td>
        An array containing zero or one ID of the task's recipients or a valid array of zero or one [Recipient](https://docs.onfleet.com/reference/recipients) objects.
      </td>
    </tr>

    <tr>
      <td>
        completeAfter
      </td>

      <td>
        number
      </td>

      <td>
        Optional. A timestamp in unix time for the earliest time the task should be completed, in milliseconds precision.
      </td>
    </tr>

    <tr>
      <td>
        completeBefore
      </td>

      <td>
        number
      </td>

      <td>
        Optional. A timestamp in unix time for the latest time the task should be completed, in milliseconds precision.
      </td>
    </tr>

    <tr>
      <td>
        pickupTask
      </td>

      <td>
        boolean
      </td>

      <td>
        Optional. Whether the task is a pickup task.
      </td>
    </tr>

    <tr>
      <td>
        dependencies
      </td>

      <td>
        string array
      </td>

      <td>
        Optional. One or more IDs of tasks which must be completed prior to this task. Please see [Dependencies](https://docs.onfleet.com/reference/dependencies) section for more information.
      </td>
    </tr>

    <tr>
      <td>
        notes
      </td>

      <td>
        string
      </td>

      <td>
        Optional. Notes for the task. Field length cannot exceed 10,000 characters.
      </td>
    </tr>

    <tr>
      <td>
        autoAssign
      </td>

      <td>
        object
      </td>

      <td>
        Optional. Automatic assignment options to on-duty (state=1,2) drivers. You may not provide a `container` if using automatic assignment.
      </td>
    </tr>

    <tr>
      <td>
        container
      </td>

      <td>
        object
      </td>

      <td>
        Optional. The container to which the task will be appended. If not specified, the task is added to the creating organization’s default container.
      </td>
    </tr>

    <tr>
      <td>
        quantity
      </td>

      <td>
        number
      </td>

      <td>
        Optional. The number of units to be dropped off while completing this task, for route optimization purposes.
      </td>
    </tr>

    <tr>
      <td>
        serviceTime
      </td>

      <td>
        number
      </td>

      <td>
        Optional. The number of minutes to be spent by the worker on arrival at this task's destination, for route optimization purposes.
      </td>
    </tr>

    <tr>
      <td>
        recipientName
      </td>

      <td>
        string
      </td>

      <td>
        Optional override parameter. Override the recipient name for this task only.
      </td>
    </tr>

    <tr>
      <td>
        recipientNotes
      </td>

      <td>
        string
      </td>

      <td>
        Optional override parameter. Override the recipient notes for this task only.
      </td>
    </tr>

    <tr>
      <td>
        recipientSkipSMSNotifications
      </td>

      <td>
        boolean
      </td>

      <td>
        Optional override parameter. Override the recipient notification settings for this task only.
      </td>
    </tr>

    <tr>
      <td>
        useMerchantForProxy
      </td>

      <td>
        boolean
      </td>

      <td>
        Optional override parameter. Override the organization ID to use the merchant orgID when set to true for this task only.
      </td>
    </tr>

    <tr>
      <td>
        requirements
      </td>

      <td>
        object
      </td>

      <td>
        Optional. Set signature, photo, and/or notes completion requirement(s) for this task only. Please see [Completion Requirements](https://docs.onfleet.com/reference/completion-requirements) for more information.
      </td>
    </tr>

    <tr>
      <td>
        scanOnlyRequiredBarcodes
      </td>

      <td>
        boolean
      </td>

      <td>
        Optional. Set restrictions to block the scanning of non-required barcodes.
      </td>
    </tr>

    <tr>
      <td>
        barcode
      </td>

      <td>
        array of objects
      </td>

      <td>
        Optional. This is an [Scale](https://onfleet.com/pricing) feature for including setting up barcodes requirements for a task. For more information on how this object works, please see [Barcode Scanning](https://docs.onfleet.com/reference/barcode-scanning)
      </td>
    </tr>

    <tr>
      <td>
        appearance
      </td>

      <td>
        object
      </td>

      <td>
        Optional. Set triangle colored pins on the map.
      </td>
    </tr>

    <tr>
      <td>
        customFields
      </td>

      <td>
        array of objects
      </td>

      <td>
        Optional. See [Task Custom Fields](https://docs.onfleet.com/reference/task-custom-fields)
      </td>
    </tr>

    <tr>
      <td>
        additionalQuantities
      </td>

      <td>
        Object
      </td>

      <td>
        Optional. See [Additional Quanities](https://docs.onfleet.com/reference/additional-quanities)
      </td>
    </tr>
  </tbody>
</Table>

> 🚧 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](https://docs.onfleet.com/reference/data-types-and-response-formats) or free conversion tool online [here](https://unixtime.org/).

```shell Request
curl -X POST "https://onfleet.com/api/v2/tasks" \
       -u "<your_onfleet_api_key>:" \
       -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"}}'
```

```python
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"}
})
```

```javascript
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"}
});
```

```php
$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"]]);
```

```json Response
{
  "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
}
```