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.

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.

{
  "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.

Where to go next

• Create a job or bulk-create up to 100.
• Search jobs by date range, customer, group, status, and more.
• Export PODs for completed jobs.