# Checkpoints ## Get Checkpoints Details of how the `v2/checkpoints` endpoint can be used to retrieve the checkpoints for a tracking in the parcelLab system are described below.
GET Checkpoints via Courier and Tracking Number You can retrieve the checkpoints for a tracking using the `courier` and `tracking_number` with the `v2/checkpoints` endpoint. The details of the Get Checkpoints via Courier and Tracking Number API are described in the following section. **API Details** `GET` `https://api.parcellab.com/v2/checkpoints` **Query Parameters** | Name | Type | Description | | ------- | ------ | ------------------------------------------------------------------------------------------------------------ | | tno | string | Tracking number | | courier | string | Courier code | | lang | string | Language in [ISO 3166-1 alpha-3](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3) format. Defaults to `en`. | An example request is displayed below to show the format for retrieving checkpoints via the courier and tracking number. {% code overflow="wrap" %} ```bash curl --location 'https://api.parcellab.com/v2/checkpoints/?tno=00340000000000000001&courier=dhl&lang=de ``` {% endcode %} **Responses** * 200 - accepted An example successful response is displayed below to show the format for retrieving checkpoints. ```javascript { "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" } ] } } ```
GET Checkpoints via Order Number You can retrieve the checkpoints for a tracking using the `orderNo` and your `user_id` with the `v2/checkpoints` endpoint. **Note:** If you want to include return trackings, add the `&showReturns=true` parameter. To only include *active* returns (returns portal labels or returns dropped off to the carrier), add `&showActiveReturns=true` instead. The response header will then include entries you can identify via `header.delivery_info.isReturn`. The details of the Get Checkpoints via Order Number API are described in the following section. **API Details** `GET` `https://api.parcellab.com/v2/checkpoints` **Query Parameters**
NameTypeDescription
usernumberparcelLab user ID
orderNostringAssigned order number
langstringLanguage as ISO 3166-1 alpha-3, defaults to en
showReturnsbooleanOptional: set to true to include return labels alongside forward shipments
showActiveReturnsbooleanOptional: set to true to include only active returns (returns portal labels or returns dropped off to carrier)
An example request is displayed below to show the format for retrieving checkpoints via the order number. {% code overflow="wrap" %} ```bash curl --location 'https://api.parcellab.com/v2/checkpoints/?user=USERID&orderNo=12ORDER34&lang=de’ ``` {% endcode %} **Responses** * 200 - accepted An example successful response is displayed below to show the format for retrieving checkpoints. ```javascript { "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" } ] } } ```
GET Checkpoints via XID You can retrieve the checkpoints for a tracking using the `xid` and your `user_id` with the `v2/checkpoints` endpoint. The details of the Get Checkpoints via XID API are described in the following section. **API Details** `GET` `https://api.parcellab.com/v2/checkpoints` **Query Parameters** | Name | Type | Description | | ---- | ------ | ------------------------------------------------ | | user | number | User ID in parcelLab | | xid | string | Assigned xid | | lang | string | Language as ISO 3166-1 alpha-3, defaults to `en` | An example request is displayed below to show the format for retrieving checkpoints via XID. {% code overflow="wrap" %} ```bash curl --location 'https://api.parcellab.com/v2/checkpoints/?user=USERID&xid=12XID34&lang=de’ ``` {% endcode %} **Responses** * 200 - accepted An example successful response is displayed below to show the format for retrieving checkpoints. ```javascript { "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 gives a `200 OK` status code and a JSON encoded response object. This object consists of a `header` and `body`. ### Return Header The `header` is an array that provides an overview of all trackings returned. When requesting the API with a combination of `courier` and `tracking_number`, the array will always have `header.length === 1`. {% hint style="info" %} For authed requests, all standard return documents for returns created through parcelLab will be available in the header for the `checkpoints` endpoint. {% endhint %} The details of the header for each tracking are described in the following table. | Key | Type | Description | | ---------------------- | ------- | --------------------------------------------------------------------------------- | | id | String | The ID of the tracking which serves as the key in the `body`. | | tracking\_number | String | The tracking number of the tracking. | | courier | Object | Details about the [courier](#courier-object). | | last\_delivery\_status | Object | Details about the [current status](#last-delivery-status-object) of the tracking. | | delay | Boolean | Whether a delay of this delivery has been detected by parcelLab. | | exception | Boolean | Whether an escalated problem has been detected by parcelLab. | #### **Courier Object** The details of the courier object for each tracking are described in the following table. | Key | Type | Description | | ------------------------ | ------- | ------------------------------------------------------------------------------------ | | name | String | The courier code (for example: `dhl-germany`). | | prettyname | String | The display name of the courier (for example: `DHL`). | | trackingurl | String | The URL of the courier's own tracking page. | | trackingurl\_label | String | The localized label of the `trackingurl`. | | hide\_trackingurl | Boolean | Whether to hide the tracking URL. | | rerouteurl | String | The URL of the courier's own tracking page in case the recipient reroutes the order. | | rerouteurl\_label\_short | String | The localized short label of the `rerouteurl`. | | rerouteurl\_label\_long | String | The localized long label of the `rerouteurl`. | | rerouteurl\_label\_info | String | The localized information regarding the `rerouteurl`. | | destination\_courier | Object | Information regarding the final courier handling the parcel. | #### **Last Delivery Status Object** The details of the last delivery status object for each tracking are described in the following table. {% hint style="info" %} For further information, see the complete list of [status codes](/docs/developers/v2/data-elements/status-model.md#status-codes) that can be used. {% endhint %} | Key | Type | Description | | --------------- | ------ | ------------------------------------------------------------- | | status | String | A short description of the current status of the delivery. | | status\_details | String | A detailed description of the current status of the delivery. | | code | String | The applicable parcelLab status code. | ### Return Body The `body` is an object that provides an array of checkpoints for each tracking (identified by their `id`) in the header. The details of the array for each tracking are described in the following table. | Key | Type | Description | | --------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | shown | Boolean |

Whether the checkpoint has been marked as unclear by parcelLab.

Note: Checkpoints provided by the courier which are unclear and do not help the recipient to understand the current status of the delivery are automatically filtered.

| | status | String | The applicable parcelLab status code. | | status\_text | String | A short description of the current status of the delivery. | | status\_details | String | A detailed description of the current status of the delivery. | | full\_courier\_status | String |

The full status code provided by the courier for reference.

Note: This is not recommended to display to the recipient.

| | location | String | The location of the checkpoint if available; otherwise an empty string `""` is returned. | | timestamp | String | The date and time of the checkpoint, formatted as [Date.prototype.toJSON()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toJSON). | ## Get Tracking Details Details of how the `v2/tracking-details` endpoint can be used to retrieve the details of a tracking in the parcelLab system are described below.
GET Tracking Details You can retrieve all the status details of a tracking using the `orderNo` with the `tracking-details` endpoint. For low volume requests, the `v2/tracking-details` endpoint retrieves 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 resulting JSON will have the same structure as the `v2/checkpoints` endpoint above but will feature more details for the action box (details below). The details of the Get Tracking Details API are described in the following section. **API Details** `GET` `https://api.parcellab.com/v2/tracking-details` **Query Parameters** | Name | Type | Description | | ------- | ------ | ------------------------------------------------ | | orderNo | string | primary reference number of the order | | lang | string | language as ISO 3166-1 alpha-3, defaults to `en` | **Header** | Name | Type | Description | | ------------ | ------ | ------------------- | | user | number | parcelLab user ID | | token | string | parcelLab API token | | content-type | string | 'application/json' | **Responses** * 200 - accepted An example successful response is displayed below to show the format for retrieving tracking details (same results as checkpoints above, with more details in the action box). ```javascript { "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 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`). The variations available are described in the following sections. #### Type `prediction` For a prediction, a sub document is included with the scheduled delivery date. This is displayed in the format below. {% code title="actionBox-prediction.json" %} ```javascript "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" } } ``` {% endcode %} #### Type `pickup-location` For a delivery to be collected, a sub document is included with the opening hours. This is displayed in the format below. {% hint style="info" %} The format of the opening hours is the same as used by the [Google Maps API](https://developers.google.com/places/web-service/details#PlaceDetailsResults). {% endhint %} {% code title="actionBox-pickup.json" %} ```javascript "actionBox": { "type": "pickup-location", "address": "Kurfürstenplatz 8, 80796 München", "openingHours": [ { "close": { "day": 1, "time": "1800" }, "open": { "day": 1, "time": "0800" } }, ... ] }, ``` {% endcode %} ## Get Sender Information for a Tracking Details of how the `sender` endpoint can be used to retrieve sender information for an order or tracking in the parcelLab system are described below.
GET Sender Information for a Tracking You can retrieve the sender information given for an order or tracking using the `courier` and `tracking_number` with the `sender` endpoint. **Note:** All request parameters specified above for `v2/checkpoints` are also supported. The details of the Get Sender Information for a Tracking API are described in the following section. **API Details** `GET` `https://api.parcellab.com/sender` **Query Parameters** | Name | Type | Description | | ------- | ------ | --------------------------------------------------------------------------------------------------------------- | | tno | string | Tracking number | | courier | string | Courier code | | lang | string | Language in in [ISO 3166-1 alpha-3](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3) format. Defaults to `en`. | An example request is displayed below to show the format for retrieving sender information for a tracking. {% code overflow="wrap" %} ```bash curl --location 'https://api.parcellab.com/sender/?tno=003400SOMETRACKING&courier=dhl-germany&lang=de’ ``` {% endcode %} **Responses** * 200 - accepted
## Get Article List of a Tracking Details of how the `v2/checkpoints` endpoint can be used to retrieve the article list for an order or tracking in the parcelLab system are described below.
GET Article List of Tracking You can retrieve the article list for an order or tracking using the `courier` and `tracking_number` with the `v2/checkpoints` endpoint. In order to retrieve the article list, request authentication through the security hash `&s=` is required. **Note:** All request parameters specified above for `v2/checkpoints` are also supported. The details of the Get Article List of a Tracking API are described in the following section. **API Details** `GET` `https://api.parcellab.com/v2/checkpoints` **Query Parameters** | Name | Type | Description | | ------- | ------ | --------------------------------------------------------------------------------------------------------------- | | tno | string | Tracking number | | courier | string | Courier code | | lang | string | Language in in [ISO 3166-1 alpha-3](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3) format. Defaults to `en`. | | s | string | Security hash | An example request is displayed below to show the format for retrieving the article list of a tracking. {% code overflow="wrap" %} ```bash curl --location 'https://api.parcellab.com/sender/?tno=003400SOMETRACKING&courier=dhl-germany&lang=de&s=ABCD1234’ ``` {% endcode %} **Responses** * 200 - accepted
## Get Notifications of a Tracking Details of how the `v2/notifications` endpoint can be used to retrieve all notifications for a tracking in the parcelLab system are described below.
GET Notifications of Tracking You can retrieve all sent notifications for a tracking using the `userId` and `trackingId` with the `v2/notifications` endpoint. The details of the Get Notifications for a Tracking API are described in the following section. **API Details** `GET` `https://api.parcellab.com/v2/notifications` **Path Parameters** | Name | Type | Description | | ---- | ------ | --------------------- | | tid | string | parcelLab tracking ID | **Header** | Name | Type | Description | | ----- | ------ | ------------------- | | user | number | parcelLab user ID | | token | string | parcelLab API token | An example request is displayed below to show the format for retrieving the notifications for a tracking. ```bash curl --location 'https://api.parcellab.com/v2/notifications?tid=50ae00000000000000000001’ \ --header 'user: 100' \ --header 'token: parcelLabAPItoken-30characters' \ ``` **Responses** **`200 OK`** All notifications for selected tracking or order will be shown in the JSON response body formatted as an array of objects with the following fields: * Array sorted by `timestamp` (oldest → newest) across channels. Each item includes `type` (`email|sms|webhook|app`) and, when applicable, `from_other_tracking` (`true` if it belongs to a sibling tracking of the same order). * Email fields: `id`, `subject`, `created`, `sentAt`, `message`/`messageType`/`prettyName`, `opened`, `clicked`, `bounced`, `rescueLink`, `live`, `attachments` \[{`url`,`filename?`,`isOptional`}], optional `source` (slot/trigger data). * SMS fields: `id`, `messageType`/`prettyName`, `message`, `receiver`, `clicked`, `segments`, `sender`, `trackingId`, `failed`, `courier`, optional `source`. * Webhook fields: `id`, `messageType`/`prettyName`, `status`, `success`, `isFinalAttempt`, `receiver` (URL without query), `headers`, `message` (request body), `response_headers`, `response_body`, `response_error`, `is_push_notification`, `timing`, `payload_size`, optional `source`. * App execution fields: `id`, `installedApp`, `customApp`, `slug`, `appName`, `appType`, `appKey`, `success`, `input`, `output`, `duration`, `deduplicationId`, `created`/`timestamp`, optional `source`. * Email attachment URLs are pre-signed (1-day expiry); `opened`/`clicked` are nulled if the account has `hideEmailEngagement` enabled. *** **`401 UNAUTHORIZED`** Not authorized to access data for this tracking. Plain text response body: `Access denied.` *** **`404 NOT FOUND`** Requested tracking cannot be found. This does not reflect the case of a tracking without any notifications, which would be an empty array response with status 200. Plain text response body: `Nothing found.` *** **`500 INTERNAL SERVER ERROR`** Server error when processing result or accessing database. Plain text response body: `Error accessing database.`
--- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.parcellab.com/docs/developers/v2/status-updates/checkpoints.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.