Get a booking

Endpoint

GET /api/bookings/v4/{id}

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

Authentication

Note

Requires authentication via API key or basic auth.

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

{
  "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
  },
  "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"
    }
  ],
  "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"
      }
    }
  }
}

Response fields

Field	Type	Description
id	integer	Unique booking identifier.
status	string	Current booking status. See statuses below.
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 identifier. Present after confirmation.
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 identifier. Only present when status is new — 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 status is not new.
additional_charges	array	Any post-booking adjustments. Present once status is not new.

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

A booking progresses through the following statuses during its lifecycle:

Status	Description
new	Quote has been created with basic details. Pricing has been returned.
pending_payment	A courier has been selected. Awaiting payment.
paid	Payment has been processed. The booking is ready to be sent to the courier.
pending_review	The booking has been flagged for manual review by the Transdirect team.
request_sent	The booking has been submitted to the courier for confirmation.
request_failed	The courier was unable to process the booking. Contact support.
reviewed	The booking has passed manual review and is being processed.
confirmed	The courier has confirmed the booking. A connote has been generated.
cancelled	The booking has been cancelled.
booked_manually	The booking was processed manually by the Transdirect team.
demo	A test booking created while your account is in demo mode. Not sent to any courier.

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

Error responses

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