Create tasks in batch

Create tasks in batch

You may create multiple tasks in a single request by using this batch endpoint

This is particularly helpful if you want to create unassigned tasks quickly for future assignment or optimization, without having to worry about orchestrating requests to avoid excessive contention around the organization container lock.

Automatic assignment is not currently supported by this endpoint. You will also not receive taskCreated webhook requests for batch task creations if you have registered for this trigger.

Processing will take place for all the tasks provided and you will receive a response with tasks containing the full details of the successfully created tasks and errors with any issues that may have been found. These errors contain both the error as well as the body provided for the problematic task so your integration can more easily react to the problem. Make sure that you increase your timeout value for this request as it could take considerably longer than others.

Note that the structure of the errors you may get from this endpoint is slightly different from the errors we send back when a request responds with a non-200 code. Batch errors include the following top-level properties: statusCode (number), error (number), message (string) and cause (string).

Body parameters

Name

Type

Description

tasks

object array

An array containing one or more task objects. Refer to the Create task endpoint section for a complete definition of the task object.

🚧

Internal Timeout

Onfleet has an internal system timeout of 70 seconds, in which Batch creation may encounter when uploading more than 25* tasks at a time. When this happens, the tasks are still being processed and will be created, but will not be able to respond to the HTTP request with relevant data. If this error is encountered, try to lower the number of tasks in the batch.

curl -X POST "https://onfleet.com/api/v2/tasks/batch" \
       -u "cd3b3de84cc1ee040bf06512d233719c:" \
       -d '{"tasks":[{"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."}],"notes":"Order 332: 24oz Stumptown Finca El Puente, 10 x Aji de Gallina Empanadas, 13-inch Lelenitas Tres Leches"},{"destination":{"address":{"number":"1264","street":"W. Augusta Blvd. ","apartment":"","city":"Chicago","state":"IL","country":"USA"}},"notes":"12 x 2016 Getariako Txakolina (Rosé)","pickupTask":true,"metadata":[{"name":"caseId","type":"number","value":33162}],"recipients":[]},{"destination":{"address":{"number":"420","street":"Infinite Loop","city":"Redmond","state":"WA","country":"USA"}},"recipients":[{"name":"S.N.","phone":"206-341-8826"}]}]}'
