DTS Customer API v1

• Price a job Get a price for each service with POST /quotes.
• Book it Book the service you chose, at that price, with POST /bookings.
• Track it Read the status, progress and driver with GET /bookings/{jobNumber}, or list a day's bookings with GET /bookings.
• Get the paperwork Download the shipping label and tax invoice as PDFs, and read proof of delivery.

The API is for DTS business customers. It works over HTTPS with JSON, and each region has its own address and keys. Start by getting a key, then follow the booking flow guide. To check that a key works, call GET /account:

curl https://portal.directtransport.com.au/api/v1/account \
  -H "Authorization: Bearer $DTS_API_KEY"

Regions and base URLs

DTS has a portal in each of three regions. Each region has its own API address (base URL), its own keys and its own bookings. Use the base URL of the region your account books in.

• A key only works with the base URL of the region that issued it. Sent to another region's base URL, it's refused with invalid_api_key (401) or wrong_region (403).
• If you book in more than one region, you need a key for each region.
• A key sees only its own account's bookings in its region. Bookings of linked accounts aren't included.
• Paths in this documentation are relative to the base URL. In Sydney, POST /quotes means POST https://portal.directtransport.com.au/api/v1/quotes.
• Examples use the Sydney base URL. Melbourne and Queensland work the same way.

Melbourne's time zone is named Australia/Melbourne, but its clock is the same as Sydney's. Queensland doesn't use daylight saving time. See dates and times.

Getting a key

DTS staff issue API keys; you can't create them yourself. Email IT@directtransport.com.au with your account's name and email address, the region, and whether you need a live key, a test key or both. Keys are only for DTS business accounts.

Live and test keys

A key is dts_live_ or dts_test_ followed by 40 letters and digits. For example (this isn't a real key):

dts_test_EXAMPLEexampleEXAMPLEexampleEXAMPLE01234

Build and test with a test key first. See test mode and limits and usage. An account can have up to five keys that aren't revoked, so you can keep separate keys for separate systems, or move to a new key before the old one is revoked.

Keep keys secret

Authentication

Send your key with every request, in either of these headers:

The word Bearer isn't case-sensitive. If a request carries both headers, the Bearer key is used.

Every request checks the key and the account it belongs to, so a change such as a revoked key applies straight away. After DTS allows a paused key again, allow up to 30 seconds before every request is accepted.

curl https://portal.directtransport.com.au/api/v1/account \
  -H "Authorization: Bearer $DTS_API_KEY"

const response = await fetch("https://portal.directtransport.com.au/api/v1/account", {
  headers: { Authorization: `Bearer ${process.env.DTS_API_KEY}` },
});

import os
import requests

response = requests.get(
    "https://portal.directtransport.com.au/api/v1/account",
    headers={"Authorization": f"Bearer {os.environ['DTS_API_KEY']}"},
    timeout=30,
)

Authentication errors

Requests and responses

Requests

• Use HTTPS and your region's base URL.
• Send request bodies as JSON, with Content-Type: application/json. Other content types are refused with unsupported_media_type (415). A body that isn't valid JSON gets invalid_request (400).
• A request body can be up to 100 KB (102,400 bytes). A larger body gets payload_too_large (413).
• Field names are case-sensitive. Fields the API doesn't know are refused with invalid_request, so a mistyped name is never silently ignored. The same goes for query parameters on GET /bookings and the label and invoice endpoints.
• Types are strict. Send numbers as JSON numbers (12.5, not "12.5") and yes/no values as true or false.
• Spaces at the start and end of text such as addresses, names, phone numbers, references and instructions are removed.
• The JavaScript examples use fetch, which is built into Node.js 18 and later; run them in an ES module or an async function. The Python examples use the requests package.

Responses

A successful response has the result in data. Each endpoint below describes its data.

{
  "data": {},
  "requestId": "req_0f8c2a5d9b7e4c1a8e3f6b2d4a9c7e10"
}

An error response has an error object instead:

{
  "error": {
    "code": "invalid_request",
    "message": "Some fields aren't valid.",
    "details": [
      { "field": "items.0.weightKg", "message": "weightKg must be more than 0." },
      { "field": "expectedTotal", "message": "Send expectedTotal: the price.total of the service you chose from POST /quotes." }
    ]
  },
  "requestId": "req_7d1e4b9a2c6f4e8d9a0b3c5e7f1a2b4c"
}

• code doesn't change, so build your error handling on it. Every code is listed under errors.
• message is written for people and may change. It usually says exactly what to fix, so log it and show it to your staff.
• details is only there for some errors. For invalid_request it's a list of field and message pairs. field is the path to the field, counting items from 0 (items.0.weightKg is the first item's weight), or null when the problem isn't a single field, such as an unknown field at the top level of the body. Other errors' details are described with each error.
• A response may not list every problem at once. Checks that compare fields (such as tailgate with HIAB) only run once no field is missing, of the wrong type, or outside its list of allowed values.

Response headers

Dates and times

• Ready dates and times, and the dates you list bookings by, are in the region's time zone: Australia/Sydney for Sydney, Australia/Melbourne for Melbourne (the same clock as Sydney) and Australia/Brisbane for Queensland, which has no daylight saving time. Responses repeat the zone in readyAt.timeZone.
• Dates are YYYY-MM-DD, for example 2026-09-15. Times are 24-hour HH:mm, for example 09:30 or 17:45.
• Moments such as createdAt and the progress times are ISO 8601 in UTC, for example 2026-09-14T06:05:12.412Z.
• Daily limits count from midnight to midnight in the region's time zone.

The price object

Quotes and bookings show money in a price object. Amounts are Australian dollars, as numbers rounded to the cent.

{
  "currency": "AUD",
  "base": 95,
  "serviceCharge": 9.5,
  "tailgate": 35,
  "hiab": 0,
  "insurance": 0,
  "waitTime": 0,
  "tolls": 4.2,
  "totalExGst": 143.7,
  "gst": 13.95,
  "total": 157.65
}

Booking flow guide

Booking through the API follows the same steps as Place the Booking on the portal: price the job, choose a service, book it at that price, then track it.

1. Price the jobPOST /quotes with the addresses, the ready date and time, and the items. You get a price for each service.
2. Choose a servicePick an option with "bookable": true. The other options say why they can't be booked.
3. Book itPOST /bookings with the same job, the service, contact and references, an Idempotency-Key and expectedTotal.
4. Track itGET /bookings/{jobNumber} for status and progress. Download the label and invoice, and read proof of delivery.

Step 1: Price the job

Send the job to POST /quotes: the booking type, when the job will be ready, the pickup and delivery addresses, and either the items or a job code, plus tailgate, HIAB or insurance if you need them. Nothing is booked.

This example is a Same Day job in Sydney, ready at 9:30 AM on Tuesday 15 September 2026: two pallets and six boxes, with a tailgate.

curl https://portal.directtransport.com.au/api/v1/quotes \
  -H "Authorization: Bearer $DTS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "bookingType": "same_day",
    "readyAt": { "date": "2026-09-15", "time": "09:30" },
    "pickup": { "address": "Unit 4, 10 Example Street, Silverwater NSW 2128" },
    "delivery": { "address": "25 Sample Road, Botany NSW 2019" },
    "items": [
      { "type": "Pallet", "quantity": 2, "weightKg": 180, "lengthCm": 120, "widthCm": 120, "heightCm": 110 },
      { "type": "Box", "quantity": 6, "weightKg": 12.5, "lengthCm": 40, "widthCm": 30, "heightCm": 30, "stackable": true }
    ],
    "tailgate": true
  }'

const job = {
  bookingType: "same_day",
  readyAt: { date: "2026-09-15", time: "09:30" },
  pickup: { address: "Unit 4, 10 Example Street, Silverwater NSW 2128" },
  delivery: { address: "25 Sample Road, Botany NSW 2019" },
  items: [
    { type: "Pallet", quantity: 2, weightKg: 180, lengthCm: 120, widthCm: 120, heightCm: 110 },
    { type: "Box", quantity: 6, weightKg: 12.5, lengthCm: 40, widthCm: 30, heightCm: 30, stackable: true },
  ],
  tailgate: true,
};

const response = await fetch("https://portal.directtransport.com.au/api/v1/quotes", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.DTS_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify(job),
});
const quote = await response.json();

import os
import requests

job = {
    "bookingType": "same_day",
    "readyAt": {"date": "2026-09-15", "time": "09:30"},
    "pickup": {"address": "Unit 4, 10 Example Street, Silverwater NSW 2128"},
    "delivery": {"address": "25 Sample Road, Botany NSW 2019"},
    "items": [
        {"type": "Pallet", "quantity": 2, "weightKg": 180, "lengthCm": 120, "widthCm": 120, "heightCm": 110},
        {"type": "Box", "quantity": 6, "weightKg": 12.5, "lengthCm": 40, "widthCm": 30, "heightCm": 30, "stackable": True},
    ],
    "tailgate": True,
}

