Getting status updates

Retrieving a tracking from parcelLab refers to the act of requesting the information about a certain delivery from parcelLab. We call this information about the progress up to now the checkpoints.

get
Get checkpoints

https://api.parcellab.com/v2/checkpoints/
Retrieves the current status of a tracking or an order.
Request
Response
Query Parameters
tno
required
string
Tracking number
courier
required
string
Courier code
lang
optional
string
Language as ISO 3166-1 alpha-3, defaults to en
200: OK
For more details of the response please see below.
{
"header": [
{
"id": "579f6444b6a1bb4fbaab5610",
"tracking_number": "00340000000000000001",
"courier": {
"name": "dhl-germany",
"prettyname": "DHL",
"trackingurl": "https://nolp.dhl.de/ne~~~00001",
"trackingurl_label": "Klicken Sie hier f├╝r weitere Informationen zur Sendung."
},
"last_delivery_status": {
"status": "Zugestellt",
"status_details": "Die Ware wurde erfolgreich zugestellt.",
"code": "Delivered"
},
"delay": false,
"exception": false
}
],
"body": {
"579f6444b6a1bb4fbaab5610": [
{
"shown": true,
"status": "OrderProcessed",
"status_text": "Bestellung verarbeitet",
"status_details": "Die Bestellung wurde verarbeitet.",
"full_courier_status": "If exists, date of order, else date of import to parcelLab",
"location": "Sample City",
"timestamp": "2015-08-10T15:18:27.000Z"
}
]
}
}

The return of a successful call of this endpoint yields status code 200 OK and a JSON encoded response object. This object consists of a header and body.

Return Header

The header is an array listing an overview over all trackings returned. When requesting the API like documented here with a combination of courier and tracking_number the array with always have header.length === 1.

The overview for each tracking is structured like this:

Key

Type

Description

id

String

id of the tracking which serves as key in the body

tracking_number

String

tracking number of the tracking

courier

Object

details about the courier, explained below

last_delivery_status

Object

details about the current status of the tracking

delay

Boolean

true if a delay of this delivery has been detected by parcelLab

exception

Boolean

true if an escalated problem has been detected

Return object courier

Key

Type

Description

name

String

the courier code (e.g. dhl-germany )

prettyname

String

pretty name of the courier to be displayed (e.g. DHL )

trackingurl

String

URL of courier's own tracking page

trackingurl_label

String

localised label for trackingurl

Return object last_delivery_status

Key

Type

Description

status

String

see below in description of checkpoints

status_details

String

see below in description of checkpoints

code

String

see below in description of checkpoints

Return Body

The body simply is an object where for each tracking in the header, identified by their id, an array of checkpoints is given. This array has the following structure:

Key

Type

Description

shown

Boolean

parcelLab automatically filters checkpoints provided by the courier which are unclear and do not help the recipient to understand the current status of the delivery. These unclear status are marked with false .

status

String

One of the parcelLab status codes

status_text

String

A localised short description of the current status of the delivery

status_details

String

A localised longer, more detailed description of the current status of the delivery

full_courier_status

String

The full status code provided by the courier for reference, not recommended to display to recipient

location

String

Location of checkpoint if available, else empty string ""

timestamp

String

Date and time of checkpoint formatted as Date.prototype.toJSON()ÔÇő

Alternatively, a request can be performed using the orderNo:

get
Get checkpoints via order number

https://api.parcellab.com/v2/checkpoints
Alternative request structure with orderNo, response as described above.
Request
Response
Query Parameters
u
required
number
User ID in parcelLab
orderNo
required
string
Assigned order number
lang
optional
string
Language as ISO 3166-1 alpha-3, defaults to en
200: OK
As above
ÔÇő

get
Retrieve all tracking status details

