Skip to content

Booking checks

Transdirect reads each booking’s goods_description against the courier you chose. Some goods need a question answered (is any of it liquid?), some need a change (a courier that needs liquids in a liquids carton), and a few can’t go with that courier at all. The same checks run on Transdirect’s own booking pages.

Once a booking has a courier, these responses carry a checks object:

  • Get a booking (GET /api/v5/bookings/{id})
  • Update a booking
  • Confirm with Prefer: return=representation
  • GET /api/v5/bookings/{id}/checks, which also takes ?courier= to see the checks for a courier before you choose it
{
"state": "open",
"courier": "hunter_express",
"items": [
{
"id": "liquid",
"kind": "question",
"fact": "liquid",
"question": "Is any of it liquid?",
"options": [
{ "value": "alcohol", "label": "Yes, alcohol" },
{ "value": "other", "label": "Yes, another liquid" },
{ "value": "no", "label": "No" }
],
"which_items": true,
"required": false,
"blocking": false
}
],
"answered": {},
"photo_wanted": false
}
stateMeaning
noneNothing to ask.
openSomething in items to answer or fix.
answeredEverything asked is answered.
heldPaid, and held for a review of its description. Answer the open items to help it through.
clearedPaid, answered and not held.

Each item is one of:

  • question: answer it with one of its options[].value. When which_items is true you can also say which item lines it applies to, by booking item id.
  • fix: what the courier needs. action says what: change_packaging (set the item description to the packaging_type carton), another_courier, road_service, palletise, carton_not_satchel, crate, box_it, rewrite (describe the goods more exactly) or acknowledge. Make the fix by changing the items or the courier. Only an acknowledge fix is answered, with acknowledged: true.
  • cant_send: this courier can’t take these goods. Choose another courier from the quote.

required means the booking is held for review after payment if the item is left open. blocking means confirm is refused while it stands. Only cant_send items block.

Answer inline with answers on create, update or confirm, keyed by item id:

{
"answers": {
"liquid": { "value": "other", "items": [48211] },
"fix:fridge-upright": true
}
}

Or answer one at a time:

Terminal window
curl -X POST "https://api.transdirect.com.au/api/v5/bookings/123456/checks/liquid/answer" \
-H "api-key: $TD_API_KEY" -H "Content-Type: application/json" \
-d '{"value":"no"}'

The response is {"booking_id":123456,"checks":{...}} with the updated checks. Sending the same answer again changes nothing; a different value replaces it. Unknown ids return 404 check_not_found, and a value that isn’t one of the options returns 422 invalid_answer.

A question you leave unanswered never fails a request. It behaves as it does on Transdirect’s booking pages: a booking with an open required item may be held for review after payment. Answers on a held booking go to that review.

When photo_wanted is true, a photo of the packed goods helps Transdirect’s team check the booking. Send up to 5 per booking, before or after payment:

Terminal window
curl -X POST "https://api.transdirect.com.au/api/v5/bookings/123456/checks/photo" \
-H "api-key: $TD_API_KEY" -F "photo=@packed.jpg"

Send multipart field photo, or JSON {"image":"data:image/jpeg;base64,..."}. JPEG or PNG, up to 8 MB. The response is 201 with photo_id, photos and max_photos. Photos are re-encoded without their location data and kept for the same period as the booking’s checks.

StatuserrorCause
409booking_not_openThe booking is paid and not held.
409too_many_photosThe booking has 5 photos already.
413too_largeOver 8 MB.
422photo_rejectedNot a JPEG or PNG.

Once refusals are on for your account, confirming a booking whose courier can’t take the goods returns 422 before anything is charged:

{
"error": "cant_send",
"code": "CANT_SEND",
"message": "Hunter Express and TGE don't take liquids, alcohol included, in cartons or on pallets: choose another courier",
"courier": "hunter_express",
"checks": { "state": "open", "courier": "hunter_express", "items": [ ... ] }
}

Choose another courier from the quote and confirm again. Questions and fixes never cause a refusal.