response = requests.post(
    "https://portal.directtransport.com.au/api/v1/quotes",
    headers={"Authorization": f"Bearer {os.environ['DTS_API_KEY']}"},
    json=job,
    timeout=60,
)
quote = response.json()

200 OK

{
  "data": {
    "bookingType": "same_day",
    "readyAt": { "date": "2026-09-15", "time": "09:30", "timeZone": "Australia/Sydney" },
    "serviceArea": "metro",
    "pickup": {
      "address": "Unit 4/10 Example St, Silverwater NSW 2128, Australia",
      "suburb": "Silverwater",
      "state": "NSW",
      "postcode": "2128",
      "location": { "lat": -33.8352, "lng": 151.0473 },
      "precision": "exact",
      "insideMetroArea": true
    },
    "delivery": {
      "address": "25 Sample Rd, Botany NSW 2019, Australia",
      "suburb": "Botany",
      "state": "NSW",
      "postcode": "2019",
      "location": { "lat": -33.9461, "lng": 151.1965 },
      "precision": "exact",
      "insideMetroArea": true
    },
    "distanceKm": 24.6,
    "options": [
      {
        "service": "Standard",
        "bookable": true,
        "jobCode": "1T",
        "vehicle": "1T",
        "price": { "currency": "AUD", "base": 95, "serviceCharge": 9.5, "tailgate": 35, "hiab": 0, "insurance": 0, "waitTime": 0, "tolls": 4.2, "totalExGst": 143.7, "gst": 13.95, "total": 157.65 }
      },
      {
        "service": "Express",
        "bookable": true,
        "jobCode": "1T",
        "vehicle": "1T",
        "price": { "currency": "AUD", "base": 125, "serviceCharge": 12.5, "tailgate": 35, "hiab": 0, "insurance": 0, "waitTime": 0, "tolls": 4.2, "totalExGst": 176.7, "gst": 17.25, "total": 193.95 }
      },
      {
        "service": "Direct",
        "bookable": true,
        "jobCode": "1T",
        "vehicle": "1T",
        "price": { "currency": "AUD", "base": 160, "serviceCharge": 16, "tailgate": 35, "hiab": 0, "insurance": 0, "waitTime": 0, "tolls": 4.2, "totalExGst": 215.2, "gst": 21.1, "total": 236.3 }
      },
      {
        "service": "After Hours",
        "bookable": false,
        "reason": "outside_service_hours",
        "message": "After Hours jobs need a ready time before 7:00 AM or after 5:00 PM.",
        "jobCode": "1T",
        "vehicle": "1T",
        "price": { "currency": "AUD", "base": 210, "serviceCharge": 21, "tailgate": 35, "hiab": 0, "insurance": 0, "waitTime": 0, "tolls": 4.2, "totalExGst": 270.2, "gst": 26.6, "total": 296.8 }
      },
      {
        "service": "Weekend Deliveries",
        "bookable": false,
        "reason": "outside_service_hours",
        "message": "Weekend Deliveries need a ready date on a Saturday or Sunday.",
        "jobCode": "1T",
        "vehicle": "1T",
        "price": { "currency": "AUD", "base": 230, "serviceCharge": 23, "tailgate": 35, "hiab": 0, "insurance": 0, "waitTime": 0, "tolls": 4.2, "totalExGst": 292.2, "gst": 28.8, "total": 321 }
      }
    ]
  },
  "requestId": "req_3b9e1f7c5a2d4e6f8a1b3c5d7e9f0a2b"
}

Step 2: Choose a service

Each entry in options is one service.

• Only options with "bookable": true can be booked. In the example, that's Standard, Express and Direct.
• An option with "bookable": false has a reason code and a message you can show. Here, After Hours and Weekend Deliveries can't be booked because 9:30 AM on a Tuesday is outside their hours. All reasons are listed under option reasons.
• Keep the chosen option's price.total. You send it as expectedTotal when you book.
• Check pickup.precision and delivery.precision. If either address was only found approximately (approximate), a driver can't be sent to it, so the job can't be booked: every option that was priced has "bookable": false with the reason address_not_precise, and its message names the address. The prices are still shown. Send a full street address, or add its location, and price the job again (see addresses).

For example, if the delivery address had been sent as just Botany NSW, the Standard option would come back like this:

{
  "service": "Standard",
  "bookable": false,
  "reason": "address_not_precise",
  "message": "The delivery address was found as \"Botany NSW 2019, Australia\", which isn't precise enough to send a driver to. Send a full street address, or its location as well.",
  "jobCode": "1T",
  "vehicle": "1T",
  "price": { "currency": "AUD", "base": 92, "serviceCharge": 9.2, "tailgate": 35, "hiab": 0, "insurance": 0, "waitTime": 0, "tolls": 4.2, "totalExGst": 140.4, "gst": 13.62, "total": 154.02 }
}

const option = quote.data.options.find((o) => o.bookable && o.service === "Standard");
if (!option) {
  // Show why each service can't be booked, and let the person booking choose again.
  for (const o of quote.data.options) console.log(o.service, o.bookable, o.reason ?? "", o.message ?? "");
  throw new Error("Standard can't be booked for this job.");
}
const expectedTotal = option.price.total; // 157.65

options = quote["data"]["options"]
option = next((o for o in options if o["bookable"] and o["service"] == "Standard"), None)
if option is None:
    # Show why each service can't be booked, and let the person booking choose again.
    for o in options:
        print(o["service"], o["bookable"], o.get("reason", ""), o.get("message", ""))
    raise SystemExit("Standard can't be booked for this job.")
expected_total = option["price"]["total"]  # 157.65

Step 3: Book the job

Send POST /bookings with:

• the same job details you priced: bookingType, readyAt, the pickup and delivery addresses (and location, if you sent it), items or jobCode, and tailgate, hiab and insurance;
• the service you chose;
• contact, the name of the person to contact about the job, and if you like, a company name, phone number, reference and instructions for each address, and your own internalReference and internalReference2;
• expectedTotal, the chosen option's price.total (required);
• an Idempotency-Key header with a new unique value, such as a UUID, so that retrying the request can't book the job twice.

curl https://portal.directtransport.com.au/api/v1/bookings \
  -H "Authorization: Bearer $DTS_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "bookingType": "same_day",
    "readyAt": { "date": "2026-09-15", "time": "09:30" },
    "service": "Standard",
    "pickup": {
      "address": "Unit 4, 10 Example Street, Silverwater NSW 2128",
      "companyName": "Acme Freight",
      "phone": "02 5550 1234",
      "reference": "PO-1001",
      "instructions": "Loading dock at the rear."
    },
    "delivery": {
      "address": "25 Sample Road, Botany NSW 2019",
      "companyName": "Example Retail",
      "phone": "02 5550 5678",
      "reference": "INV-2002",
      "instructions": "Deliver to goods inwards."
    },
    "items": [
      { "type": "Pallet", "quantity": 2, "weightKg": 180, "lengthCm": 120, "widthCm": 120, "heightCm": 110 },
      { "type": "Box", "quantity": 6, "weightKg": 12.5, "lengthCm": 40, "widthCm": 30, "heightCm": 30, "stackable": true }
    ],
    "tailgate": true,
    "contact": "Jamie Citizen",
    "internalReference": "ORDER-5501",
    "expectedTotal": 157.65
  }'

import { randomUUID } from "node:crypto";

// One key for this booking: send it with every attempt until the booking is made.
const idempotencyKey = randomUUID();

const response = await fetch("https://portal.directtransport.com.au/api/v1/bookings", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.DTS_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": idempotencyKey,
  },
  body: JSON.stringify({
    ...job, // the same job details you priced in step 1
    service: "Standard",
    pickup: {
      ...job.pickup,
      companyName: "Acme Freight",
      phone: "02 5550 1234",
      reference: "PO-1001",
      instructions: "Loading dock at the rear.",
    },
    delivery: {
      ...job.delivery,
      companyName: "Example Retail",
      phone: "02 5550 5678",
      reference: "INV-2002",
      instructions: "Deliver to goods inwards.",
    },
    contact: "Jamie Citizen",
    internalReference: "ORDER-5501",
    expectedTotal: option.price.total, // 157.65
  }),
});
const booking = await response.json();

import uuid

# One key for this booking: send it with every attempt until the booking is made.
idempotency_key = str(uuid.uuid4())

booking_request = {
    **job,  # the same job details you priced in step 1
    "service": "Standard",
    "pickup": {
        **job["pickup"],
        "companyName": "Acme Freight",
        "phone": "02 5550 1234",
        "reference": "PO-1001",
        "instructions": "Loading dock at the rear.",
    },
    "delivery": {
        **job["delivery"],
        "companyName": "Example Retail",
        "phone": "02 5550 5678",
        "reference": "INV-2002",
        "instructions": "Deliver to goods inwards.",
    },
    "contact": "Jamie Citizen",
    "internalReference": "ORDER-5501",
    "expectedTotal": option["price"]["total"],  # 157.65
}

