openapi: 3.0.3
info:
title: Onfleet Tasks API
description: |
The Onfleet Tasks API manages delivery and pickup tasks across the Onfleet
last-mile delivery platform. Tasks are the atomic unit of work — each
represents a single pickup or dropoff with a destination, recipient,
completion window, and optional dependencies.
version: '2.7'
contact:
name: Onfleet Support
email: [email protected]
url: https://onfleet.com/support
license:
name: Onfleet Terms of Service
url: https://onfleet.com/legal
servers:
- url: https://onfleet.com/api/v2
description: Production
security:
- basicAuth: []
tags:
- name: Tasks
paths:
/tasks:
post:
tags: [Tasks]
summary: Create Task
description: Create a new pickup or dropoff task with a destination, recipient, and completion window.
operationId: createTask
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/TaskCreate'
responses:
'200':
description: Task created
content:
application/json:
schema:
$ref: '#/components/schemas/Task'
/tasks/batch:
post:
tags: [Tasks]
summary: Create Tasks In Batch
description: Asynchronously create up to 100 tasks per request; results are returned via the taskBatchCreateJobCompleted webhook.
operationId: createTaskBatch
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
tasks:
type: array
items:
$ref: '#/components/schemas/TaskCreate'
responses:
'200':
description: Batch accepted
content:
application/json:
schema:
type: object
properties:
status:
type: string
jobId:
type: string
/tasks/all:
get:
tags: [Tasks]
summary: List Tasks
description: Return a paginated collection of tasks; uses lastId-based pagination with up to 64 tasks per page.
operationId: listTasks
parameters:
- name: from
in: query
required: true
schema: {type: integer, format: int64}
description: Start of the search range in Unix milliseconds.
- name: to
in: query
schema: {type: integer, format: int64}
description: End of the search range in Unix milliseconds.
- name: lastId
in: query
schema: {type: string}
description: Cursor returned from a previous call to walk pagination.
- name: state
in: query
schema: {type: string}
description: Comma-separated list of task state values (0=Unassigned, 1=Assigned, 2=Active, 3=Completed).
- name: worker
in: query
schema: {type: string}
- name: completeBeforeBefore
in: query
schema: {type: integer, format: int64}
- name: completeAfterAfter
in: query
schema: {type: integer, format: int64}
- name: dependencies
in: query
schema: {type: string}
- name: containers
in: query
schema: {type: string}
responses:
'200':
description: Paginated tasks
content:
application/json:
schema:
$ref: '#/components/schemas/TaskList'
/tasks/{taskId}:
parameters:
- name: taskId
in: path
required: true
schema: {type: string}
get:
tags: [Tasks]
summary: Get Single Task
operationId: getTask
responses:
'200':
description: Task
content:
application/json:
schema: {$ref: '#/components/schemas/Task'}
put:
tags: [Tasks]
summary: Update Task
operationId: updateTask
requestBody:
required: true
content:
application/json:
schema: {$ref: '#/components/schemas/TaskUpdate'}
responses:
'200':
description: Updated task
content:
application/json:
schema: {$ref: '#/components/schemas/Task'}
delete:
tags: [Tasks]
summary: Delete Task
operationId: deleteTask
responses:
'200':
description: Task deleted
/tasks/shortId/{shortId}:
parameters:
- name: shortId
in: path
required: true
schema: {type: string}
get:
tags: [Tasks]
summary: Get Task By Short ID
operationId: getTaskByShortId
responses:
'200':
description: Task
content:
application/json:
schema: {$ref: '#/components/schemas/Task'}
/tasks/{taskId}/clone:
post:
tags: [Tasks]
summary: Clone Task
operationId: cloneTask
parameters:
- name: taskId
in: path
required: true
schema: {type: string}
responses:
'200':
description: Cloned task
content:
application/json:
schema: {$ref: '#/components/schemas/Task'}
/tasks/{taskId}/complete:
post:
tags: [Tasks]
summary: Force-Complete Task
operationId: forceCompleteTask
parameters:
- name: taskId
in: path
required: true
schema: {type: string}
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
completionDetails:
type: object
properties:
success: {type: boolean}
notes: {type: string}
responses:
'200':
description: Task completed
/containers/workers/{workerId}:
put:
tags: [Tasks]
summary: Assign Tasks To Worker
description: Set the ordered list of task IDs assigned to a worker (replaces existing assignments unless type=APPEND).
operationId: assignTasksToWorker
parameters:
- name: workerId
in: path
required: true
schema: {type: string}
requestBody:
required: true
content:
application/json:
schema:
type: object
required: [tasks]
properties:
tasks:
type: array
items: {type: string}
considerDependencies: {type: boolean}
responses:
'200':
description: Worker container updated
components:
securitySchemes:
basicAuth:
type: http
scheme: basic
description: Basic auth using your Onfleet API key as the username with an empty password.
schemas:
Task:
type: object
properties:
id: {type: string, description: 24-character resource identifier.}
shortId: {type: string}
organization: {type: string}
timeCreated: {type: integer, format: int64}
timeLastModified: {type: integer, format: int64}
executor: {type: string}
merchant: {type: string}
creator: {type: string}
worker: {type: string, nullable: true}
destination: {$ref: '#/components/schemas/Destination'}
recipients:
type: array
items: {$ref: '#/components/schemas/Recipient'}
completeAfter: {type: integer, format: int64, nullable: true}
completeBefore: {type: integer, format: int64, nullable: true}
pickupTask: {type: boolean}
dependencies:
type: array
items: {type: string}
notes: {type: string}
quantity: {type: integer}
serviceTime: {type: integer}
state: {type: integer, enum: [0, 1, 2, 3]}
completionDetails: {$ref: '#/components/schemas/CompletionDetails'}
feedback:
type: array
items: {$ref: '#/components/schemas/Feedback'}
metadata:
type: array
items: {$ref: '#/components/schemas/Metadata'}
trackingURL: {type: string, format: uri}
trackingViewed: {type: boolean}
eta: {type: integer, format: int64, nullable: true}
delayTime: {type: integer, nullable: true}
appearance:
type: object
properties:
triangleColor: {type: string, nullable: true}
container:
type: object
properties:
type: {type: string, enum: [ORGANIZATION, TEAM, WORKER]}
organization: {type: string}
TaskCreate:
type: object
properties:
merchant: {type: string}
executor: {type: string}
destination:
oneOf:
- {type: string}
- {$ref: '#/components/schemas/Destination'}
recipients:
type: array
items:
oneOf:
- {type: string}
- {$ref: '#/components/schemas/Recipient'}
completeAfter: {type: integer, format: int64}
completeBefore: {type: integer, format: int64}
pickupTask: {type: boolean}
dependencies:
type: array
items: {type: string}
notes: {type: string, maxLength: 10000}
quantity: {type: integer}
serviceTime: {type: integer}
autoAssign: {$ref: '#/components/schemas/AutoAssign'}
container: {type: object}
metadata:
type: array
items: {$ref: '#/components/schemas/Metadata'}
appearance:
type: object
properties:
triangleColor: {type: string}
TaskUpdate:
type: object
properties:
notes: {type: string}
completeAfter: {type: integer, format: int64}
completeBefore: {type: integer, format: int64}
pickupTask: {type: boolean}
quantity: {type: integer}
serviceTime: {type: integer}
metadata:
type: array
items: {$ref: '#/components/schemas/Metadata'}
TaskList:
type: object
properties:
lastId: {type: string, nullable: true}
tasks:
type: array
items: {$ref: '#/components/schemas/Task'}
Destination:
type: object
properties:
id: {type: string}
address:
type: object
properties:
unparsed: {type: string}
number: {type: string}
street: {type: string}
city: {type: string}
state: {type: string}
postalCode: {type: string}
country: {type: string}
apartment: {type: string}
location:
type: array
minItems: 2
maxItems: 2
items: {type: number}
description: GeoJSON [longitude, latitude].
notes: {type: string}
warnings:
type: array
items: {type: string}
Recipient:
type: object
properties:
id: {type: string}
name: {type: string}
phone: {type: string, description: E.164 phone number.}
notes: {type: string}
skipSMSNotifications: {type: boolean}
organization: {type: string}
AutoAssign:
type: object
properties:
mode: {type: string, enum: [distance, load]}
team: {type: string}
considerDependencies: {type: boolean}
excludedWorkerIds:
type: array
items: {type: string}
maxAssignedTaskCount: {type: integer}
CompletionDetails:
type: object
properties:
success: {type: boolean}
time: {type: integer, format: int64, nullable: true}
notes: {type: string}
photoUploadIds:
type: array
items: {type: string}
signatureUploadId: {type: string, nullable: true}
events:
type: array
items:
type: object
properties:
name: {type: string}
time: {type: integer, format: int64}
Feedback:
type: object
properties:
time: {type: integer, format: int64}
rating: {type: integer, minimum: 1, maximum: 5}
comments: {type: string}
Metadata:
type: object
required: [name, type, value]
properties:
name: {type: string}
type: {type: string, enum: [boolean, number, string, object, array]}
value: {}
visibility:
type: array
items: {type: string, enum: [api, dashboard, worker]}