> ## Documentation Index
> Fetch the complete documentation index at: https://detrack.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Jobs: The delivery and collection object in Detrack

> A Job is a single delivery or collection in Detrack. Learn its identifiers, fields, items, milestones, and lifecycle.

A **Job** is the core object in Detrack. Every delivery or collection is a job, identified by a delivery order number (`do_number`) and a `date`. Jobs contain address and contact details, one or more items, and a running list of milestones the driver records as the job progresses.

## Identifiers

Every job is uniquely identified by the combination of:

* `do_number` (string, required) — Your delivery order number.
* `date` (date, required) — The job date in `YYYY-MM-DD` format.
* `type` (string) — Either `Delivery` or `Collection`. Defaults to `Delivery`.

Detrack also assigns:

* `id` (string, read-only) — Detrack's internal ID for the job.
* `detrack_number` (string, read-only) — A human-readable Detrack tracking number, for example `DET2000001`.

Most endpoints accept the `do_number` (plus optionally `date` and `type`) to look up a job. See [Retrieve](/api-reference/jobs/retrieve).

## Required fields

Creating a job always requires:

* `do_number`
* `date`

You also need an address: either `address`, or the address lines `address_1`, `address_2`, and `address_3`. Your account settings can make other fields mandatory, such as the contact name (`deliver_to_collect_from`).

Everything else is optional but strongly recommended: contact name (`deliver_to_collect_from`), `phone_number`, `notify_email`, and `items`.

## Items

A job can carry any number of `items`. Which item fields are required depends on your account's mandatory item field settings. Items also support `quantity`, `unit_of_measure`, batch and purchase order numbers, expiry dates, and driver-captured fields like `actual_quantity`, `follow_up_quantity`, and `rework_quantity`.

```json theme={null}
{
  "items": [
    { "sku": "SKU-001", "description": "iPad", "quantity": 10 },
    { "sku": "SKU-002", "description": "iPhone", "quantity": 5 }
  ]
}
```

## Milestones

Detrack records a `milestones` array on every job as the driver progresses through statuses. Each milestone contains:

* `status` — The status the job entered, for example `info_recv`, `dispatched`, `out_for_delivery`, `completed`.
* `assign_to` — The driver at the time of the change.
* `reason` — A failure reason when the job did not complete.
* `pod_at` — When the status change happened.
* `created_at` — When the milestone was recorded.
* `user_name` — Who recorded it.

## Status fields

Job responses include three status fields. They answer different questions:

| Field | What it tells you | Example |
| - | - | - |
| `status` | Where the job is in its lifecycle. This is the field to use in your integration logic. | `dispatched`, `completed`, `failed` |
| `primary_job_status` | The same value as `status`. When you create a job, you can set it to `Info Received`, `In Transit`, or `In Progress` to choose the job's starting status. | `dispatched` |
| `tracking_status` | The customer-facing label shown on the tracking page. Detrack works it out from `status`, whether a driver is assigned, and the job date. Your account can customise the wording, so don't use it in integration logic. | `Info received`, `Scheduled`, `Out for delivery` |

For example, a delivery job with `status` `dispatched` shows a different `tracking_status` depending on assignment and date:

* Not yet assigned to a driver: "Info received"
* Assigned, with a job date in the future: "Scheduled"
* Assigned, on or after the job date: "Out for delivery"

## Lifecycle

A typical job progresses through:

1. **`info_recv`** — Detrack received the job.
2. **`dispatched`** — Assigned to a driver.
3. **`out_for_delivery`** / **`head_to_delivery`** — Driver is en route.
4. **`completed`** / **`completed_partial`** / **`failed`** — Terminal state.

Failed jobs can be reattempted with [Reattempt](/api-reference/jobs/reattempt).

## Where to go next

* [Create a job](/api-reference/jobs/create) or [bulk-create up to 100](/api-reference/jobs/bulk-create).
* [Search jobs](/api-reference/jobs/search) by date range, customer, group, status, and more.
* [Export PODs](/api-reference/jobs/bulk-export) for completed jobs.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.