response = requests.post(
    "https://portal.directtransport.com.au/api/v1/bookings",
    headers={
        "Authorization": f"Bearer {os.environ['DTS_API_KEY']}",
        "Idempotency-Key": idempotency_key,
    },
    json=booking_request,
    timeout=60,
)
booking = response.json()

The booking is made. The answer is 201 Created, with the new booking's path in Location and the booking in data:

HTTP/1.1 201 Created
Content-Type: application/json
Location: /api/v1/bookings/DTS12345
X-Request-Id: req_9c2d7e4f1a6b4c8d8e2f5a7b9c1d3e5f
X-DTS-Mode: live
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 57
X-RateLimit-Reset: 48
Cache-Control: no-store

{
  "data": {
    "jobNumber": "DTS12345",
    "testMode": false,
    "status": "pending",
    "bookingType": "same_day",
    "service": "Standard",
    "readyAt": { "date": "2026-09-15", "time": "09:30", "timeZone": "Australia/Sydney" },
    "createdAt": "2026-09-14T06:05:12.412Z",
    "contact": "Jamie Citizen",
    "internalReference": "ORDER-5501",
    "internalReference2": "",
    "pickup": {
      "companyName": "Acme Freight",
      "address": "Unit 4/10 Example St, Silverwater NSW 2128, Australia",
      "suburb": "Silverwater",
      "reference": "PO-1001",
      "phone": "02 5550 1234",
      "instructions": "Loading dock at the rear.",
      "location": { "lat": -33.8352, "lng": 151.0473 }
    },
    "delivery": {
      "companyName": "Example Retail",
      "address": "25 Sample Rd, Botany NSW 2019, Australia",
      "suburb": "Botany",
      "reference": "INV-2002",
      "phone": "02 5550 5678",
      "instructions": "Deliver to goods inwards.",
      "location": { "lat": -33.9461, "lng": 151.1965 }
    },
    "items": [
      { "type": "Pallet", "quantity": 2, "weightKg": 180, "lengthCm": 120, "widthCm": 120, "heightCm": 110, "stackable": false },
      { "type": "Box", "quantity": 6, "weightKg": 12.5, "lengthCm": 40, "widthCm": 30, "heightCm": 30, "stackable": true }
    ],
    "jobCode": "1T",
    "vehicle": "1T",
    "tailgate": true,
    "hiab": false,
    "insurance": false,
    "distanceKm": 24.6,
    "price": { "currency": "AUD", "base": 95, "serviceCharge": 9.5, "tailgate": 35, "hiab": 0, "insurance": 0, "waitTime": 0, "tolls": 4.2, "totalExGst": 143.7, "gst": 13.95, "total": 157.65 }
  },
  "requestId": "req_9c2d7e4f1a6b4c8d8e2f5a7b9c1d3e5f"
}

409 Conflict

{
  "error": {
    "code": "price_changed",
    "message": "The price for this job is now $161.05. Send that as expectedTotal to book at this price.",
    "details": {
      "expectedTotal": 157.65,
      "price": { "currency": "AUD", "base": 95, "serviceCharge": 9.5, "tailgate": 35, "hiab": 0, "insurance": 0, "waitTime": 0, "tolls": 7.6, "totalExGst": 147.1, "gst": 13.95, "total": 161.05 }
    }
  },
  "requestId": "req_4e6a8c0b2d4f4a6c8e0b2d4f6a8c0e2b"
}

A booking can also be refused because an address was only found approximately (address_not_precise), the service can't be booked for the ready time (service_not_available), the job needs a custom quote or can't be priced online (cannot_price_online), or a field is missing, not valid or required by your account (invalid_request). See POST /bookings for every case.

Step 4: Track the booking

• GET /bookings/DTS12345 returns the booking with its status, progress times, driver and whether proof of delivery is available.
• GET /bookings?date=2026-09-15 lists your bookings ready on a day. Use from and to for up to 31 days.
• GET /bookings/DTS12345/label?paper=A4 and GET /bookings/DTS12345/invoice return the shipping label and the tax invoice as PDFs.
• GET /bookings/DTS12345/pod returns proof of delivery, if it's turned on for your account.

To follow a job, check it every few minutes, and stop once it's delivered, returned, futile or cancelled. When you follow many jobs, one GET /bookings?date=… page uses one request of your limits instead of one per job.

Full example

The whole flow in one script: price a job, choose Standard, book it, handle a changed price, and read the booking back.

// book-a-job.mjs: price, choose, book and track a job. Node.js 18 or later.
import { randomUUID } from "node:crypto";

const BASE_URL = "https://portal.directtransport.com.au/api/v1";
const API_KEY = process.env.DTS_API_KEY; // keep keys on your server

async function api(method, path, { body, headers = {} } = {}) {
  const response = await fetch(BASE_URL + path, {
    method,
    headers: {
      Authorization: `Bearer ${API_KEY}`,
      ...(body ? { "Content-Type": "application/json" } : {}),
      ...headers,
    },
    body: body ? JSON.stringify(body) : undefined,
  });
  return { status: response.status, payload: await response.json() };
}

const job = {
  bookingType: "same_day",
  readyAt: { date: "2026-09-15", time: "09:30" },
  pickup: { address: "Unit 4, 10 Example Street, Silverwater NSW 2128" },
  delivery: { address: "25 Sample Road, Botany NSW 2019" },
  items: [{ type: "Pallet", quantity: 2, weightKg: 180, lengthCm: 120, widthCm: 120, heightCm: 110 }],
  tailgate: true,
};

// 1. Price the job.
const quote = await api("POST", "/quotes", { body: job });
if (quote.status !== 200) throw new Error(`${quote.payload.error.code}: ${quote.payload.error.message}`);

// 2. Choose a service that can be booked.
const option = quote.payload.data.options.find((o) => o.bookable && o.service === "Standard");
if (!option) throw new Error("Standard can't be booked for this job.");

// 3. Book it at the price shown.
// One Idempotency-Key for this booking. A retry after a timeout can't book twice, and a refusal
// such as price_changed doesn't use the key up, so the same key is sent again with the new price.
const idempotencyKey = randomUUID();

function book(expectedTotal) {
  return api("POST", "/bookings", {
    headers: { "Idempotency-Key": idempotencyKey },
    body: {
      ...job,
      service: option.service,
      pickup: { ...job.pickup, companyName: "Acme Freight", phone: "02 5550 1234" },
      delivery: { ...job.delivery, companyName: "Example Retail", phone: "02 5550 5678" },
      contact: "Jamie Citizen",
      internalReference: "ORDER-5501",
      expectedTotal,
    },
  });
}

let booking = await book(option.price.total);
if (booking.status === 409 && booking.payload.error.code === "price_changed") {
  const newTotal = booking.payload.error.details.price.total;
  // Nothing was booked. This script accepts the new total; your system may need a person to confirm it.
  console.log(`The price is now $${newTotal.toFixed(2)}.`);
  booking = await book(newTotal);
}
if (booking.status !== 201) throw new Error(`${booking.payload.error.code}: ${booking.payload.error.message}`);

const { jobNumber } = booking.payload.data;
console.log(`Booked ${jobNumber}`);

// 4. Track it.
const detail = await api("GET", `/bookings/${jobNumber}`);
console.log(detail.payload.data.status, detail.payload.data.progress);

# book_a_job.py: price, choose, book and track a job. Needs the requests package.
import os
import uuid

import requests

BASE_URL = "https://portal.directtransport.com.au/api/v1"
session = requests.Session()
session.headers["Authorization"] = f"Bearer {os.environ['DTS_API_KEY']}"  # keep keys on your server

job = {
    "bookingType": "same_day",
    "readyAt": {"date": "2026-09-15", "time": "09:30"},
    "pickup": {"address": "Unit 4, 10 Example Street, Silverwater NSW 2128"},
    "delivery": {"address": "25 Sample Road, Botany NSW 2019"},
    "items": [{"type": "Pallet", "quantity": 2, "weightKg": 180, "lengthCm": 120, "widthCm": 120, "heightCm": 110}],
    "tailgate": True,
}


def fail(response):
    error = response.json()["error"]
    raise SystemExit(f"{error['code']}: {error['message']}")


# 1. Price the job.
quote = session.post(f"{BASE_URL}/quotes", json=job, timeout=60)
if quote.status_code != 200:
    fail(quote)

# 2. Choose a service that can be booked.
options = quote.json()["data"]["options"]
option = next((o for o in options if o["bookable"] and o["service"] == "Standard"), None)
if option is None:
    raise SystemExit("Standard can't be booked for this job.")


