Get a booking

Endpoint

GET /api/bookings/v4/{id}

Returns the full details of a single booking, including sender and receiver information, items, quotes (while still a quote), selected courier, and current status.

Authentication

Path parameters

Parameter	Type	Required	Description
`id`	integer	Yes	The unique booking ID.

Example request

curl -X GET \
  -H "Api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  https://www.transdirect.com.au/api/bookings/v4/12345678

Example response (confirmed booking)

{
  "id": 12345678,
  "status": "Confirmed",
  "booked_at": "2025-08-15T10:30:00+0000",
  "booked_by": "sender",
  "created_at": "2025-08-15T10:30:00+0000",
  "updated_at": "2025-08-15T10:35:00+0000",
  "declared_value": 1000,
  "insured_value": 1000,
  "description": null,
  "tailgate_pickup": false,
  "tailgate_delivery": false,
  "courier": "allied",
  "connote": "ALD123456789",
  "charged_weight": 5,
  "scanned_weight": 5,
  "special_instructions": "Leave at front door",
  "pickup_instructions": null,
  "pickup_window": [
    "2025-08-18T14:00:00+1000",
    "2025-08-18T18:00:00+1000"
  ],
  "label": "http://www.transdirect.com.au/api/bookings/12345678/label",
  "notifications": {
    "email": false,
    "sms": false
  },
  "cost": 79.24,
  "additional_charges": 0,
  "sender": {
    "name": "John Smith",
    "company_name": "Example Pty Ltd",
    "email": "john@example.com",
    "phone": "0400000000",
    "address": "123 George Street",
    "postcode": "2000",
    "suburb": "SYDNEY",
    "state": "NSW",
    "type": "business",
    "country": "AU"
  },
  "receiver": {
    "name": "Jane Doe",
    "company_name": "Receiver Co",
    "email": "jane@example.com",
    "phone": "0400000001",
    "address": "456 Collins Street",
    "postcode": "3000",
    "suburb": "MELBOURNE",
    "state": "VIC",
    "type": "business",
    "country": "AU"
  },
  "items": [
    {
      "weight": 5,
      "height": 25,
      "width": 35,
      "length": 40,
      "quantity": 1,
      "description": "carton"
    }
  ]
}

Example response (quote / status `new`)

While the booking is still a quote, the body includes a quotes object (and usually quote_errors) and does not include cost / additional_charges / courier yet:

{
  "id": 12345678,
  "status": "new",
  "quotes": {
    "allied": {
      "total": 79.24,
      "price_insurance_ex": 72.09,
      "fee": 7.15,
      "insured_amount": 4500,
      "service": "road",
      "transit_time": "1-2 days",
      "pickup_dates": ["2025-08-18", "2025-08-19"],
      "pickup_time": { "from": "14:00", "to": "18:00" }
    }
  },
  "quote_errors": [],
  "sender": { "postcode": "2000", "suburb": "SYDNEY", "type": "business", "country": "AU" },
  "receiver": { "postcode": "3000", "suburb": "MELBOURNE", "type": "business", "country": "AU" },
  "items": [
    { "weight": 5, "height": 25, "width": 35, "length": 40, "quantity": 1, "description": "carton" }
  ]
}

Response fields