https://api.parcellab.com/v2/tracking-details
For low volume requests, the /tracking-details route allows to retrieve the complete and latest status details of a delivery. As all data is being pulled synchronously, expect higher response times. For high volume calls, we require using the normal checkpoints API described above. The result JSON will have the same structure as /checkpoints above, but will feature more details for the action box. Details below.
Request
Response
Headers
user
required
number
parcelLab User ID
token
required
string
parcelLab Token
required
string
'application/json'
Query Parameters
orderNo
required
string
primary reference number of the order
lang
optional
string
language as ISO 3166-1 alpha-3, defaults to en
200: OK
Same result as above with more details in the action box
tracking-details.json
{
"header": [
{
"id": "5cbf6ad11b8bd5bc9bf8c2c1",
"tracking_number": "00PL16120004",
"actionBox": {
"type": "prediction",
"label": "Estimated Delivery:",
"prediction": {
"label": "Estimated Delivery:",
"type": "prediction",
"timeCaption": "",
"dateOfMonth": "21",
"dayOfWeek": "Saturday",
"month": "December",
"caption": "The delivery has been announced by DHL.",
"startTime": "11:30",
"endTime": "13:30"
}
},
"courier": {
"name": "dhl-germany",
"prettyname": "DHL",
"trackingurl": "https://nolp.dhl.de/nextt-online-public/en/set_identcodes.do?idc=00PL16120004",
"trackingurl_label": "Find further information about this order at DHL",
"rerouteurl": "https://www.dhl.de/de/privatkunden/pakete-empfangen/verfolgen.html?piececode=00PL16120004",
"rerouteurl_label_short": "Select a delivery option",
"rerouteurl_label_long": "You are not at home? Select your delivery day and location",
"rerouteurl_label_info": "if available",
"destinationCourier_name": "DHL"
},
"last_delivery_status": {
"code": "Scheduled",
"status": "Date fixed",
"status_details": "An appointment to make the delivery has been made. The goods will be delivered on Saturday, Dec 21st, 2019, between 11:30 am and 1:30 pm.",
"specifics": "21.12.2019 11:30 h to 21.12.2019 13:30 h. (Type: telephone)"
},
"delay": false,
"exception": false
},
{
"id": "5cbf6add1b8bd5bc9bf8c2cc",
"tracking_number": "00PL16120006",
"actionBox": {
"type": "pickup-location",
"address": "Kurf├╝rstenplatz 8, 80796 M├╝nchen",
"openingHours": [
{
"close": {
"day": 1,
"time": "1800"
},
"open": {
"day": 1,
"time": "0800"
}
},
{
"close": {
"day": 2,
"time": "1800"
},
"open": {
"day": 2,
"time": "0800"
}
},
{
"close": {
"day": 3,
"time": "1800"
},
"open": {
"day": 3,
"time": "0800"
}
},
{
"close": {
"day": 4,
"time": "1800"
},
"open": {
"day": 4,
"time": "0800"
}
},
{
"close": {
"day": 5,
"time": "1800"
},
"open": {
"day": 5,
"time": "0800"
}
},
{
"close": {
"day": 6,
"time": "1400"
},
"open": {
"day": 6,
"time": "0900"
}
}
]
},
"courier": {
"name": "dhl-germany",
"prettyname": "DHL",
"trackingurl": "https://nolp.dhl.de/nextt-online-public/en/set_identcodes.do?idc=00PL16120006",
"trackingurl_label": "Find further information about this order at DHL",
"rerouteurl": null,
"rerouteurl_label_short": null,
"rerouteurl_label_long": null,
"rerouteurl_label_info": null,
"destinationCourier_name": "DHL"
},
"last_delivery_status": {
"code": "PickupReadyNextDay",
"status": "Ready for collection",
"status_details": "The goods will be ready for collection on the next working day at the parcel shop (<a href=\"http://maps.google.com/?q=Kurf%C3%BCrstenplatz%208%2C%2080796%20M%C3%BCnchen\" {{TextStyling/client}} target=\"_blank\">Kurf├╝rstenplatz 8, 80796 M├╝nchen</a>).",
"specifics": "Kurf├╝rstenplatz 8 80796 M├╝nchen"
},
"delay": true,
"exception": false
}
],
"body": {
"5cbf6ad11b8bd5bc9bf8c2c1": [
{
"location": "",
"timestamp": "2016-08-26T00:00:00.000Z",
"status": "OrderProcessed",
"status_text": "Order processed",
"status_details": "The order has been processed.",
"shown": true,
"full_courier_status": "If exists, date of order, else date of import to parcelLab"
},
{
"shown": true,
"timestamp": "2016-08-27T12:17:00.000Z",
"status": "PickUpScheduled",
"status_text": "Pick-up scheduled",
"status_details": "The goods are being processed for pick-up.",
"full_courier_status": "Die Auftragsdaten zu dieser Sendung wurden vom Absender elektronisch an DHL ├╝bermittelt.",
"created": "2016-08-27T13:00:47.001Z"
},
{
"shown": false,
"location": "Feucht",
"timestamp": "2016-08-27T18:14:59.000Z",
"status": "InboundScan",
"status_text": "Dispatched",
"status_details": "The goods have been sent.",
"full_courier_status": "Die Sendung wurde im Start-Paketzentrum bearbeitet.",
"created": "2016-08-27T18:08:00.277Z"
},
{
"shown": true,
"location": "Feucht",
"timestamp": "2016-08-27T18:15:00.000Z",
"status": "InboundScan",
"status_text": "Dispatched",
"status_details": "The goods have been sent.",
"full_courier_status": "Die Sendung wurde im Start-Paketzentrum bearbeitet.",
"created": "2016-08-27T18:08:00.277Z"
},
{
"shown": true,
"location": "R├╝dersdorf",
"timestamp": "2016-08-29T04:54:00.000Z",
"status": "DestinationDeliveryCenter",
"status_text": "Delivery is being prepared",
"status_details": "The goods have arrived in the destination region.",
"full_courier_status": "Die Sendung wurde im Ziel-Paketzentrum bearbeitet.",
"created": "2016-08-29T06:36:55.166Z"
},
{
"shown": true,
"timestamp": "2016-08-29T07:58:00.000Z",
"status": "Scheduled",
"status_text": "Date fixed",
"status_details": "An appointment to make the delivery has been made. The goods will be delivered on Saturday, Dec 21st, 2019, between 11:30 am and 1:30 pm.",
"full_courier_status": "Notification of the delivery/pick-up of the shipment was given for the period 21.12.2019 11:30 h to 21.12.2019 13:30 h. (Type: telephone)",
"created": "2016-08-29T06:36:55.167Z",
"Specifics": "21.12.2019 11:30 h to 21.12.2019 13:30 h. (Type: telephone)",
"ParsedSpecifics": {
"startDay": "2019-12-21T00:00:00.000Z",
"endDay": "2019-12-21T00:00:00.000Z",
"startTime": "2019-09-04T11:30:00.000Z",
"endTime": "2019-09-04T13:30:00.000Z"
}
}
],
"5cbf6add1b8bd5bc9bf8c2cc": [
{
"location": "",
"timestamp": "2019-09-01T04:41:14.498Z",
"status": "OrderProcessed",
"status_text": "Order processed",
"status_details": "The order has been processed.",
"shown": false,
"full_courier_status": "If exists, date of order, else date of import to parcelLab"
},
{
"shown": true,
"timestamp": "2017-01-24T17:21:00.000Z",
"status": "PickUpScheduled",
"status_text": "Pick-up scheduled",
"status_details": "The goods are being processed for pick-up.",
"full_courier_status": "The instruction data for this shipment have been provided by the sender to DHL electronically",
"created": "2017-01-24T18:07:08.382Z"
},
{
"shown": true,
"location": "Kitzingen",
"timestamp": "2017-01-25T15:51:00.000Z",
"status": "InboundScan",
"status_text": "Dispatched",
"status_details": "The goods have been sent.",
"full_courier_status": "The shipment has been processed in the parcel center of origin",
"created": "2017-01-25T16:17:30.710Z"
},
{
"shown": true,
"location": "Augsburg",
"timestamp": "2017-01-26T03:33:00.000Z",
"status": "DestinationDeliveryCenter",
"status_text": "Delivery is being prepared",
"status_details": "The goods have arrived in the destination region.",
"full_courier_status": "The shipment has been processed in the destination parcel center",
"created": "2017-01-26T07:20:13.462Z"
},
{
"shown": true,
"timestamp": "2017-01-26T07:50:00.000Z",
"status": "Scheduled",
"status_text": "Date fixed",
"status_details": "An appointment to make the delivery has been made.",
"full_courier_status": "Voraussichtliche Zustellung Do, 26.01.17 zwischen 12:30 und 15:30 Uhr",
"created": "2017-01-26T08:48:20.472Z",
"Specifics": "26.01.17 zwischen 12:30 und 15:30",
"ParsedSpecifics": {
"startDay": null,
"endDay": null,
"startTime": "2019-09-04T12:30:00.000Z",
"endTime": "2019-09-04T15:30:00.000Z"
}
},
{
"shown": true,
"timestamp": "2017-01-26T08:24:00.000Z",
"status": "OutForDelivery",
"status_text": "Out for delivery",
"status_details": "The goods will be delivered today.",
"full_courier_status": "The shipment has been loaded onto the delivery vehicle",
"created": "2017-01-26T08:47:34.613Z"
},
{
"shown": true,
"location": "",
"timestamp": "2017-01-26T12:43:00.000Z",
"status": "FailedAttemptFirst",
"status_text": "Failed delivery attempt",
"status_details": "Unfortunately, the goods could not be delivered. The goods are being forwarded to a pick-up location.",
"full_courier_status": "The shipment could not be delivered and is being forwarded to a retail outlet. The recipient has been notified.",
"created": "2017-01-26T13:17:31.011Z",
"NextAction": "PickUpReady"
},
{
"shown": true,
"location": "",
"timestamp": "2017-01-26T15:57:00.000Z",
"status": "PickupReadyNextDay",
"status_text": "Ready for collection",
"status_details": "The goods will be ready for collection on the next working day at the parcel shop (<a href=\"http://maps.google.com/?q=Kurf%C3%BCrstenplatz%208%2C%2080796%20M%C3%BCnchen\" {{TextStyling/client}} target=\"_blank\">Kurf├╝rstenplatz 8, 80796 M├╝nchen</a>).",
"full_courier_status": "The shipment is being brought to <a href='http://standorte.deutschepost.de/Standortsuche?standorttyp=filialen_verkaufspunkte&ort=Pei%C3%9Fenberg&strasse=Hauptstr.&hausnummer=85&postleitzahl=82380&lang=en' class='arrowLink' target='_blank'><span class='arrow'></span>retail outlet Kurf├╝rstenplatz 8 80796 M├╝nchen</a> for pick-up. The earliest time when it can be picked up can be found on the notification card.",
"created": "2017-01-26T16:18:49.382Z",
"Specifics": "Kurf├╝rstenplatz 8 80796 M├╝nchen"
}
]
}
}

The additional details in the action box are type-specific. For example, if the tracking.actionBox.type === 'pickup-location', the action box will also feature a new key with the openingHours. All variations are as follows:

Type prediction

For a prediction, we'll include a sub document with the scheduled delivery date in this format:

actionBox-prediction.json
"actionBox": {
"type": "prediction",
"label": "Estimated Delivery:",
"prediction": {
"label": "Estimated Delivery:",
"type": "prediction",
"timeCaption": "",
"dateOfMonth": "21",
"dayOfWeek": "Saturday",
"month": "December",
"caption": "The delivery has been announced by DHL.",
"startTime": "11:30",
"endTime": "13:30"
}
}

Type pickup-location

For a delivery to be collected the opening hours are added in the sub document as described below. The format of the opening hours is the same as used by the Google Maps API.

actionBox-pickup.json
"actionBox": {
"type": "pickup-location",
"address": "Kurf├╝rstenplatz 8, 80796 M├╝nchen",
"openingHours": [
{
"close": {
"day": 1,
"time": "1800"
},
"open": {
"day": 1,
"time": "0800"
}
},
...
]
},