onfleet.tasks.batchCreate(body={"tasks":[{"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."}],"notes":"Order 332: 24oz Stumptown Finca El Puente, 10 x Aji de Gallina Empanadas, 13-inch Lelenitas Tres Leches"},{"destination":{"address":{"number":"1264","street":"W. Augusta Blvd. ","apartment":"","city":"Chicago","state":"IL","country":"USA"}},"notes":"12 x 2016 Getariako Txakolina (Rosé)","pickupTask":true,"metadata":[{"name":"caseId","type":"number","value":33162}],"recipients":[]},{"destination":{"address":{"number":"420","street":"Infinite Loop","city":"Redmond","state":"WA","country":"USA"}},"recipients":[{"name":"S.N.","phone":"206-341-8826"}]}]})
onfleet.tasks.batchCreate({"tasks":[{"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."}],"notes":"Order 332: 24oz Stumptown Finca El Puente, 10 x Aji de Gallina Empanadas, 13-inch Lelenitas Tres Leches"},{"destination":{"address":{"number":"1264","street":"W. Augusta Blvd. ","apartment":"","city":"Chicago","state":"IL","country":"USA"}},"notes":"12 x 2016 Getariako Txakolina (Rosé)","pickupTask":true,"metadata":[{"name":"caseId","type":"number","value":33162}],"recipients":[]},{"destination":{"address":{"number":"420","street":"Infinite Loop","city":"Redmond","state":"WA","country":"USA"}},"recipients":[{"name":"S.N.","phone":"206-341-8826"}]}]});
$onfleet->tasks->batchCreate(["tasks" =>  [["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."]],"notes" =>  "Order 332 =>   24oz Stumptown Finca El Puente, 10 x Aji de Gallina Empanadas, 13-inch Lelenitas Tres Leches"],["destination" =>  ["address" =>  ["number" =>  "1264","street" =>  "W. Augusta Blvd. ","apartment" =>  "","city" =>  "Chicago","state" =>  "IL","country" =>  "USA"]],"notes" =>  "12 x 2016 Getariako Txakolina (Rosé)","pickupTask" =>  true,"metadata" =>  [["name" =>  "caseId","type" =>  "number","value" =>  33162]],"recipients" =>  []],["destination" =>  ["address" =>  ["number" =>  "420","street" =>  "Infinite Loop","city" =>  "Redmond","state" =>  "WA","country" =>  "USA"]],"recipients" =>  [["name" =>  "S.N.","phone" =>  "206-341-8826"]]]]]);
{
  "tasks": [
    {
      "id": "C2AN77VYi1mqHwbKRBNCuEPZ",
      "timeCreated": 1507072619000,
      "timeLastModified": 1507072619880,
      "organization": "yAM*fDkztrT3gUcz9mNDgNOL",
      "shortId": "0dadas4c",
      "trackingURL": "https://onf.lt/0dadas4c",
      "worker": null,
      "merchant": "yAM*fDkztrT3gUcz9mNDgNOL",
      "executor": "yAM*fDkztrT3gUcz9mNDgNOL",
      "creator": "EJmsbJgHiRLPjNVE7GEIPs7*",
      "dependencies": [],
      "state": 0,
      "completeAfter": null,
      "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": [],
        "failureReason": "NONE",
        "time": null,
        "firstLocation": [],
        "lastLocation": []
      },
      "feedback": [],
      "metadata": [],
      "overrides": {
        "recipientSkipSMSNotifications": null,
        "recipientNotes": null,
        "recipientName": null
      },
      "quantity": 0,
      "serviceTime": 0,
      "container": {
        "type": "ORGANIZATION",
        "organization": "yAM*fDkztrT3gUcz9mNDgNOL"
      },
      "recipients": [
        {
          "id": "G7rcM2nqblmh8vj2do1FpaOQ",
          "organization": "yAM*fDkztrT3gUcz9mNDgNOL",
          "timeCreated": 1491957797000,
          "timeLastModified": 1507072619873,
          "name": "Blas Silkovich",
          "phone": "+16505554481",
          "notes": "Knows Neiman, VIP status.",
          "skipSMSNotifications": false,
          "metadata": []
        }
      ],
      "destination": {
        "id": "h9nzV88L1gVkxxQywHqGUXOi",
        "timeCreated": 1507072619000,
        "timeLastModified": 1507072619857,
        "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": []
      }
    },
    {
      "id": "9l2s~L~jNB32TZmb*XRHCDJe",
      "timeCreated": 1507072620000,
      "timeLastModified": 1507072620557,
      "organization": "yAM*fDkztrT3gUcz9mNDgNOL",
      "shortId": "cafaqf73",
      "trackingURL": "https://onf.lt/cafaqf73",
      "worker": null,
      "merchant": "yAM*fDkztrT3gUcz9mNDgNOL",
      "executor": "yAM*fDkztrT3gUcz9mNDgNOL",
      "creator": "EJmsbJgHiRLPjNVE7GEIPs7*",
      "dependencies": [],
      "state": 0,
      "completeAfter": null,
      "completeBefore": null,
      "pickupTask": true,
      "notes": "12 x 2016 Getariako Txakolina (Rosé)",
      "completionDetails": {
        "events": [],
        "failureReason": "NONE",
        "time": null,
        "firstLocation": [],
        "lastLocation": []
      },
      "feedback": [],
      "metadata": [
        {
          "name": "caseId",
          "type": "number",
          "value": 33162,
          "visibility": [
            "api"
          ]
        }
      ],
      "overrides": {
        "recipientSkipSMSNotifications": null,
        "recipientNotes": null,
        "recipientName": null
      },
      "quantity": 0,
      "serviceTime": 0,
      "container": {
        "type": "ORGANIZATION",
        "organization": "yAM*fDkztrT3gUcz9mNDgNOL"
      },
      "recipients": [],
      "destination": {
        "id": "nzr69litF0Lw~rZjAdw8hx2s",
        "timeCreated": 1507072620000,
        "timeLastModified": 1507072620548,
        "location": [
          -87.66117659999999,
          41.8999945
        ],
        "address": {
          "apartment": "",
          "state": "Illinois",
          "postalCode": "60642",
          "country": "United States",
          "city": "Chicago",
          "street": "West Augusta Boulevard",
          "number": "1264"
        },
        "notes": "",
        "metadata": []
      }
    }
  ],
  "errors": [
    {
      "error": {
        "statusCode": 400,
        "error": 1000,
        "message": "The values of one or more parameters are invalid.",
        "cause": "Geocoding errors found. "
      },
      "task": {
        "destination": {
          "address": {
            "number": "420",
            "street": "Infinite Loop",
            "city": "Redmond",
            "state": "WA",
            "country": "USA"
          }
        },
        "recipients": [
          {
            "name": "S.N.",
            "phone": "206-341-8826"
          }
        ]
      }
    }
  ]
}