Courier Tracking REST API Documentation

curl -s -H "X-API-Key: ct_live_your_api_key_here" \
  "https://api.cleartrackpromise.in/v1/track/delhivery/123456789012"

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

{
  "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"
    }
  ]
}

# Track a Blue Dart consignment
curl -s -X GET "https://api.cleartrackpromise.in/v1/track/bluedart/12345678901" \
  -H "X-API-Key: ct_live_your_api_key_here" \
  -H "Accept: application/json"

async function trackShipment(carrier, awb) {
  const apiKey = process.env.CLEARTRACK_API_KEY || "ct_live_your_api_key_here";
  const url = `https://api.cleartrackpromise.in/v1/track/${encodeURIComponent(carrier)}/${encodeURIComponent(awb)}`;

  const response = await fetch(url, {
    method: "GET",
    headers: {
      "X-API-Key": apiKey,
      "Accept": "application/json",
    },
  });

  const data = await response.json();
  if (!response.ok) {
    throw new Error(`Tracking API Error (${response.status}): ${data.error?.message || "Unknown error"}`);
  }

  console.log("Status:", data.status);
  console.log("Delivered:", data.is_delivered);
  console.log("Current Stage:", data.insights?.current_stage);
  return data;
}

// Example usage
trackShipment("delhivery", "123456789012").catch(console.error);

import os
import requests

def track_shipment(carrier: str, awb: str) -> dict:
    api_key = os.getenv("CLEARTRACK_API_KEY", "ct_live_your_api_key_here")
    url = f"https://api.cleartrackpromise.in/v1/track/{carrier}/{awb}"
    headers = {
        "X-API-Key": api_key,
        "Accept": "application/json"
    }

    response = requests.get(url, headers=headers, timeout=15)
    response.raise_for_status()
    data = response.json()

    print(f"Status: {data.get('status')}")
    print(f"Delivered: {data.get('is_delivered')}")
    print(f"Stage: {data.get('insights', {}).get('current_stage')}")
    return data

if __name__ == "__main__":
    track_shipment("indiapost", "CP100000001IN")

<?php

function trackShipment(string $carrier, string $awb): array {
    $apiKey = getenv('CLEARTRACK_API_KEY') ?: 'ct_live_your_api_key_here';
    $url = "https://api.cleartrackpromise.in/v1/track/" . rawurlencode($carrier) . "/" . rawurlencode($awb);

    $ch = curl_init();
    curl_setopt_array($ch, [
        CURLOPT_URL => $url,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HTTPHEADER => [
            "X-API-Key: {$apiKey}",
            "Accept: application/json",
        ],
        CURLOPT_TIMEOUT => 15,
    ]);

    $response = curl_exec($ch);
    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);

    $data = json_decode($response, true);
    if ($httpCode >= 400) {
        $message = $data['error']['message'] ?? 'API error';
        throw new Exception("ClearTrack API Error ({$httpCode}): {$message}");
    }

    return $data;
}

// Example usage
$result = trackShipment('delhivery', '123456789012');
echo "Status: " . $result['status'] . PHP_EOL;
echo "Stage: " . ($result['insights']['current_stage'] ?? 'unknown') . PHP_EOL;