# 3. Book it at the price shown.
# One Idempotency-Key for this booking. A retry after a timeout can't book twice, and a refusal
# such as price_changed doesn't use the key up, so the same key is sent again with the new price.
idempotency_key = str(uuid.uuid4())


def book(expected_total):
    body = {
        **job,
        "service": option["service"],
        "pickup": {**job["pickup"], "companyName": "Acme Freight", "phone": "02 5550 1234"},
        "delivery": {**job["delivery"], "companyName": "Example Retail", "phone": "02 5550 5678"},
        "contact": "Jamie Citizen",
        "internalReference": "ORDER-5501",
        "expectedTotal": expected_total,
    }
    headers = {"Idempotency-Key": idempotency_key}
    return session.post(f"{BASE_URL}/bookings", json=body, headers=headers, timeout=60)


booking = book(option["price"]["total"])
if booking.status_code == 409 and booking.json()["error"]["code"] == "price_changed":
    new_total = booking.json()["error"]["details"]["price"]["total"]
    # Nothing was booked. This script accepts the new total; your system may need a person to confirm it.
    print(f"The price is now ${new_total:.2f}.")
    booking = book(new_total)
if booking.status_code != 201:
    fail(booking)

job_number = booking.json()["data"]["jobNumber"]
print(f"Booked {job_number}")

# 4. Track it.
detail = session.get(f"{BASE_URL}/bookings/{job_number}", timeout=30).json()["data"]
print(detail["status"], detail["progress"])

Endpoints

All paths are relative to your region's base URL.

Errors any endpoint can return

As well as the errors listed with each endpoint, any request can get missing_api_key, invalid_api_key, key_revoked, key_suspended, account_not_allowed or wrong_region (see authentication errors), rate_limited or daily_limit_reached (see limits and usage), and internal_error or service_unavailable. Every code is in the errors table.

curl https://portal.directtransport.com.au/api/v1/account \
  -H "Authorization: Bearer $DTS_API_KEY"

const response = await fetch("https://portal.directtransport.com.au/api/v1/account", {
  headers: { Authorization: `Bearer ${process.env.DTS_API_KEY}` },
});
const { data } = await response.json();
console.log(data.key.mode, data.region, data.usageToday);

import os
import requests

response = requests.get(
    "https://portal.directtransport.com.au/api/v1/account",
    headers={"Authorization": f"Bearer {os.environ['DTS_API_KEY']}"},
    timeout=30,
)
data = response.json()["data"]
print(data["key"]["mode"], data["region"], data["usageToday"])

{
  "data": {
    "key": {
      "id": "key_EXAMPLEexample12",
      "mode": "test",
      "prefix": "dts_test_EXAMPL",
      "label": "Test key",
      "createdAt": "2026-09-14T00:12:45.318Z"
    },
    "account": { "email": "bookings@acmefreight.example", "name": "Acme Freight" },
    "region": "sydney",
    "limits": {
      "requestsPerMinute": 60,
      "requestsPerDay": 5000,
      "priceChecksPerDay": 200,
      "bookingsPerDay": 200,
      "documentsPerDay": 500,
      "googleCallsPerDay": 600,
      "tollCallsPerDay": 200,
      "databaseReadsPerDay": 250000,
      "databaseWritesPerDay": 100000,
      "rateLimitedPerDay": 1000
    },
    "usageToday": {
      "requests": 42,
      "priceChecks": 12,
      "bookings": 3,
      "documents": 4,
      "googleCalls": 36,
      "tollCalls": 5,
      "databaseReads": 287,
      "databaseWrites": 151,
      "rateLimited": 0
    }
  },
  "requestId": "req_1a3c5e7f9b2d4f6a8c0e1b3d5f7a9c2e"
}

curl https://portal.directtransport.com.au/api/v1/quotes \
  -H "Authorization: Bearer $DTS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "bookingType": "same_day",
    "readyAt": { "date": "2026-09-15", "time": "09:30" },
    "services": ["Standard", "Express"],
    "pickup": { "address": "Unit 4, 10 Example Street, Silverwater NSW 2128" },
    "delivery": {
      "address": "25 Sample Road, Botany NSW 2019",
      "location": { "lat": -33.9461, "lng": 151.1965 }
    },
    "items": [
      { "type": "Box", "quantity": 3, "weightKg": 8, "lengthCm": 40, "widthCm": 30, "heightCm": 30, "stackable": true }
    ]
  }'

const response = await fetch("https://portal.directtransport.com.au/api/v1/quotes", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.DTS_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    bookingType: "same_day",
    readyAt: { date: "2026-09-15", time: "09:30" },
    services: ["Standard", "Express"],
    pickup: { address: "Unit 4, 10 Example Street, Silverwater NSW 2128" },
    delivery: {
      address: "25 Sample Road, Botany NSW 2019",
      location: { lat: -33.9461, lng: 151.1965 },
    },
    items: [{ type: "Box", quantity: 3, weightKg: 8, lengthCm: 40, widthCm: 30, heightCm: 30, stackable: true }],
  }),
});
const quote = await response.json();
if (!response.ok) throw new Error(`${quote.error.code}: ${quote.error.message}`);
const bookable = quote.data.options.filter((option) => option.bookable);

import os
import requests

response = requests.post(
    "https://portal.directtransport.com.au/api/v1/quotes",
    headers={"Authorization": f"Bearer {os.environ['DTS_API_KEY']}"},
    json={
        "bookingType": "same_day",
        "readyAt": {"date": "2026-09-15", "time": "09:30"},
        "services": ["Standard", "Express"],
        "pickup": {"address": "Unit 4, 10 Example Street, Silverwater NSW 2128"},
        "delivery": {
            "address": "25 Sample Road, Botany NSW 2019",
            "location": {"lat": -33.9461, "lng": 151.1965},
        },
        "items": [{"type": "Box", "quantity": 3, "weightKg": 8, "lengthCm": 40, "widthCm": 30, "heightCm": 30, "stackable": True}],
    },
    timeout=60,
)
quote = response.json()
if not response.ok:
    raise SystemExit(f"{quote['error']['code']}: {quote['error']['message']}")
bookable = [option for option in quote["data"]["options"] if option["bookable"]]

{
  "data": {
    "bookingType": "same_day",
    "readyAt": { "date": "2026-09-15", "time": "09:30", "timeZone": "Australia/Sydney" },
    "serviceArea": "metro",
    "pickup": {
      "address": "Unit 4/10 Example St, Silverwater NSW 2128, Australia",
      "suburb": "Silverwater",
      "state": "NSW",
      "postcode": "2128",
      "location": { "lat": -33.8352, "lng": 151.0473 },
      "precision": "exact",
      "insideMetroArea": true
    },
    "delivery": {
      "address": "25 Sample Rd, Botany NSW 2019, Australia",
      "suburb": "Botany",
      "state": "NSW",
      "postcode": "2019",
      "location": { "lat": -33.9461, "lng": 151.1965 },
      "precision": "exact",
      "insideMetroArea": true
    },
    "distanceKm": 24.6,
    "options": [
      {
        "service": "Standard",
        "bookable": true,
        "jobCode": "HT",
        "vehicle": "HT",
        "price": { "currency": "AUD", "base": 38, "serviceCharge": 3.8, "tailgate": 0, "hiab": 0, "insurance": 0, "waitTime": 0, "tolls": 4.2, "totalExGst": 46, "gst": 4.18, "total": 50.18 }
      },
      {
        "service": "Express",
        "bookable": true,
        "jobCode": "HT",
        "vehicle": "HT",
        "price": { "currency": "AUD", "base": 52, "serviceCharge": 5.2, "tailgate": 0, "hiab": 0, "insurance": 0, "waitTime": 0, "tolls": 4.2, "totalExGst": 61.4, "gst": 5.72, "total": 67.12 }
      }
    ]
  },
  "requestId": "req_5d7f9b1c3e5a4c7e9b1d3f5a7c9e1b3d"
}

{
  "service": "Standard",
  "bookable": false,
  "reason": "custom_quote_required",
  "message": "This load falls outside our standard vehicle limits. Our bookings team will review the job details and prepare the right vehicle and pricing for you.",
  "contactEmail": "bookings@directtransport.com.au"
}

curl https://portal.directtransport.com.au/api/v1/bookings \
  -H "Authorization: Bearer $DTS_TEST_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 0b8f3c52-6d1e-4a7b-9c2d-5e8f1a3b7c64" \
  -d '{
    "bookingType": "same_day",
    "readyAt": { "date": "2026-09-15", "time": "09:30" },
    "service": "Standard",
    "pickup": {
      "address": "Unit 4, 10 Example Street, Silverwater NSW 2128",
      "companyName": "Acme Freight",
      "phone": "02 5550 1234"
    },
    "delivery": {
      "address": "25 Sample Road, Botany NSW 2019",
      "location": { "lat": -33.9461, "lng": 151.1965 },
      "companyName": "Example Retail"
    },
    "items": [
      { "type": "Box", "quantity": 3, "weightKg": 8, "lengthCm": 40, "widthCm": 30, "heightCm": 30, "stackable": true }
    ],
    "contact": "Jamie Citizen",
    "internalReference": "ORDER-5502",
    "expectedTotal": 50.18
  }'

