Home / API

Integration options.

Structured payloads for shipment tracking, events, and reporting. Designed to support future API integration with your systems.

Patterns

Integrate with your systems.

REST-style endpoints

Shipment creation, milestone events, tracking reads, and standardized response codes.

Webhook events

Push-based notifications for milestone changes and exceptions.

Statements export

Periodic reporting files for governance workflows.

Idempotency concepts

Retry-safe patterns for shipment creation and updates.

Sample

Example payload

{
  "trackingNumber": "HGX129047381",
  "status": "in_transit",
  "currentLocation": {
    "city": "Frankfurt",
    "country": "DE"
  },
  "eta": "2026-03-26",
  "milestones": [
    { "code": "processing", "at": "2026-03-20T09:14:00Z" },
    { "code": "in_transit", "at": "2026-03-21T06:05:00Z" },
    { "code": "customs_clearance", "at": null },
    { "code": "delivered", "at": null }
  ],
  "history": [
    {
      "at": "2026-03-20T22:30:00Z",
      "event": "departed_origin_hub",
      "location": "London, UK"
    }
  ]
}

Example schema to align terminology, event codes, and reporting fields.

Endpoints

Suggested routes

Method	Path	Description
GET	/v1/shipments/{trackingNumber}	Read shipment status and milestone history
POST	/v1/shipments	Create a shipment record (idempotent pattern)
POST	/v1/webhooks	Register a webhook destination
GET	/v1/reports/monthly	Download monthly statements
GET	/v1/pricing	Read service tiers and capabilities
GET	/v1/notifications/schema	List webhook events and payload definitions

Sample data

Schemas and examples

Use these JSON examples to review fields, event codes, and response shapes before connecting live systems.

Tracking

/assets/data/tracking-samples.json

Pricing

/assets/data/pricing.json

Notifications

/assets/data/notifications.json

Client usage

Example (jQuery)

HGApi.getTrackingSamples().then(function (samples) {
  var item = samples["HGX129047381"];
  console.log(item.status, item.location);
});

HGApi.getPricing().then(function (pricing) {
  console.log(pricing.tiers.length);
});