Track a public shipment reference

GET

/api/v5/bookings/v4/trackstatus/{reference}

• Production

Returns normalised tracking status and event history for a booking ID, consignment number or courier tracking reference. Public — no API key required. Falls back to the legacy tracking service when native tracking finds no match; returns 404 when nothing matches and 502 when the legacy service is unavailable.

Parameters

Path Parameters

reference

required

Booking ID, consignment number or courier tracking reference.

string

>= 3 characters <= 80 characters /^[A-Za-z0-9_-]+$/

Example

IRE032323149

Booking ID, consignment number or courier tracking reference.

Responses

200

Normalized public tracking response

object

reference

required

Tracking reference that was looked up (booking ID or connote).

string

matched

required

Whether the reference matched a known booking or consignment.

boolean

bookingId

required

Matched Transdirect booking ID; null when no match.

string

nullable

connote

required

Carrier consignment note number; null when unavailable.

string

nullable

deliveryStatus

required

Numeric internal delivery-status code; null when unavailable.

number

nullable

statusPhrase

required

Short human-readable status phrase for the shipment.

string

state

required

Overall tracking state (e.g. in_transit, delivered, not_found).

string

Allowed values: not_found pending picked_up in_transit out_for_delivery delivered attention

headline

required

Headline summary line to show to the recipient.

string

summary

required

Longer summary describing the current tracking situation.

string

helpRecommended

required

Whether the recipient should be prompted to contact support.

boolean

attachmentRecommended

required

Whether the recipient should be prompted to attach supporting evidence.

boolean

checkedAt

required

ISO 8601 timestamp when tracking was last checked.

string

items

required

Per-item tracking details for the shipment.

Array<object>

object

label

required

Display label identifying this parcel or consignment item.

string

eta

required

Estimated delivery date/time; null when unknown.

string

nullable

stage

required

Current normalised delivery stage of this item.

string

Allowed values: pending picked_up in_transit out_for_delivery delivered exception unknown

stageCode

required

Numeric code for the current stage; null when unavailable.

number

nullable

trackingGraphicUrl

required

URL of a progress-bar graphic for the item; null when unavailable.

string

nullable

events

required

Chronological tracking events recorded for this item.

Array<object>

object

occurredAt

required

ISO 8601 timestamp the event occurred; null when unknown.

string

nullable

dateText

required

Human-readable date/time label for display; null when unavailable.

string

nullable

stage

required

Normalised delivery stage for this event (e.g. in_transit, delivered).

string

Allowed values: pending picked_up in_transit out_for_delivery delivered exception unknown

status

required

Normalised status label for the event; null when unavailable.

string

nullable

description

required

Human-readable description of the event; null when unavailable.

string

nullable

location

required

Location where the event occurred; null when unavailable.

string

nullable

podUrl

required

URL of the proof-of-delivery document; null when not available.

string

nullable

deliveryDateText

required

Human-readable delivery date label; null when not delivered.

string

nullable

raw

required

Original unprocessed event payload from the carrier.

object

date

Raw event date as supplied by the carrier.

string

datetime

Raw combined date-time string as supplied by the carrier.

string

time

Raw event time as supplied by the carrier.

string

occurred_at

Raw timestamp the event occurred, as supplied by the carrier.

string

status

Raw status code or label from the carrier.

string

description

Raw event description from the carrier.

string

details

Additional raw event detail text from the carrier.

string

event

Raw event name or type from the carrier.

string

milestone

Raw milestone identifier from the carrier.

string

location

Raw location text from the carrier.

string

depot

Raw depot name from the carrier.

string

branch

Raw branch name from the carrier.

string

404

No booking matched the supplied reference

object

reference

required

Tracking reference that was looked up (booking ID or connote).

string

matched

required

Whether the reference matched a known booking or consignment.

boolean

bookingId

required

Matched Transdirect booking ID; null when no match.

string

nullable

connote

required

Carrier consignment note number; null when unavailable.

string

nullable

deliveryStatus

required

Numeric internal delivery-status code; null when unavailable.

number

nullable

statusPhrase

required

Short human-readable status phrase for the shipment.

string

state

required

Overall tracking state (e.g. in_transit, delivered, not_found).

string

Allowed values: not_found pending picked_up in_transit out_for_delivery delivered attention

headline

required

Headline summary line to show to the recipient.

string

summary

required

Longer summary describing the current tracking situation.

string

helpRecommended

required

Whether the recipient should be prompted to contact support.

boolean

attachmentRecommended

required

Whether the recipient should be prompted to attach supporting evidence.

boolean

checkedAt

required

ISO 8601 timestamp when tracking was last checked.

string

items

required

Per-item tracking details for the shipment.

Array<object>

object

label

required

Display label identifying this parcel or consignment item.

string

eta

required

Estimated delivery date/time; null when unknown.

string

nullable

stage

required

Current normalised delivery stage of this item.

string

Allowed values: pending picked_up in_transit out_for_delivery delivered exception unknown

stageCode

required

Numeric code for the current stage; null when unavailable.

number

nullable

trackingGraphicUrl

required

URL of a progress-bar graphic for the item; null when unavailable.

string

nullable

events

required

Chronological tracking events recorded for this item.

Array<object>

object

occurredAt

required

ISO 8601 timestamp the event occurred; null when unknown.

string

nullable

dateText

required

Human-readable date/time label for display; null when unavailable.

string

nullable

stage

required

Normalised delivery stage for this event (e.g. in_transit, delivered).

string

Allowed values: pending picked_up in_transit out_for_delivery delivered exception unknown

status

required

Normalised status label for the event; null when unavailable.

string

nullable

description

required

Human-readable description of the event; null when unavailable.

string

nullable

location

required

Location where the event occurred; null when unavailable.

string

nullable

podUrl

required

URL of the proof-of-delivery document; null when not available.

string

nullable

deliveryDateText

required

Human-readable delivery date label; null when not delivered.

string

nullable

raw

required

Original unprocessed event payload from the carrier.

object

date

Raw event date as supplied by the carrier.

string

datetime

Raw combined date-time string as supplied by the carrier.

string

time

Raw event time as supplied by the carrier.

string

occurred_at

Raw timestamp the event occurred, as supplied by the carrier.

string

status

Raw status code or label from the carrier.

string

description

Raw event description from the carrier.

string

details

Additional raw event detail text from the carrier.

string

event

Raw event name or type from the carrier.

string

milestone

Raw milestone identifier from the carrier.

string

location

Raw location text from the carrier.

string

depot

Raw depot name from the carrier.

string

branch

Raw branch name from the carrier.

string

502

The legacy tracking service did not return a usable response

object

error

required

string