import { randomUUID } from "node:crypto";

const idempotencyKey = randomUUID(); // use it for every attempt at this booking until it's made

const response = await fetch("https://portal.directtransport.com.au/api/v1/bookings", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.DTS_TEST_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": idempotencyKey,
  },
  body: JSON.stringify({
    bookingType: "same_day",
    readyAt: { date: "2026-09-15", time: "09:30" },
    service: "Standard",
    pickup: {
      address: "Unit 4, 10 Example Street, Silverwater NSW 2128",
      companyName: "Acme Freight",
      phone: "02 5550 1234",
    },
    delivery: {
      address: "25 Sample Road, Botany NSW 2019",
      location: { lat: -33.9461, lng: 151.1965 },
      companyName: "Example Retail",
    },
    items: [{ type: "Box", quantity: 3, weightKg: 8, lengthCm: 40, widthCm: 30, heightCm: 30, stackable: true }],
    contact: "Jamie Citizen",
    internalReference: "ORDER-5502",
    expectedTotal: 50.18,
  }),
});
const result = await response.json();
if (response.status === 201) {
  console.log("Booked", result.data.jobNumber);
} else {
  console.error(result.error.code, result.error.message, result.error.details);
}

import os
import uuid
import requests

idempotency_key = str(uuid.uuid4())  # use it for every attempt at this booking until it's made

response = requests.post(
    "https://portal.directtransport.com.au/api/v1/bookings",
    headers={
        "Authorization": f"Bearer {os.environ['DTS_TEST_API_KEY']}",
        "Idempotency-Key": idempotency_key,
    },
    json={
        "bookingType": "same_day",
        "readyAt": {"date": "2026-09-15", "time": "09:30"},
        "service": "Standard",
        "pickup": {
            "address": "Unit 4, 10 Example Street, Silverwater NSW 2128",
            "companyName": "Acme Freight",
            "phone": "02 5550 1234",
        },
        "delivery": {
            "address": "25 Sample Road, Botany NSW 2019",
            "location": {"lat": -33.9461, "lng": 151.1965},
            "companyName": "Example Retail",
        },
        "items": [{"type": "Box", "quantity": 3, "weightKg": 8, "lengthCm": 40, "widthCm": 30, "heightCm": 30, "stackable": True}],
        "contact": "Jamie Citizen",
        "internalReference": "ORDER-5502",
        "expectedTotal": 50.18,
    },
    timeout=60,
)
result = response.json()
if response.status_code == 201:
    print("Booked", result["data"]["jobNumber"])
else:
    print(result["error"]["code"], result["error"]["message"], result["error"].get("details"))

{
  "data": {
    "jobNumber": "TEST-DTS12345",
    "testMode": true,
    "status": "pending",
    "bookingType": "same_day",
    "service": "Standard",
    "readyAt": { "date": "2026-09-15", "time": "09:30", "timeZone": "Australia/Sydney" },
    "createdAt": "2026-09-14T06:20:31.907Z",
    "contact": "Jamie Citizen",
    "internalReference": "ORDER-5502",
    "internalReference2": "",
    "pickup": {
      "companyName": "Acme Freight",
      "address": "Unit 4/10 Example St, Silverwater NSW 2128, Australia",
      "suburb": "Silverwater",
      "reference": "",
      "phone": "02 5550 1234",
      "instructions": "",
      "location": { "lat": -33.8352, "lng": 151.0473 }
    },
    "delivery": {
      "companyName": "Example Retail",
      "address": "25 Sample Rd, Botany NSW 2019, Australia",
      "suburb": "Botany",
      "reference": "",
      "phone": "",
      "instructions": "",
      "location": { "lat": -33.9461, "lng": 151.1965 }
    },
    "items": [
      { "type": "Box", "quantity": 3, "weightKg": 8, "lengthCm": 40, "widthCm": 30, "heightCm": 30, "stackable": true }
    ],
    "jobCode": "HT",
    "vehicle": "HT",
    "tailgate": false,
    "hiab": false,
    "insurance": false,
    "distanceKm": 24.6,
    "price": { "currency": "AUD", "base": 38, "serviceCharge": 3.8, "tailgate": 0, "hiab": 0, "insurance": 0, "waitTime": 0, "tolls": 4.2, "totalExGst": 46, "gst": 4.18, "total": 50.18 }
  },
  "requestId": "req_6f8a0c2e4b6d4f8a0c2e4b6d8f0a2c4e"
}

{
  "error": {
    "code": "service_not_available",
    "message": "Standard jobs ready today need a ready time between 7:00 AM and 3:00 PM.",
    "details": [
      {
        "field": "service",
        "reason": "outside_service_hours",
        "message": "Standard jobs ready today need a ready time between 7:00 AM and 3:00 PM."
      }
    ]
  },
  "requestId": "req_2c4e6a8b0d2f4b6d8a0c2e4f6b8d0a1c"
}

{
  "error": {
    "code": "cannot_price_online",
    "message": "This load falls outside our standard vehicle limits. Our bookings team will review the job details and prepare the right vehicle and pricing for you.",
    "details": {
      "reason": "custom_quote_required",
      "contactEmail": "bookings@directtransport.com.au"
    }
  },
  "requestId": "req_8b0d2f4a6c8e4a0c2e4b6d8f0a2c4e6b"
}

curl "https://portal.directtransport.com.au/api/v1/bookings?date=2026-09-15&limit=2" \
  -H "Authorization: Bearer $DTS_API_KEY"

const params = new URLSearchParams({ date: "2026-09-15", limit: "2" });
const response = await fetch(`https://portal.directtransport.com.au/api/v1/bookings?${params}`, {
  headers: { Authorization: `Bearer ${process.env.DTS_API_KEY}` },
});
const { data } = await response.json();
for (const booking of data.bookings) console.log(booking.jobNumber, booking.status);
console.log("Next page:", data.nextCursor);

import os
import requests

response = requests.get(
    "https://portal.directtransport.com.au/api/v1/bookings",
    headers={"Authorization": f"Bearer {os.environ['DTS_API_KEY']}"},
    params={"date": "2026-09-15", "limit": 2},
    timeout=30,
)
data = response.json()["data"]
for booking in data["bookings"]:
    print(booking["jobNumber"], booking["status"])
print("Next page:", data["nextCursor"])

{
  "data": {
    "bookings": [
      {
        "jobNumber": "DTS12345",
        "testMode": false,
        "status": "allocated",
        "bookingType": "same_day",
        "service": "Standard",
        "readyAt": { "date": "2026-09-15", "time": "09:30", "timeZone": "Australia/Sydney" },
        "createdAt": "2026-09-14T06:05:12.412Z",
        "contact": "Jamie Citizen",
        "internalReference": "ORDER-5501",
        "internalReference2": "",
        "pickup": {
          "companyName": "Acme Freight",
          "address": "Unit 4/10 Example St, Silverwater NSW 2128, Australia",
          "suburb": "Silverwater",
          "reference": "PO-1001",
          "phone": "02 5550 1234",
          "instructions": "Loading dock at the rear.",
          "location": { "lat": -33.8352, "lng": 151.0473 }
        },
        "delivery": {
          "companyName": "Example Retail",
          "address": "25 Sample Rd, Botany NSW 2019, Australia",
          "suburb": "Botany",
          "reference": "INV-2002",
          "phone": "02 5550 5678",
          "instructions": "Deliver to goods inwards.",
          "location": { "lat": -33.9461, "lng": 151.1965 }
        },
        "items": [
          { "type": "Pallet", "quantity": 2, "weightKg": 180, "lengthCm": 120, "widthCm": 120, "heightCm": 110, "stackable": false },
          { "type": "Box", "quantity": 6, "weightKg": 12.5, "lengthCm": 40, "widthCm": 30, "heightCm": 30, "stackable": true }
        ],
        "jobCode": "1T",
        "vehicle": "1T",
        "tailgate": true,
        "hiab": false,
        "insurance": false,
        "distanceKm": 24.6,
        "price": { "currency": "AUD", "base": 95, "serviceCharge": 9.5, "tailgate": 35, "hiab": 0, "insurance": 0, "waitTime": 0, "tolls": 4.2, "totalExGst": 143.7, "gst": 13.95, "total": 157.65 }
      },
      {
        "jobNumber": "DTS23456",
        "testMode": false,
        "status": "pending",
        "bookingType": "same_day",
        "service": "Express",
        "readyAt": { "date": "2026-09-15", "time": "13:00", "timeZone": "Australia/Sydney" },
        "createdAt": "2026-09-15T01:47:09.120Z",
        "contact": "Jamie Citizen",
        "internalReference": "ORDER-5510",
        "internalReference2": "",
        "pickup": {
          "companyName": "Acme Freight",
          "address": "Unit 4/10 Example St, Silverwater NSW 2128, Australia",
          "suburb": "Silverwater",
          "reference": "",
          "phone": "02 5550 1234",
          "instructions": "",
          "location": { "lat": -33.8352, "lng": 151.0473 }
        },
        "delivery": {
          "companyName": "Sample Hardware",
          "address": "3 Trial Ln, Parramatta NSW 2150, Australia",
          "suburb": "Parramatta",
          "reference": "",
          "phone": "",
          "instructions": "",
          "location": { "lat": -33.815, "lng": 151.0011 }
        },
        "items": [
          { "type": "Box", "quantity": 2, "weightKg": 20, "lengthCm": 60, "widthCm": 40, "heightCm": 40, "stackable": false }
        ],
        "jobCode": "HT",
        "vehicle": "HT",
        "tailgate": false,
        "hiab": false,
        "insurance": false,
        "distanceKm": 9.8,
        "price": { "currency": "AUD", "base": 45, "serviceCharge": 4.5, "tailgate": 0, "hiab": 0, "insurance": 0, "waitTime": 0, "tolls": 0, "totalExGst": 49.5, "gst": 4.95, "total": 54.45 }
      }
    ],
    "nextCursor": "eyJmcm9tIjoiMjAyNi0wOS0xNSIsInRvIjoiMjAyNi0wOS0xNSIsImRheSI6IjIwMjYtMDktMTUiLCJhZnRlciI6IkRUUzIzNDU2In0"
  },
  "requestId": "req_0d2f4b6c8e0a4c2e6b8d0f2a4c6e8b0d"
}