Field	Type	Description
`id`	integer	Unique booking identifier.
`status`	string	Current booking status. See statuses.
`booked_at`	string	Date and time the booking was placed (ISO 8601).
`booked_by`	string	Who placed the booking. Defaults to `"sender"`.
`created_at`	string	Date and time the booking record was created (ISO 8601).
`updated_at`	string	Date and time the booking was last updated (ISO 8601).
`declared_value`	number	Declared value of the goods (AUD).
`insured_value`	number	Final insured amount once a courier has been selected. `0` until confirmation. See warranty and insurance.
`description`	string \| null	Free-text goods description, if provided.
`tailgate_pickup`	boolean	Whether tailgate is required at pickup.
`tailgate_delivery`	boolean	Whether tailgate is required at delivery.
`courier`	string	Selected courier string_id. Present after confirmation (and on v5 sometimes earlier once selected).
`connote`	string \| null	Courier consignment note number. Populated once the courier has confirmed.
`charged_weight`	number	Weight the courier billed against (after re-weigh, if applicable). `0` until set by the courier.
`scanned_weight`	number	Weight scanned by the courier at pickup. `0` until set by the courier.
`special_instructions`	string	Special handling instructions. Multiple instructions are returned semicolon-joined.
`pickup_instructions`	string \| null	Pickup-specific instructions.
`pickup_window`	array	Two ISO 8601 strings (`[from, to]`) bounding the pickup window. Empty array `[]` before pickup is set.
`label`	string	URL to fetch the PDF label. See get a label.
`notifications`	object	Notification toggles. Always returns `{"email": false, "sms": false}` — this field is a stub and does not reflect member notification preferences.
`sender`	object	Full sender details.
`receiver`	object	Full receiver details.
`items`	array	Array of item objects.
`quotes`	object	Courier quotes keyed by courier string_id. Only present when the booking is still a quote (`status` is `new` on v4). Once confirmed, `quotes` is omitted and replaced by `cost` and `additional_charges`.
`quote_errors`	array	Couriers that could not provide a quote, e.g. `[{"courier": "direct_couriers_express", "code": "no_service"}, ...]`.
`cost`	number	Final booking cost. Present once the booking is no longer a bare quote.
`additional_charges`	number	Post-booking adjustments total. Present once the booking is no longer a bare quote.
`order`	object	Optional linked e-commerce order: `{ order_id, order_number }`.
`collection_point`	object	Optional PUDO / collection-point details when set.

Sender / Receiver object

Field	Type	Description
`name`	string	Contact name.
`company_name`	string	Company or business name.
`email`	string	Contact email address.
`phone`	string	Contact phone number.
`address`	string	Street address.
`postcode`	string	Postcode.
`suburb`	string	Suburb name.
`state`	string	State or territory abbreviation (e.g. `"NSW"`, `"VIC"`).
`type`	string	Address type: `"business"` or `"residential"`.
`country`	string	ISO 3166-1 alpha-2 country code.

Booking statuses

The database stores machine codes (e.g. confirmed). The GET response often returns the human label for non-quote bookings (e.g. "Confirmed"). The labels come from a fixed lookup table, not from mechanical title-casing — note On hold and Sending to Courier — and the mapping is not reversible: both pending_review and on_hold_suspicious return Pending Review. Treat matching as case-insensitive, or accept both forms.

Machine code	Typical label	Description
`new`	`new` (v4 quote) / `New` (v5)	Quote created; pricing returned.
`pending_payment`	Pending Payment	Courier selected; awaiting payment.
`paid`	Paid	Payment processed; ready to send to the courier.
`pending_review`	Pending Review	Flagged for manual review.
`under_review`	Under Review	Under review by Transdirect.
`request_sent`	Request Sent	Submitted to the courier.
`request_failed`	Request Failed	Courier could not process the booking.
`reviewed`	Reviewed	Passed review; being processed.
`sending_to_courier`	Sending to Courier	Actively being sent to the courier.
`confirmed`	Confirmed	Courier confirmed; connote generated.
`cancelled`	Cancelled	Cancelled.
`cancelled_refund`	Cancel Refund	Cancelled with refund.
`booked_manually`	Booked Manually	Processed manually by Transdirect.
`on_hold`	On hold	On hold.
`on_hold_suspicious`	Pending Review	Fraud / suspicion hold.
`from_on_hold`	`from_on_hold`	Released from an on-hold state. Deliberately unlabelled — the raw code is returned as-is.
`labels_failed`	Labels Failed	Label generation failed.
`demo`	Demo	Legacy sandbox status. Bookings made with `payment_method: "demo"` do not get this status — they follow the normal lifecycle.
`multipickup_unpaid`	Multipickup Unpaid	Multipickup booking awaiting payment.

For more detail on how statuses progress, see booking lifecycle.

Error responses

Status code	Description
`401`	Unauthorised — invalid or missing credentials.
`403` / `404`	Not found — no booking exists with the given ID, or it belongs to another member.