Orders represent a delivery workflow composed of a pair of tasks: a pickup and a corresponding dropoff. Orders are associated with courier organizations and the clients they serve.
Clients can create orders and send them to the couriers. The Couriers can create orders on behalf of the clients.
To create an order pair, you would need to create both pickup and dropoff pair of tasks.
The top level body fields requires pickupTask and dropoffTask as top level fields. The order pairs of tasks will automatically be directed to the courier's Onfleet dashboard for delivery assignment. For more tasks fields information please also see Create task to get familiarized with the Task Object.
The top level fields for a create order payload:
| Name | Type | Description |
|---|---|---|
| deliveryServiceId | string | Required only if there is a Service/Rate existing for the client |
| price | number | Optional. The unit of currency assigned. |
| currency | string | Optional. Any currency unit. |
| client | string | Required when using this endpoint as a courier |
The recipient can be left blank if there is no recipient for any of the task pairs. If there is a recipient for any of the tasks, then these are the Required recipient field for each task:
| Name | Type | Description |
|---|---|---|
| name | string | Required. The recipient’s complete name. |
| phone | string | Required. A unique, valid phone number as per the organization’s country if there's no leading + sign. If a phone number has a leading + sign, it will disregard the organization's country setting. |
Destination is a required field, with address sub-field(s). You have to choose either the unparsed field, or spell out the address components, for example if you have address.number, you will need to supply the rest of the address component.
destination fields for each task:
| Name | Type | Description |
|---|---|---|
| unparsed | string | Optional. The full address in a single text field. For example: 1 Warriors Way, San Francisco, CA 94158, USA |
| number | string | Required. The number components of the address. For example: 1. |
| street | string | Required. The street name of the address component. For example: Warriors Way. |
| city | string | Required. The name of the municipality or the locale of an address. For example: San Francisco |
| state | string | Required. The name of the wider jurisdiction, state or province or similar. For example: CA or California |
| postalCode | string | Required. The postal code or a zip code of the address component, if there is one. For example: 94158. |
| country | string | Required. The country component of the address, the name of the country goes here. For example: USA |
| apartment | string | Optional, if the delivery destination has one. |
Optional Task fields for both pickupTask and dropoffTask:
| Name | Type | Description |
|---|---|---|
| notes | string | Optional. Notes for pickupTask and dropoffTask. Field length cannot exceed 10,000 characters. |
| completeBefore | number | Optional. A timestamp in unix time for the latest time the order should be completed, in milliseconds precision. This value must be the same on the Pickup and Dropoff task. |
| completeAfter | number | Optional. A timestamp in unix time for the earliest time the task should be completed, in milliseconds precision. This value must be the same on the Pickup and Dropoff task. |
| quantity | number | Optional. The number of units to be dropped off while completing this task, for the Courier’s route optimization purposes. |
Requirements field for what to collect from the recipients when the Worker delivered their payload. This is signified with a requirements object; more information can be found here. This is for drop off task only:
| Name | Type | Description |
|---|---|---|
| signature | boolean | Optional. A signature must be collected to complete this task. |
| photo | boolean | Optional. A photo must be collected to complete this task. |
| minimumAge | number | Optional. The recipient's ID must be scanned and their age verified to be greater than or equal to the minimumAge in order to complete the task. Must be in a plan that supports ID verification. |
| notes | boolean | Optional. Task completion notes must be submitted to complete this task. |
Task, Destination, and Recipient objectsIn order to make an order pair, you can just use the Skeleton JSON payload and swap out the values for your orders.
Example request and Skeleton JSON:
curl -i -X POST "https://onfleet.com/api/v2/taskOrders" \
-u '<your_api_key>:' \
-d '{"pickupTask": {"destination": {"address": {"unparsed": "honda center"}},"recipients": []},"dropoffTask": {"destination": {"address": {"unparsed": "dodgers stadium"}},"recipients": []},"courier": "nYrkNP6jZMSKgBwG9qG7ci3J"}'{
"pickupTask": {
"destination": {
"address": {
"number":"2695",
"street":"E. Katella Ave.",
"city":"Anaheim",
"state":"CA",
"postalCode":"92806",
"country":"USA",
"apartment":""
}
},
"recipients": [
{
"name": "Jane Doe",
"phone": "+1415555555"
}
],
"notes":"this is a pick up test",
"completeAfter":1710265683752,
"completeBefore":1734025683000,
"quantity":1,
},
"dropoffTask": {
"destination": {
"address": {
"number":"1000",
"street":"Vin Scully Ave.",
"city":"Los Angeles",
"state":"CA",
"postalCode":"90012",
"country":"USA",
"apartment":""
}
},
"recipients": [{
"name": "John Smith",
"phone": "+16265554147"
}
],
"notes":"this is a test",
"completeAfter":1710265683752,
"completeBefore":1734025683000,
"quantity":1,
"requirements":{
"signature":false,
"photo":false,
"notes":false,
"minimumAge":21
}
}
}{
"courier": "nYrkNP6jZMSKgBwG9qG7ci3J",
"dropoffTask":
{
"destination":
{
"address":
{
"unparsed": "dodgers stadium"
}
},
"recipients":
[]
},
"pickupTask":
{
"destination":
{
"address":
{
"unparsed": "honda center"
}
},
"recipients":
[]
}
}Example response JSON payload:
{
"id": "9DrRJvmP4jZ3Fqr~ahRun9Bf",
"shortId": "85fa4733",
"timeCreated": 1776518329000,
"timeLastModified": 1776518329371,
"source": "api",
"events": [],
"pickupTask": {
"id": "YLooevyzbtPYCZEVh1KMQI7Z",
"timeCreated": 1776518329000,
"timeLastModified": 1776518329100,
"organization": "rqbyV*TtVRyzJCeXbZyXWA7s",
"shortId": "b194591e",
"orderShortId": "85fa4733",
"trackingURL": "https://onf.lt/b194591e5f",
"worker": null,
"merchant": "rqbyV*TtVRyzJCeXbZyXWA7s",
"executor": "gz6~YVrx7HVI34ecvWOG1LfB",
"creator": "r9UlWdZWMW1PiEyW7QboYSsf",
"isActive": false,
"dependencies": [],
"completeAfter": 1776518300000,
"completeBefore": 1776546171000,
"completionDetails": {
"failureNotes": "",
"successNotes": "",
"failureReason": "NONE",
"events": [],
"actions": [],
"time": null,
"signatureUploadId": null,
"photoUploadId": null,
"photoUploadIds": null,
"firstLocation": [],
"lastLocation": [],
"unavailableAttachments": []
},
"commConfig": {
"doProxy": false
},
"pickupTask": true,
"type": 0,
"notes": "this is a pick up test",
"feedback": [],
"overrides": {},
"computed": {
"arrival": {
"location": []
},
"departure": {
"location": []
},
"firstLocation": [],
"lastLocation": []
},
"quantity": 1,
"additionalQuantities": {
"quantityA": 0,
"quantityB": 0,
"quantityC": 0
},
"serviceTime": 0,
"lastModifiedBy": "r9UlWdZWMW1PiEyW7QboYSsf",
"isFulfilled": false,
"attachments": [],
"recipientFirstViewedTime": null,
"recipientFeedbackTime": null,
"startTime": null,
"estimatedCompletionTime": null,
"identity": {
"failedScanCount": 0,
"checksum": null
},
"completionPreference": -1,
"optimizationId": null,
"appearance": {
"triangleColor": null
},
"assignmentHistory": [
{
"actionContext": {
"type": "API",
"id": "r9UlWdZWMW1PiEyW7QboYSsf"
},
"containerDescription": {
"type": "ORGANIZATION",
"organization": "gz6~YVrx7HVI34ecvWOG1LfB"
},
"time": 1776518329122
}
],
"isSelfAssigned": false,
"isSelfAssignable": false,
"requirements": {
"signature": false,
"notes": false,
"photo": false,
"minimumAge": 0
},
"container": {
"type": "ORGANIZATION",
"organization": "gz6~YVrx7HVI34ecvWOG1LfB"
},
"customFields": [],
"customRequirements": [],
"state": 0,
"weight": {
"value": 5,
"units": "kg"
},
"bulkTasks": [],
"metadata": [],
"delayTime": null,
"estimatedArrivalTime": null,
"destination": {
"id": "p8*ad4L4Z8TrURTIpoUbdush",
"timeCreated": 1776518329000,
"timeLastModified": 1776518329035,
"location": [
-123.140469,
49.2634254
],
"address": {
"number": "1580",
"street": "West Broadway",
"apartment": "",
"city": "Vancouver",
"state": "British Columbia",
"postalCode": "V6J 5K8",
"country": "Canada"
},
"notes": "",
"organization": "rqbyV*TtVRyzJCeXbZyXWA7s",
"wasGeocoded": true,
"createdByLocation": false,
"googlePlaceId": null,
"useGPS": false
},
"recipients": [
{
"id": "GPSpxVguKBY6aekgWYo5ZliG",
"timeCreated": 1776518329000,
"timeLastModified": 1776518329047,
"name": "Jane Doe",
"phone": "+14155555555",
"organization": "rqbyV*TtVRyzJCeXbZyXWA7s",
"skipSMSNotifications": false,
"metadata": []
}
]
},
"dropoffTask": {
"id": "L8VymDzdGx**EULcRUEc99Ro",
"timeCreated": 1776518329000,
"timeLastModified": 1776518329332,
"organization": "rqbyV*TtVRyzJCeXbZyXWA7s",
"shortId": "a2ccfa3a",
"orderShortId": "85fa4733",
"trackingURL": "https://onf.lt/a2ccfa3ab5",
"worker": null,
"merchant": "rqbyV*TtVRyzJCeXbZyXWA7s",
"executor": "gz6~YVrx7HVI34ecvWOG1LfB",
"creator": "r9UlWdZWMW1PiEyW7QboYSsf",
"isActive": false,
"dependencies": [
"YLooevyzbtPYCZEVh1KMQI7Z"
],
"completeAfter": 1776518300000,
"completeBefore": 1776546171000,
"completionDetails": {
"failureNotes": "",
"successNotes": "",
"failureReason": "NONE",
"events": [],
"actions": [],
"time": null,
"signatureUploadId": null,
"photoUploadId": null,
"photoUploadIds": null,
"firstLocation": [],
"lastLocation": [],
"unavailableAttachments": []
},
"commConfig": {
"doProxy": false
},
"pickupTask": false,
"type": 1,
"notes": "this is a test",
"feedback": [],
"overrides": {},
"computed": {
"arrival": {
"location": []
},
"departure": {
"location": []
},
"firstLocation": [],
"lastLocation": []
},
"quantity": 1,
"additionalQuantities": {
"quantityA": 0,
"quantityB": 0,
"quantityC": 0
},
"serviceTime": 0,
"lastModifiedBy": "r9UlWdZWMW1PiEyW7QboYSsf",
"isFulfilled": false,
"attachments": [],
"recipientFirstViewedTime": null,
"recipientFeedbackTime": null,
"startTime": null,
"estimatedCompletionTime": null,
"identity": {
"failedScanCount": 0,
"checksum": null
},
"completionPreference": -1,
"optimizationId": null,
"appearance": {
"triangleColor": null
},
"assignmentHistory": [
{
"actionContext": {
"type": "API",
"id": "r9UlWdZWMW1PiEyW7QboYSsf"
},
"containerDescription": {
"type": "ORGANIZATION",
"organization": "gz6~YVrx7HVI34ecvWOG1LfB"
},
"time": 1776518329350
}
],
"isSelfAssigned": false,
"isSelfAssignable": false,
"requirements": {
"signature": false,
"notes": false,
"photo": false,
"minimumAge": 21
},
"container": {
"type": "ORGANIZATION",
"organization": "gz6~YVrx7HVI34ecvWOG1LfB"
},
"customFields": [],
"customRequirements": [],
"state": 0,
"weight": {
"value": 5,
"units": "kg"
},
"bulkTasks": [],
"metadata": [],
"delayTime": null,
"estimatedArrivalTime": null,
"destination": {
"id": "BYQjGg40*xz6xYB94ukcoFKT",
"timeCreated": 1776518329000,
"timeLastModified": 1776518329275,
"location": [
-122.7895271,
49.2843224
],
"address": {
"name": "1507",
"number": "3070",
"street": "Guildford Way",
"apartment": "",
"city": "Coquitlam",
"state": "British Columbia",
"postalCode": "V3B 7R8",
"country": "Canada"
},
"notes": "",
"organization": "rqbyV*TtVRyzJCeXbZyXWA7s",
"wasGeocoded": true,
"createdByLocation": false,
"googlePlaceId": null,
"useGPS": false
},
"recipients": [
{
"id": "yCjx6UQae0S8~O2IlX7zEExH",
"timeCreated": 1776518329000,
"timeLastModified": 1776518329287,
"name": "John Smith",
"phone": "+16265554147",
"organization": "rqbyV*TtVRyzJCeXbZyXWA7s",
"skipSMSNotifications": false,
"metadata": []
}
]
},
"organization": "rqbyV*TtVRyzJCeXbZyXWA7s",
"deliveryService": null,
"orchestrationDetails": null,
"priceBreakdown": [],
"deliveryServiceInvoice": null,
"status": "unassigned"
}
PairingThe Order creation is a One-to-One relation, as in one pickup task and one dropoff task. It will not be used for One-to-Many. If multiple dropoff task objects are provided, the last one in the payload will be considered.