curl https://portal.directtransport.com.au/api/v1/bookings/DTS12345 \
  -H "Authorization: Bearer $DTS_API_KEY"

const response = await fetch("https://portal.directtransport.com.au/api/v1/bookings/DTS12345", {
  headers: { Authorization: `Bearer ${process.env.DTS_API_KEY}` },
});
const { data: booking } = await response.json();
console.log(booking.status, booking.progress.pickedUpAt, booking.driver?.name);

import os
import requests

response = requests.get(
    "https://portal.directtransport.com.au/api/v1/bookings/DTS12345",
    headers={"Authorization": f"Bearer {os.environ['DTS_API_KEY']}"},
    timeout=30,
)
booking = response.json()["data"]
print(booking["status"], booking["progress"]["pickedUpAt"], (booking["driver"] or {}).get("name"))

{
  "data": {
    "jobNumber": "DTS12345",
    "testMode": false,
    "status": "picked_up",
    "bookingType": "same_day",
    "service": "Standard",
    "readyAt": { "date": "2026-09-15", "time": "09:30", "timeZone": "Australia/Sydney" },
    "createdAt": "2026-09-14T06:05:12.412Z",
    "contact": "Jamie Citizen",
    "internalReference": "ORDER-5501",
    "internalReference2": "",
    "pickup": {
      "companyName": "Acme Freight",
      "address": "Unit 4/10 Example St, Silverwater NSW 2128, Australia",
      "suburb": "Silverwater",
      "reference": "PO-1001",
      "phone": "02 5550 1234",
      "instructions": "Loading dock at the rear.",
      "location": { "lat": -33.8352, "lng": 151.0473 }
    },
    "delivery": {
      "companyName": "Example Retail",
      "address": "25 Sample Rd, Botany NSW 2019, Australia",
      "suburb": "Botany",
      "reference": "INV-2002",
      "phone": "02 5550 5678",
      "instructions": "Deliver to goods inwards.",
      "location": { "lat": -33.9461, "lng": 151.1965 }
    },
    "items": [
      { "type": "Pallet", "quantity": 2, "weightKg": 180, "lengthCm": 120, "widthCm": 120, "heightCm": 110, "stackable": false },
      { "type": "Box", "quantity": 6, "weightKg": 12.5, "lengthCm": 40, "widthCm": 30, "heightCm": 30, "stackable": true }
    ],
    "jobCode": "1T",
    "vehicle": "1T",
    "tailgate": true,
    "hiab": false,
    "insurance": false,
    "distanceKm": 24.6,
    "price": { "currency": "AUD", "base": 95, "serviceCharge": 9.5, "tailgate": 35, "hiab": 0, "insurance": 0, "waitTime": 0, "tolls": 4.2, "totalExGst": 143.7, "gst": 13.95, "total": 157.65 },
    "progress": {
      "bookedAt": "2026-09-14T06:05:12.412Z",
      "allocatedAt": "2026-09-14T22:41:03.000Z",
      "driverAcceptedAt": "2026-09-14T22:43:27.000Z",
      "pickedUpAt": "2026-09-14T23:36:50.000Z",
      "deliveredAt": null,
      "futileAt": null,
      "returnedAt": null,
      "cancelledAt": null
    },
    "driver": { "name": "Jordan Sample" },
    "proofOfDelivery": { "available": false }
  },
  "requestId": "req_e1c3a5b7d9f14e3a5c7b9d1f3a5c7e9b"
}

curl "https://portal.directtransport.com.au/api/v1/bookings/DTS12345/label?paper=A4" \
  -H "Authorization: Bearer $DTS_API_KEY" \
  -o DTS12345-label.pdf

import { writeFile } from "node:fs/promises";

const response = await fetch("https://portal.directtransport.com.au/api/v1/bookings/DTS12345/label?paper=A4", {
  headers: { Authorization: `Bearer ${process.env.DTS_API_KEY}` },
});
if (!response.ok) {
  const { error } = await response.json(); // errors are JSON
  throw new Error(`${error.code}: ${error.message}`);
}
await writeFile("DTS12345-label.pdf", Buffer.from(await response.arrayBuffer()));

import os
import requests

response = requests.get(
    "https://portal.directtransport.com.au/api/v1/bookings/DTS12345/label",
    headers={"Authorization": f"Bearer {os.environ['DTS_API_KEY']}"},
    params={"paper": "A4"},
    timeout=60,
)
if response.status_code != 200:
    error = response.json()["error"]  # errors are JSON
    raise SystemExit(f"{error['code']}: {error['message']}")
with open("DTS12345-label.pdf", "wb") as file:
    file.write(response.content)

HTTP/1.1 200 OK
Content-Type: application/pdf
Content-Disposition: inline; filename="DTS12345-label.pdf"
X-Request-Id: req_c3e5a7b9d1f34a5c7e9b1d3f5a7c9e1b
X-DTS-Mode: live
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 59
X-RateLimit-Reset: 22
Cache-Control: no-store

curl https://portal.directtransport.com.au/api/v1/bookings/DTS12345/invoice \
  -H "Authorization: Bearer $DTS_API_KEY" \
  -o DTS12345-invoice.pdf

import { writeFile } from "node:fs/promises";

const response = await fetch("https://portal.directtransport.com.au/api/v1/bookings/DTS12345/invoice", {
  headers: { Authorization: `Bearer ${process.env.DTS_API_KEY}` },
});
if (!response.ok) {
  const { error } = await response.json(); // errors are JSON
  throw new Error(`${error.code}: ${error.message}`);
}
await writeFile("DTS12345-invoice.pdf", Buffer.from(await response.arrayBuffer()));

import os
import requests

response = requests.get(
    "https://portal.directtransport.com.au/api/v1/bookings/DTS12345/invoice",
    headers={"Authorization": f"Bearer {os.environ['DTS_API_KEY']}"},
    timeout=60,
)
if response.status_code != 200:
    error = response.json()["error"]  # errors are JSON
    raise SystemExit(f"{error['code']}: {error['message']}")
with open("DTS12345-invoice.pdf", "wb") as file:
    file.write(response.content)

HTTP/1.1 200 OK
Content-Type: application/pdf
Content-Disposition: inline; filename="DTS12345-invoice.pdf"
X-Request-Id: req_d4f6b8c0e2a44b6d8f0c2e4a6b8d0f2c
X-DTS-Mode: live
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 58
X-RateLimit-Reset: 21
Cache-Control: no-store

curl https://portal.directtransport.com.au/api/v1/bookings/DTS12345/pod \
  -H "Authorization: Bearer $DTS_API_KEY"

const response = await fetch("https://portal.directtransport.com.au/api/v1/bookings/DTS12345/pod", {
  headers: { Authorization: `Bearer ${process.env.DTS_API_KEY}` },
});
const { data: pod } = await response.json();
if (pod.available) console.log(pod.receiverName, pod.deliveredAt, pod.podPdfUrl);

