Scope
The following operations are allowed in the Tracking API:
| Operation | Type | Path |
| Get Tracking | GET | /tracking/v4/package/open |
All tracking requests should be authorized for the Pickup. This means that the tracking results will be returned only if the requested package is present within one or more of the authorized pickups for the API user.
We recommend that you track a package using the packageId or the dhlPackageId.
Workflow
There are many ways to track a package. Using one of the package identifiers:
packageIddhlPackageIdtrackingId
pluspickup(optional)
A single tracking request supports up to 10 package identifiers of the same kind. Use pickup as an additional query parameter in order to search for the package within a specific pickup.
There are many ways to track a group of packages. Using -
manifestIdpickup,startDate,endDatepickup,startDate,endDateplus any of the following [^1] parameterscitystatecountrypostalCodeorderedProductId
Any combination of one or more parameters of the above fields are also supported. endDate should be within 7 days of startDate
When tracking a group of packages, all searches can be paginated using the following two parameters:
offsetlimit
/tracking/v4/package/open?pickup=5119000&startDate=20190701&endDate=20190707&offset=5&limit=10
The default offset value is zero if not provided in the request. The max limit supported is 10.
When the results run into multiple pages, the links object in the response provides the URL for the prev and next page with preset offset and limit values. If there is no links object in the response, then there is no prev or next page available. The total element in the response provides the total number of packages for the query across all the pages.
Tracking IDs
There are multiple references for trackingId possible for a package. In order to minimize the complexity, all of them have been grouped under a single identifier called the trackingId. Any of the below identifiers will be supported in the query parameter when searching using the identifier trackingId.
These could be:
- DSP Mail Identifier trackingId
- Delivery Confirmation Number (Delcon) deliveryConfirmationNumber
- IMb code intelligentMailBarcode
- Overlabeled IMb Code overlabeledIntelligentMailBarcode
- Overlabeled DSP number overlabeledDspNumber
For consistency, the trackingId returned in the response of the Tracking API will always be the 'DSP Mail Identifier' even though the query searches for other identifiers mentioned above.
We recommend using the DSP Mail Identifier as the trackingId reference in your system. Other references are supported mainly for legacy customers.
In addition to the tracking history, the API response also provides additional information related to the package -
- pickup Detail pickupDetail
- package Detail package
- Recipient information recipient
This information is for reference only and we strongly recommend that this information not be made public if you're using this API to display results in a public tracking page.
M- Mandatory O- Optional C- Conditional N- Not Applicable
| Node | Data Type | Required? | Length | Description | Example Values |
| packageId | string | O | 1:30 | Customer-provided package ID, also known as the CCN (customer confirmation number) or the GM number. | GM60511234500000001 |
| dhlPackageId | string | O | 1:30 | DHL-generated package ID. | 3387191106122423 |
| trackingId | string | O | 1:30 | DSP (carrier) tracking number for the package. | 420300249374869903500011805718 |
| manifestId | string | O | 1:20 | Manifest (BOL) number under which the package was manifested. | 40931443 |
| >pickup | string | O | 4:10 | DHL eCommerce pickup account number. | 5320 |
| startDate | string | O | 1:10 | Date when package first received in a DHLeC distribution center, in YYYY-MM-DD format | 2020-07-13 |
| endDate | string | O | 1:10 | Ending receive date, in YYYY-MM-DD format (max range: 7 days inclusive) | 2020-07-13 |
| city | string | C | 1:40 | Recipient's city | Newark |
| state | string | C | 0:50 | Recipient's state or province | NJ |
| postalCode | string | C | 3:10 | Recipient's postal code | 30066 |
| country | string | C | 2 | Recipient's country | US |
| orderedProductId | string | C | 3 | DHL eCommerce product ID (defaults to billedProductId if it is different from orderedProductId) | MAX |
| limit | integer | C | 1:10 | Number of results to return per request (max = 10) | 10 |
| offset | integer | C | 0:999999 | Number of records to skip in the next request | 0 |
M- Mandatory O- Optional C- Conditional N- Not Applicable
| Node | Data Type | Required? | Length | Description | Example Values |
| total | integer | M | 1:999999 | Total number of records in the result set. | 14 |
| limit | integer | M | 1:10 | Maximum number of records returned in the request (max = 10). | 10 |
| offset | integer | M | 0:999999 | Number of records skipped in the result set. | 0 |
| timestamp | string | M | 1:50 | Timestamp of response; ISO-8601 date/time format. | 2020-07-28T18:00:00.087Z |
| links | object | O | Links to other pages in the tracking request. | ||
| previous | string | O | 1:50 | HTTPS link to the previous set of records (paging). | /tracking/v4/package/open?packageId=123456789&limit=10&offset=10 |
| next | string | O | 1:50 | HTTPS link to the next set of records (paging). | /tracking/v4/package/open?packageId=123456789&limit=10&offset=0 |
| packages | array | O | An array of packages. | ||
| recipient | object | M | The recipients address block. | ||
| city | string | O | 1:30 | Recipient city | Newark |
| state | string | O | 0:50 | Recipient state | NJ |
| postalCode | string | O | 0:20 | Recipient postal code | 7114 |
| country | string | O | 2 | Recipient country | US |
| signedForName | string | O | 0:20 | Signature for package | Jess |
| events | array | O | An array of tracking events | ||
| location | string | O | 0:100 | Event location | Hebron, KY, US |
| date | string | O | 1:10 | Event date in YYYY-MM-DD format | 2019-10-24 |
| time | string | O | 1:8 | Event time in HH:MM:SS format | 15:20:24 |
| timeZone | string | O | 0:30 | Event timezone | ET |
| gmtOffset | string | O | 0:10 | Event date and time offset to GMT. Present only for US domestic events. | GMT-08:00 |
| postalCode | string | O | 0:20 | Recipient postal code | 41048 |
| country | string | O | 2 | Event country | US |
| primaryEventId | integer | M | 1:6 | Event id | 220 |
| primaryEventDescription | string | O | 1:100 | Event description | PROCESSED |
| secondaryEventId | integer | O | 0:6 | Event id | 100 |
| secondaryEventDescription | string | O | 0:100 | Secondary event description | PROCESSED in FACILITY |
| package | object | M | Package detail | ||
| dhlPackageId | string | O | 1:30 | DHL-generated package ID. | 3387191106122423 |
| packageId | string | O | 1:30 | Customer-provided package ID, also known as the CCN (customer confirmation number) or the GM number. | GM60511234500000001 |
| manifestId | string | O | 1:30 | Number assigned to the Consignment/BOL during Manifesting | 531818890913173105551 |
| trackingId | string | O | 1:30 | Last-mile carrier package ID. For international shipments, this ID is only available after the package has been shipped. For domestic shipments, this ID contains the full USPS IMpb number and is always available. If the package is overlabeled for any reason, this field contains the latest carrier package ID. | 420071149361269903500011492028 |
| deliveryConfirmationNumber | string | O | 1:50 | For domestic shipments, this is the USPS tracking number, which is part of the IMpb number and is also sometimes referred to as the PIC (package identification code). If the package is overlabeled for any reason, this field contains the latest USPS tracking number. For international shipments, this field contains the last-mile carrier package ID (same value as the trackingId field) and is only available after the package has been shipped. | 9361269903500011492028 |
| overlabeledDspNumber | string | O | 1:60 | For domestic shipments which have been overlabeled, this is the original USPS tracking number. The USPS tracking number is part of the IMpb number and is also sometimes referred to as the PIC (package identification code). For international shipments and non-overlabeled domestic shipments, this field is unused. | 9261269903500013618305 |
| intelligentMailBarcode | string | O | 1:60 | For domestic flats shipments, this is the USPS IMb number. If the package is overlabeled for any reason, this field contains the latest IMb number. For international shipments and non-flats domestic shipments, this field is unused. | 0031043534391627906195625053434 |
| overlabeledIntelligentMailBarcode | string | O | 1:60 | For domestic flats shipments which have been overlabeled, this is the original USPS IMb number. For international shipments and non-overlabeled / non-flats domestic shipments, this field is unused. | 0031043534391640211895625057522 |
| productClass | string | O | 1:50 | DHL eCommerce product class assigned to the package | Domestic |
| orderedProductId | string | O | 3 | DHL eCommerce original ordered product name assigned to the item | EXP |
| billedProductId | string | O | 3 | DHL eCommerce product id assigned to the package | EXP |
| productName | string | O | 1:500 | The full name of the product | DHL Parcel International Direct |
| signatureConfirmationFlag | boolean | O | true, false | Does the package have signature confirmation? | true |
| expectedDelivery | string | O | 1:10 | Date the package is expected to receive a delivery scan. In YYYY-MM-DD format. | 12/25/2019 |
| weight | object | O | Weight of the package | ||
| value | float | M | 0:999999999 | Total rate calculated for this product | 7.40 |
| currency | string | M | 3:3 | Three-character ISO currency code for the rate | USD |
| effectiveForm | string | M | 10 | Date that reflects when a rate was last updated | 2024-01-28 |
| rateComponents | array | M | Rate components | ||
| value | string | M | 1:10 | Unique rate component identifier | ZBPT |
| partId | string | M | 1:20 | Invoiced part identifier for this rate component | 36 |
| description | string | M | 1:50 | Short description of this rate component | Base Rate |
| amount | float | M | 0:999999999 | Amount of this rate component, expressed in the total rate currency | 6.23 |
| value | float | M | 1:9999.99 | Package weight | 3.2 |
| unitOfMeasure | string | M | 1:3 | Package weight unit | lb |
| intelligentMailBarcodeFlag | boolean | O | true, false | Whether IMB was applied | true |
| declaredValue | integer | O | 1:50 | Declared value of the item | 23 |
| declaredValueCurrency | string | O | 3 | Declared value currency | USD |
| batchReference | string | O | 1:50 | Customer provided reference for the package | TEST |
| contentCategory | string | O | 1:50 | Mail content category assigned to the item | 01 |