A carrier tracking API is a system that allows the location and status of a shipment to be queried in real time through direct communication between digital platforms. Understanding how the carrier tracking API works is the foundation for building reliable integrations in any TMS, WMS, or e-commerce store. Unlike EDI, which prioritizes large-scale documentary transactions, APIs prioritize frequent visibility of operational events in real time. Platforms such as TrackRoad and Loggi already expose these interfaces so that development teams can integrate them directly into their logistics systems.
How does the carrier tracking API work?
A tracking API operates under the classic request-and-response scheme. Your system - whether an ERP, a TMS, or an online store - sends a request to the carrier's server with the shipment identifiers. The server processes that request and returns a structured object containing the current status, the event history, and, in many cases, the geographic location of the package.
Event-driven querying is the most widespread model in digital logistics. This means your system does not wait for a fixed synchronization cycle, but instead fires the request when something relevant occurs: a confirmed order, an opened claim, or an exceeded time threshold. The result is a more precise and actionable chain of information than any conventional EDI integration can provide.
The typical response includes fields such as trackingCode, status, events[], and estimatedDelivery. Each event within the array carries its own code, description, and timestamp. That level of granularity makes it possible to build detailed timelines and trigger automatic alerts without manual intervention.
How is a tracking query authenticated and structured?
Authentication is the first point of failure in any integration. The API key is sent with every request, usually in the HTTP header. TrackRoad, for example, uses the X-API-Key header for its REST endpoints and SessionIDHeader for its SOAP services. Choosing between REST and SOAP depends on the carrier, although REST dominates in modern integrations due to its lower overhead and greater compatibility with current tooling.
The technical steps of a standard query are as follows:
- Obtain credentials from the carrier's portal and store them in environment variables, never in the source code.
- Build the HTTP request using the GET or POST method as specified by the carrier, including the authentication header.
- Include the shipment identifiers in the URL parameters or in the request body, such as
CompanyIDandTrackingCodein the Loggi API. - Process the response by parsing the received JSON or XML and mapping the fields to your own data model.
- Handle errors according to the returned HTTP code: 401 indicates an invalid or missing credential, 403 signals insufficient permissions or an exceeded call limit.
Distinguishing between a 401 and a 403 error in your logs speeds up incident resolution in production. A 401 points to a key problem; a 403 points to permissions or quotas. Confusing them unnecessarily prolongs diagnosis.
Pro tip: Always log the error code, timestamp, and shipment identifier for every failed call. That log lets you reconstruct the sequence of failures and detect patterns such as expired keys or carriers with recurring outages.
What is the difference between periodic polling and webhooks?
The integration architecture determines how quickly your system reflects a status change. There are two main models, and each has a clear use case.
Pull model (periodic polling):
- Your system sends requests to the carrier's API at a set interval, for example every 15 or 30 minutes.
- It is simple to implement and requires no additional infrastructure on your side.
- It generates unnecessary load on the carrier's server and can exceed hourly call limits.
- It introduces latency: if the package changes status right after your last query, you won't know until the next cycle.
Push model (webhooks):
- The carrier sends a real-time notification to one of your HTTPS endpoints every time there is a package movement.
- Your endpoint must respond with a 200 or 201 code to confirm receipt. If it does not respond, the carrier retries the delivery.
- It requires your endpoint to be public, stable, and capable of handling traffic spikes.
- It reduces latency to seconds and eliminates unnecessary consumption of your call quota.
Pro tip: Many teams combine both models: they use polling when creating a shipment to sync the initial history and then activate webhooks to receive real-time updates. This hybrid architecture requires deduplication logic to avoid duplicate states in the interface.
Deduplication is the most underestimated problem in tracking integrations. Implement an event engine with unique identifiers based on the combination of trackingCode, eventCode, and timestamp. This prevents you from displaying the same status twice when the webhook and polling coincide in time.
How are multiple carriers integrated into a single system?
Managing several carriers from a single system requires normalizing the data from each API into a common model. Each carrier uses its own status codes, response structures, and naming conventions. Without an abstraction layer, your code becomes a collection of special cases that is impossible to maintain.
The unified tracking object should include at least these fields:
| Field | Description | Example |
|---|---|---|
carrierId |
Carrier identifier | LOGGI, TRACKROAD |
trackingCode |
Unique shipment code | BR123456789 |
status |
Normalized status | IN_TRANSIT, DELIVERED |
events[] |
Ordered event history | Array with timestamp and description |
errorCode |
Typed error code | NOT_FOUND, PERMISSION_DENIED |
estimatedDelivery |
Estimated delivery date | 2026-03-15T14:00:00Z |
Handling typed errors such as NOT_FOUND or PERMISSION_DENIED makes it possible to distinguish whether a shipment does not exist, whether the credentials do not have access to that carrier, or whether the tracking code is incorrect. That distinction is critical for maintaining data quality and avoiding showing the customer a generic "error" status.
Building the event timeline is where the integration delivers the most value. Combine the event arrays from each carrier, sort them by timestamp, and normalize the descriptions to a common vocabulary. The result is a coherent shipment history that you can display in your dashboard or use to trigger automatic alerts, such as notifying a customer when their package has had no movement for more than 48 hours. To dive deeper into how to build this type of dashboard, the multi-carrier dashboard guide from Jetsend offers practical examples applied to the Spanish market.
What operational benefits do tracking APIs provide?
Tracking APIs transform logistics management from reactive to proactive. Instead of waiting for the customer to call and ask about their package, your system detects the problem first and acts.
| Criterion | Tracking API | Traditional EDI |
|---|---|---|
| Update frequency | Real-time or event-driven | Scheduled cycles (daily/weekly) |
| Integration flexibility | High, standard REST/JSON | Low, proprietary formats |
| Automatic alerts | Native via webhooks | Require additional development |
| Implementation cost | Low with modern APIs | High due to mapping complexity |
| E-commerce compatibility | Full | Limited |
APIs provide greater agility and more frequent visibility than EDI in digital logistics scenarios. This does not mean EDI is obsolete: the most common strategy in mid-sized and large companies is to keep EDI for high-volume documentary transactions and use APIs for operational visibility and on-demand services.
Current systems combine GPS, scans, and automatic notifications to manage the logistics chain from a centralized dashboard. That multi-channel integration is possible precisely because APIs allow heterogeneous data sources to be connected without the need for intermediaries. To better understand the differences between in-house tracking and carrier API tracking, the internal tracking comparison is a useful resource before deciding which architecture to adopt.
The reduction of manual errors is another direct benefit. Every status that previously required a phone call or a manual check on the carrier's website becomes structured data that your system processes automatically. This frees up time for the customer service team and measurably reduces operational costs.
Key Points
Integrating carrier tracking APIs requires proper authentication, a unified data model, and an architecture that combines polling and webhooks to ensure real-time visibility without duplicating statuses.
| Point | Details |
|---|---|
| Authentication as a foundation | Manage API keys in environment variables and distinguish 401 errors from 403 errors to resolve failures quickly. |
| Unified data model | Normalize each carrier's fields into a common schema with statuses, events, and error codes. |
| Hybrid architecture | Combine polling for initial synchronization and webhooks for real-time updates. |
| Event deduplication | Use unique identifiers per event to avoid duplicate statuses in the interface. |
| APIs vs. EDI | APIs offer higher update frequency and compatibility with modern digital platforms. |
Manage Your Shipments with Jetsend Without Technical Complexity
If your company operates in Spain and needs visibility across multiple carriers without building each integration from scratch, Jetsend solves that problem directly. The platform allows you to compare 13 carriers in a single click, print labels, and manage returns from a single dashboard. You don't need to be a developer to enjoy the benefits of advanced API integration: Jetsend abstracts all that complexity and turns it into a clean, accessible interface. In 2025, Jetsend users accumulated savings of up to 1.4 million euros in shipping costs. If you manage B2B or pallet shipments, the producers in Spain section also covers those needs with competitive rates and integrated tracking.
Frequently Asked Questions
What is a carrier tracking API?
A carrier tracking API is an interface that allows external systems to query the status and location of a shipment in real time through structured HTTP requests. It returns data such as the current status, event history, and estimated delivery date.
How is a call to a carrier API authenticated?
Authentication is performed by sending an API key in the header of each request, for example using the X-API-Key header in TrackRoad. 401 errors indicate an invalid or missing key, while 403 errors signal insufficient permissions or an exceeded quota.
When should you use webhooks instead of polling for tracking?
Webhooks are preferable when you need real-time updates and want to reduce call quota consumption. Polling is useful for synchronizing the initial history of a shipment or when the carrier does not offer webhooks.
How do I avoid duplicate statuses when combining polling and webhooks?
Implement an event engine with idempotency control using a unique identifier based on the combination of trackingCode, eventCode, and timestamp. This identifier allows already-processed events to be discarded before updating the database or the interface.
What advantage do tracking APIs have over EDI?
APIs offer real-time, per-event updates and are simpler to integrate with e-commerce platforms and modern dashboards. EDI remains useful for high-volume documentary transactions, but does not cover the operational visibility that today's customers demand.
