Tracking Endpoint & JSON Schema

HTTP Request

          HTTP GET
          Normalized Tracking Endpoint
        

GET https://api.cleartrackpromise.in/v1/track/:carrier/:awb

Note: :tracking_number is supported as an accepted path alias for :awb.

Path Parameters

Parameter	Type	Required	Description
`:carrier`	string	Yes	Canonical carrier slug or accepted alias (e.g. `indiapost`, `delhivery`, `bluedart`). See Supported Carriers.
`:awb`	string	Yes	Consignment number / AWB (8 to 40 characters, e.g. `CP100000001IN`).

Illustrative Response Payload

Below is an illustrative response from the tracking endpoint for an India Post consignment:

          JSON (Illustrative Example)
          200 OK
        

{
  "awb": "CP100000001IN",
  "tracking_number": "CP100000001IN",
  "carrier": "indiapost",
  "status": "delivered",
  "status_text": "Item Delivered",
  "is_delivered": true,
  "is_rto": false,
  "origin": {
    "office": null,
    "city": "New Delhi",
    "state": "Delhi",
    "pincode": null
  },
  "destination": {
    "office": null,
    "city": "Bengaluru",
    "state": "Karnataka",
    "pincode": null
  },
  "estimated_delivery_at": null,
  "delivered_at": "2026-10-08T14:30:00.000Z",
  "first_scan_at": "2026-10-05T10:15:00.000Z",
  "last_location": "Bengaluru",
  "last_known_location": "Bengaluru",
  "last_updated_at": "2026-10-08T14:30:00.000Z",
  "last_polled_at": "2026-10-08T14:35:00.000Z",
  "cached": true,
  "stale": false,
  "shipment": {
    "service_type": null,
    "weight_grams": null,
    "origin": {
      "office": null,
      "city": "New Delhi",
      "state": "Delhi",
      "pincode": null
    },
    "destination": {
      "office": null,
      "city": "Bengaluru",
      "state": "Karnataka",
      "pincode": null
    },
    "booked_at": "2026-10-05T10:15:00.000Z"
  },
  "milestones": {
    "booked_at": "2026-10-05T10:15:00.000Z",
    "picked_up_at": null,
    "in_transit_at": "2026-10-05T18:40:00.000Z",
    "out_for_delivery_at": "2026-10-07T08:00:00.000Z",
    "first_attempt_at": null,
    "delivered_at": "2026-10-08T14:30:00.000Z",
    "rto_initiated_at": null,
    "rto_delivered_at": null
  },
  "delivery_attempts": {
    "count": 1,
    "attempts": [
      {
        "at": "2026-10-08T14:30:00.000Z",
        "outcome": "delivered",
        "reason_code": null,
        "reason_text": null
      }
    ]
  },
  "insights": {
    "transit_days_elapsed": 3.2,
    "hours_since_last_scan": null,
    "is_stuck": false,
    "is_late_vs_carrier_edd": null,
    "delay_days_vs_carrier_edd": null,
    "hub_count": 2,
    "current_stage": "delivered",
    "requires_attention": false,
    "attention_reason": null,
    "benchmark": {
      "median_transit_days_for_route": null,
      "sample_size": null,
      "expected_delivery_by": null
    }
  },
  "events": [
    {
      "timestamp": "2026-10-08T14:30:00.000Z",
      "status": "delivered",
      "status_text": "Item Delivered",
      "code": "delivered",
      "facility": "Bengaluru",
      "location": "Bengaluru",
      "description": "Item Delivered"
    },
    {
      "timestamp": "2026-10-07T08:00:00.000Z",
      "status": "out_for_delivery",
      "status_text": "Item Out for Delivery",
      "code": "out_for_delivery",
      "facility": "Bengaluru",
      "location": "Bengaluru",
      "description": "Item Out for Delivery"
    },
    {
      "timestamp": "2026-10-06T09:20:00.000Z",
      "status": "in_transit",
      "status_text": "Item Received at Bengaluru NSH",
      "code": "received",
      "facility": "Bengaluru",
      "location": "Bengaluru",
      "description": "Item Received at Bengaluru NSH"
    },
    {
      "timestamp": "2026-10-05T18:40:00.000Z",
      "status": "in_transit",
      "status_text": "Item Dispatched to Delhi NSH",
      "code": "dispatched",
      "facility": "New Delhi",
      "location": "New Delhi",
      "description": "Item Dispatched to Delhi NSH"
    },
    {
      "timestamp": "2026-10-05T10:15:00.000Z",
      "status": "picked_up",
      "status_text": "Item Booked at New Delhi GPO",
      "code": "booked",
      "facility": "New Delhi",
      "location": "New Delhi",
      "description": "Item Booked at New Delhi GPO"
    }
  ]
}

Top-Level Response Fields

Field	Type	Description
`awb`	string	Tracking number requested.
`carrier`	string	Canonical courier identifier.
`status`	string	Normalized shipment status enum (e.g. `delivered`, `in_transit`, `out_for_delivery`). See Statuses.
`status_text`	string	Sanitized latest status description with all personal identifiable information stripped.
`is_delivered`	boolean	Terminal delivery status flag.
`is_rto`	boolean	Return to Origin flag indicating shipment is being or was returned to the sender.
`cached`	boolean	Whether response was served from cache.
`stale`	boolean	Whether cached data has reached maximum TTL.
`last_updated_at`	string (ISO)	Timestamp of the latest carrier scan event.
`origin`	object	Origin location object with `city`, `state`, and `pincode`.
`destination`	object	Destination location object with `city`, `state`, and `pincode`.
`delivery_attempts`	object	NDR attempt diagnostic counters and reasons. See NDR Codes.
`milestones`	object	Timestamps for `booked_at`, `in_transit_at`, `out_for_delivery_at`, and `delivered_at`.
`insights`	object	Diagnostic health metrics including `is_stuck` and `requires_attention`. See Insights.
`events`	array	Chronological checkpoint timeline with sanitized descriptions, locations, and codes.

Tracking Endpoint & Schema

HTTP Request

Path Parameters

Illustrative Response Payload

Top-Level Response Fields