import os
import requests

response = requests.get(
    "https://portal.directtransport.com.au/api/v1/bookings/DTS12345/pod",
    headers={"Authorization": f"Bearer {os.environ['DTS_API_KEY']}"},
    timeout=30,
)
pod = response.json()["data"]
if pod["available"]:
    print(pod["receiverName"], pod["deliveredAt"], pod["podPdfUrl"])

{
  "data": {
    "jobNumber": "DTS12345",
    "status": "delivered",
    "available": true,
    "deliveredAt": "2026-09-15T00:18:44.000Z",
    "receiverName": "Sam Receiver",
    "signatureUrl": "https://files.example.com/pod/DTS12345/signature.png",
    "deliveryPhotos": [
      "https://files.example.com/pod/DTS12345/delivery-1.jpg"
    ],
    "pickupPhotos": [
      "https://files.example.com/pod/DTS12345/pickup-1.jpg"
    ],
    "pickupDocuments": [
      { "url": "https://files.example.com/pod/DTS12345/consignment-note.pdf", "fileName": "consignment-note.pdf" }
    ],
    "podPdfUrl": "https://files.example.com/pod/DTS12345/pod.pdf"
  },
  "requestId": "req_b2d4f6a8c0e24b6d8f0a2c4e6b8d0f2a"
}

Items, services and timing rules

These rules apply to both POST /quotes and POST /bookings, and match Place the Booking on the portal. Times are in the region's time zone.

Item types and measurements

items[].type must be one of these, spelt exactly as shown (note Aluminum):

• Aluminum
• Bags
• Box
• Coil
• Conduit
• Crate
• Drum
• Envelope
• Hoses
• Ladder
• Pail
• Pallet
• Pipes
• Rack
• Rolls
• Satchel
• Skid
• Steel
• Timber
• Tubes
• Tyres

Measurements are for one item, and quantity says how many there are. Weights and measurements can have decimals, such as 12.5.

Set stackable to true for items that can be stacked on top of each other, so the job can be priced with them stacked. Only Ladder, Box and Crate items can be stackable; on any other type, "stackable": true is refused with Only Ladder, Box, Crate items can be stacked.

Tailgate, HIAB and insurance

• Each one is false unless you send true.
• tailgate and hiab can't both be true (Choose Tailgate or HIAB, not both.).
• DTS can make any of them unavailable for a time. Asking for one that isn't available gets service_not_available (422), with details naming the field.
• insurance is for metro Same Day jobs. For regional and country jobs (Next Day, 3-4 Day, or Same Day with either address outside the metro area), asking for it gets service_not_available (422) with Freight insurance isn't available for regional and country jobs.

Job codes

Accounts with job codes turned on can price by job code instead of listing items: send jobCode and leave items out.

• Job codes: LD, Courier, HT, 1T, 2T, 4T, 6T, 8T, 10T, 12T, 14T and 16T.
• LD is only for same_day jobs (LD is only for same_day jobs.).
• Send one of items and jobCode. Sending neither gets Send items (what is being sent), or a jobCode. and sending both gets Send either items or a jobCode, not both.
• If job codes aren't turned on for your account, jobCode gets feature_not_enabled (403): Job codes aren't enabled for this account. Send items instead. Ask DTS if you need them.
• A booking made by job code has an empty items list.

Services by booking type

Asking for a service the booking type doesn't offer gets invalid_request, for example Express isn't offered for next_day jobs. Offered: Standard.

A same_day job is metro when both addresses are inside the metro service area, and regional and country otherwise. Every next_day and three_four_day job counts as regional and country. Quotes show this in serviceArea and in each address's insideMetroArea. Next Day and 3-4 Day jobs within the metro area can't be priced online (cannot_price_online). If regional and country jobs can't be booked online in the region at the moment, quotes and bookings for them get regional_not_available (422).

Service hours (metro Same Day)

A metro Same Day job must be ready within its service's hours:

The times shown are included, so a Standard job ready at 3:00 PM can be booked. After Hours is the other way round: a ready time of exactly 7:00 AM or 5:00 PM isn't After Hours. A ready time up to 5 minutes ago is checked as the current time (see ready date and time).

Outside these hours the option's reason is outside_service_hours, with a message such as Standard jobs ready today need a ready time between 7:00 AM and 3:00 PM. or Express jobs need a ready time no later than 4:00 PM. These hours are only for metro Same Day jobs; regional and country jobs follow the cutoffs below.

Regional and country cutoffs

Regional and country jobs have no ready-time hours, but a job that's ready today has to be booked by a cutoff. The cutoff is checked against the time you quote or book.

After a cutoff the option's reason is booking_cutoff_passed, with a message such as Regional and country Standard jobs ready today must be booked by 12:00 PM. or 3-4 Day jobs ready today must be booked by 5:00 PM.

Ready date and time

