canonical: https://jentic.com/apis/dhl.com/dhl-tracking-api

# DHL Unified Shipment Tracking API

The DHL Unified Shipment Tracking API returns real-time status updates for shipments across DHL Express, eCommerce, Freight, and Supply Chain through a single GET /shipments endpoint. Given a tracking number, it returns the current shipment state, milestone history, and the responsible DHL division. It is the canonical way to integrate cross-divisional DHL tracking from a storefront, customer-service tool, or operations dashboard.

## For AI agents

Look up real-time shipment status and milestone events for any DHL parcel or freight shipment across all divisions through one tracking endpoint.

## Scope

Does not handle label creation, rate quotes, or pickup booking - use for DHL shipment tracking lookups only.

## Capabilities

- Look up shipment status by tracking number across all DHL divisions
- Retrieve milestone events with timestamps for a shipment journey
- Identify which DHL division is responsible for a given shipment
- Filter tracking responses by service, origin, and destination country
- Detect when a shipment reaches the out-for-delivery or delivered state
- Surface estimated delivery dates where DHL has computed them

## Use cases

### Order Tracking on Customer Storefront

Display a real-time tracking timeline on an order details page without picking the right DHL divisional API for each shipment. One call to GET /shipments returns status, events, and estimated delivery, making it suitable for both Express and standard parcel shipments. This simplifies the storefront integration to a single tracking client.

Example prompt: Given tracking number JJD1234567890, render the milestone timeline and the estimated delivery date on the order details page

### Operations Exception Monitoring

Run a daily reconciliation job that flags shipments stuck in transit, returned to sender, or otherwise off the expected path. The tracking endpoint returns the latest milestone for each tracking number, which an operations dashboard can compare against expected delivery windows. This makes it possible to surface exceptions before customers complain.

Example prompt: For every tracking number in yesterday's outbound batch, fetch the current status and flag any whose latest event is older than 48 hours and not yet delivered

### Customer Notification Automation

Send the customer an SMS or email the moment their parcel changes state. By polling the tracking endpoint and comparing the latest milestone against the previous one, an automation can trigger out-for-delivery and delivered notifications even when the carrier does not push webhooks back. Useful for retailers without a dedicated tracking partner.

Example prompt: Poll tracking number 1234567890 every hour and send a templated SMS the first time the latest event status equals out-for-delivery or delivered

### AI Agent Where-Is-My-Order Bot

An AI customer-service assistant can answer shipping queries by calling the DHL unified tracking endpoint through Jentic. The agent searches by intent ("track a shipment"), loads the input schema, executes with the user's tracking number, and summarises the milestone history in natural language without needing the OpenAPI spec.

Example prompt: When the user provides a tracking number, call the DHL tracking endpoint, summarise the current status and ETA, and offer to keep watching the shipment until it is delivered

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/shipments` | Retrieve tracking status and event history for a shipment |

## Key resources

- **Shipments** — Track status, milestones, and addresses for a DHL shipment by tracking number

## Why Jentic

- **Setup:** Wiring the DHL Unified Shipment Tracking API by hand means setting the DHL-API-Key header against the EU tracking host and handling the query parameters for the shipments lookup yourself. Through Jentic you install once, import the DHL Unified Shipment Tracking API from the API Directory, store the API key once, and your agent calls it.
- **Permission scoping:** The API exposes a single read-only shipments lookup, so the agent can only track shipments and nothing else, and you decide whether to give it that one operation. It cannot create labels, quote rates, or book pickups.
- **Credential handling:** Your DHL API key is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'track a shipment', and Jentic returns the matching DHL operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **DHL Shipment Tracking - Unified API** — Identical surface area under a slightly different naming - the canonical "Unified API" entry
- **DHL eCommerce (Netherlands) API** — Label creation and shipment options for DHL Parcel in the Netherlands

## FAQ

### What authentication does the DHL Unified Shipment Tracking API use?

The API uses an API key passed in a request header. Keys are issued from the DHL Developer Portal. Through Jentic the key is stored in the encrypted vault and injected only at execution time.

### Can a single call track shipments from any DHL division?

Yes. GET /shipments accepts a tracking number across Express, eCommerce, Freight, and Supply Chain. The response identifies which division handled the shipment and returns a unified status and milestone timeline.

### What are the rate limits for the DHL Unified Shipment Tracking API?

Rate limits are tier-based and set when the API key is provisioned. Free tier keys are typically capped at 250 requests per day; higher tiers expand that allowance. Check the DHL Developer Portal for the limit attached to your key.

### How do I track a parcel through Jentic?

Run a Jentic search for "track a DHL shipment". Jentic returns the tracking operation with its input schema (trackingNumber as a query parameter), the agent loads the schema, and executes. Optional filters include service and originCountryCode.

### Does the response include estimated delivery dates?

Yes, when DHL has computed one. The shipment response includes an estimatedTimeOfDelivery field for divisions that publish ETAs and a list of milestone events with timestamps.

### How do I install the Jentic SDK to call DHL tracking?

Run pip install jentic, set JENTIC_AGENT_API_KEY to your ak_* key, then use Jentic with SearchRequest, LoadRequest, and ExecutionRequest. Get started with Jentic One, the self-hosted execution layer.

### Can I limit what my agent is allowed to do with the DHL Unified Shipment Tracking API?

Yes. Because you run Jentic One yourself, you decide which operations and credentials your agent may use, and your own rules govern every call. This API exposes only a single read-only shipments lookup (GET /shipments), so the agent can track shipments and nothing more. It cannot create labels, quote rates, or book pickups, and you choose whether to grant it even that one tracking operation.