• readyAt has a date (YYYY-MM-DD) and a time (HH:mm, 24-hour) in the region's time zone.
• Bookings must send it (Send readyAt: the date and time the job will be ready.). Quotes can leave it out: the job is then priced for now, and the quote's readyAt shows the current date and time in the region.
• It must be a real date and time (readyAt isn't a real date and time.).
• The date must be today or later (The ready date is in the past.) and at most 90 days ahead (The ready date can be at most 90 days ahead.).
• The time must not have passed. A time up to 5 minutes ago is accepted, to allow for clocks that differ, and counts as now: the quote's readyAt shows the current time, service hours and cutoffs are checked at the current time, and a booking is saved with it. For example, a metro Standard job for 15:00 today, sent at 15:03, is checked at 15:03. That's after Standard's hours, so it can't be booked.
• A time more than 5 minutes ago is refused with a message such as The ready time has passed: it is 10:42 on 2026-09-15 in Australia/Sydney. Send a ready time from now on.
• These are invalid_request (400) errors, with details naming readyAt, readyAt.date or readyAt.time.

Addresses

• Send a full street address in Australia, as you would type it on the portal: number, street, suburb, state and postcode. Addresses are only looked up in Australia.
• Responses give each address as it was found, for example 25 Sample Rd, Botany NSW 2019, Australia.
• precision is exact when the address was found precisely enough to send a driver to (such as a street address, building or business), and approximate when it was only found roughly, such as just a street or a suburb.
• A job can only be booked when both addresses are exact. If either is approximate, a quote still prices the job, but every option that was priced has "bookable": false with the reason address_not_precise, and a booking is refused with the address_not_precise error (422). The message names the address, for example: The delivery address was found as "Botany NSW 2019, Australia", which isn't precise enough to send a driver to. Send a full street address, or its location as well.
• If you know the exact point, send it as location with lat and lng. The address text is still looked up and must be found; the point you send is then used for pricing and saved with the booking, and the address counts as exact.
• An address that can't be found gets address_not_found (422), with a message such as We couldn't find the pickup address. Check the street address, suburb and postcode. Correct the address and send the request again. details names the field, for example { "field": "pickup.address", "message": "Address not found." }.
• If there's no driving route between the addresses, the answer is no_route (422).

A booking with an address that was only found approximately:

{
  "error": {
    "code": "address_not_precise",
    "message": "The delivery address was found as \"Botany NSW 2019, Australia\", which isn't precise enough to send a driver to. Send a full street address, or its location as well.",
    "details": [
      { "field": "delivery.address", "message": "Not precise enough to send a driver to." }
    ]
  },
  "requestId": "req_9e1b3d5f7a9c4e1b3d5f7a9c1e3b5d7f"
}

Account-required fields

DTS can set your account to require some booking details, as the portal does. POST /bookings then refuses a booking that leaves a required field out or blank, with invalid_request (400). Quotes don't check these fields.

{
  "error": {
    "code": "invalid_request",
    "message": "This account requires a pickup reference, a delivery phone number.",
    "details": [
      { "field": "pickup.reference", "message": "Required for this account." },
      { "field": "delivery.phone", "message": "Required for this account." }
    ]
  },
  "requestId": "req_f5a7c9e1b3d54f7a9c1e3b5d7f9a1c3e"
}

The API doesn't say which fields your account requires. Ask DTS, or check the booking form on the portal.

Statuses and progress

• A job usually goes pending, allocated, picked_up, delivered.
• A job taken off its driver goes back to pending, and its allocatedAt and driverAcceptedAt go back to null.
• Some older bookings carry other status values, written in lower case with underscores. Treat a status you don't recognise as not finished.

GET /bookings/{jobNumber} shows when each step happened in progress: bookedAt, allocatedAt, driverAcceptedAt, pickedUpAt, deliveredAt, futileAt, returnedAt and cancelledAt, as ISO 8601 times in UTC. A step that hasn't happened, or was recorded without a time, is null, so decide where a job is up to from status, not from progress.

Check jobs that aren't finished every few minutes, and use GET /bookings?date=… to check many jobs in one request. Test bookings move on by themselves; see test mode.

Proof of delivery

• Proof of delivery is turned on for each account by DTS. Email IT@directtransport.com.au if you need it. Without it, GET /bookings/{jobNumber}/pod gets feature_not_enabled (403).
• proofOfDelivery.available in GET /bookings/{jobNumber} shows whether there's proof of delivery yet, whether or not it's turned on for your account.
• Proof of delivery is available once there's a receiver's name, a signature, delivery photos or a POD PDF. These can arrive at different times, so if you need a particular one, such as podPdfUrl, check again later.
• The response has the receiver's name, when it was delivered, and links to the signature, photos from pickup and delivery, documents from pickup and the POD PDF.
• For a test booking, proof of delivery becomes available when its simulated delivery happens, with receiverName Test Receiver and no signature, photos, documents or PDF.

Documents

Every booking the key can see, including test bookings, has two PDFs:

• the shipping label: GET /bookings/{jobNumber}/label?paper=…, one page;
• the tax invoice: GET /bookings/{jobNumber}/invoice.

Label sizes

The label's text is made smaller to fit the page. If a booking has more items than fit even then, the label lists as many as fit and ends the list with "+N more items".

• Both documents are drawn from the booking as it is now, so download them again after a change, such as waiting time added to the invoice.
• They come back with Content-Type: application/pdf and Content-Disposition: inline, with a file name such as DTS12345-label.pdf or DTS12345-invoice.pdf.
• Each PDF counts as one document towards documentsPerDay: 2,000 a day for live keys and 500 for test keys.

Test mode

Test keys (dts_test_) let you build and try your integration with real prices, without booking real jobs. Use the same base URL as for live keys; only the key changes when you go live.

• Quotes are priced exactly as with a live key, with real address lookups and your account's prices.
• POST /bookings checks everything a live booking checks, then saves a test booking: its job number is TEST- followed by a DTS number (for example TEST-DTS12345) and testMode is true. No driver is sent and no email goes to DTS.
• Test keys only see test bookings, and live keys only see live bookings. A job number from the other mode gets not_found.
• Labels and invoices can be downloaded for test bookings. Proof of delivery is simulated (it still needs proof of delivery turned on for your account).
• Validation, errors, idempotency and the per-minute limit work as they do for live keys. Daily limits are lower; see daily limits.

Simulated progress

A test booking moves on by itself, counted from when it was booked (createdAt). GET /bookings and GET /bookings/{jobNumber} show the simulated status.

futileAt, returnedAt and cancelledAt stay null. These are the progress fields of a test booking 20 minutes after it was booked:

{
  "jobNumber": "TEST-DTS12345",
  "testMode": true,
  "status": "picked_up",
  "createdAt": "2026-09-14T06:20:31.907Z",
  "progress": {
    "bookedAt": "2026-09-14T06:20:31.907Z",
    "allocatedAt": "2026-09-14T06:25:31.907Z",
    "driverAcceptedAt": "2026-09-14T06:25:31.907Z",
    "pickedUpAt": "2026-09-14T06:35:31.907Z",
    "deliveredAt": null,
    "futileAt": null,
    "returnedAt": null,
    "cancelledAt": null
  },
  "driver": { "name": "Test Driver" },
  "proofOfDelivery": { "available": false }
}

Limits and usage

Each key has a per-minute limit and daily limits. GET /account shows the limits for your key in limits and what it has used today in usageToday. If you need more, email IT@directtransport.com.au: DTS can raise limits for your key.

Per minute

• A key can make 60 requests a minute (requestsPerMinute), live or test. The count starts again at the start of each minute.
• Once the key is accepted, every response has X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (the seconds until the minute ends).
• A request over the limit gets rate_limited (429) with a Retry-After header: the number of seconds until the next minute. Wait that long before trying again.
• Requests that are turned away still count towards that minute, so retrying straight away doesn't help. They also count towards rateLimitedPerDay: more than 1,000 in a day pauses the key.

HTTP/1.1 429 Too Many Requests
Content-Type: application/json
Retry-After: 17
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 17
X-Request-Id: req_a9c1e3b5d7f94a1c3e5b7d9f1a3c5e7b
X-DTS-Mode: live
Cache-Control: no-store

{
  "error": {
    "code": "rate_limited",
    "message": "Too many requests this minute. Wait until the time in Retry-After, then try again."
  },
  "requestId": "req_a9c1e3b5d7f94a1c3e5b7d9f1a3c5e7b"
}

Daily limits

Days run from midnight to midnight in the region's time zone. The names are the fields in limits; the matching counts in usageToday drop PerDay (for example priceChecks).

When a daily limit is reached

{
  "error": {
    "code": "daily_limit_reached",
    "message": "This request would go over a daily usage limit, so the key has been paused. Contact IT@directtransport.com.au.",
    "details": { "counter": "priceChecks", "limit": 2000 }
  },
  "requestId": "req_c7e9b1d3f5a74c9e1b3d5f7a9c1e3b5d"
}

Staying within your limits

• After a 429, wait for Retry-After. Spread large batches of work out over time.
• Don't price the same job again and again: each quote uses a price check and 3 Google Maps calls, and so does each booking.
• Check unfinished jobs every few minutes, not every few seconds, and check many at once with GET /bookings?date=….
• Download labels and invoices when you need them, not on every check.
• Keep an eye on usageToday in GET /account.

Idempotency

POST /bookings needs an Idempotency-Key header. It makes retrying safe: if a request times out or the connection drops, send it again with the same key, and the job can't be booked twice.

• The value is 1 to 255 visible characters with no spaces. A UUID, such as 0b8f3c52-6d1e-4a7b-9c2d-5e8f1a3b7c64, is ideal.
• Use a new value for each new booking, and send the same value with every attempt at that booking until it's made: a retry after a timeout or network error, or the booking sent again after a refusal.
• Once a booking is made, its value is remembered for 24 hours, separately for each API key.

Which answers are kept

• Kept and repeated for 24 hours: only a booking that was made (201).
• Not kept: every refusal and error, including price_changed (409), service_not_available, address_not_precise, address_not_found and cannot_price_online (422), a ready time that has passed (400), daily_limit_reached (403) and server errors (500 and 503). Nothing was booked, and the key can be used again straight away.

Pagination

GET /bookings returns bookings a page at a time.

1. Ask for the first page with date, or from and to, and limit if you want a page size other than 25 (up to 100).
2. If nextCursor isn't null, ask for the next page with cursor set to it. You can leave out date, from and to, or send the same ones again; limit can change.
3. Stop when nextCursor is null. The last page can be empty.

• Use cursors as they are; don't build or change them. A cursor that has been changed gets invalid_request: cursor isn't valid. Use nextCursor from the previous page.
• A list isn't a snapshot. Bookings made or changed while you page through can be missed or can show up.

async function listBookings(from, to) {
  const bookings = [];
  let cursor = null;
  do {
    const params = new URLSearchParams({ from, to, limit: "100" });
    if (cursor) params.set("cursor", cursor);
    const response = await fetch(`https://portal.directtransport.com.au/api/v1/bookings?${params}`, {
      headers: { Authorization: `Bearer ${process.env.DTS_API_KEY}` },
    });
    const body = await response.json();
    if (!response.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
    bookings.push(...body.data.bookings);
    cursor = body.data.nextCursor;
  } while (cursor);
  return bookings;
}

const september = await listBookings("2026-09-01", "2026-09-30");

import os
import requests


def list_bookings(date_from, date_to):
    bookings, cursor = [], None
    while True:
        params = {"from": date_from, "to": date_to, "limit": 100}
        if cursor:
            params["cursor"] = cursor
        response = requests.get(
            "https://portal.directtransport.com.au/api/v1/bookings",
            headers={"Authorization": f"Bearer {os.environ['DTS_API_KEY']}"},
            params=params,
            timeout=30,
        )
        body = response.json()
        if response.status_code != 200:
            raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
        bookings.extend(body["data"]["bookings"])
        cursor = body["data"]["nextCursor"]
        if not cursor:
            return bookings


september = list_bookings("2026-09-01", "2026-09-30")

Errors

Every error has the same format. Build your handling on code; message is for people and can change.

When to retry

Changelog

Support

Email IT@directtransport.com.au to:

• get a live or test key;
• raise your limits;
• have a paused key allowed again;
• revoke a key that may have been exposed;
• turn on proof of delivery or job codes for your account;
• ask anything about the API.

For custom quotes, contact the DTS bookings team at bookings@directtransport.com.au, the contactEmail the API gives.

When you write about a request, include:

• the region;
• the key's prefix, such as dts_live_Ab12Cd (never the whole key);
• the requestId (or X-Request-Id), the endpoint and the time;
• the error code and message.