Carrier Integration

India Post Tracking API

Track India Post and Speed Post consignments through a unified REST JSON API with normalized lifecycle statuses and standardized checkpoint history.

Get a free API key

cURL Integration Example

Query live consignment tracking data by passing your ClearTrack API key in the X-API-Key request header:

          cURL
          GET /v1/track/indiapost/:awb
        

curl -s -H "X-API-Key: YOUR_API_KEY" \
  "https://api.cleartrackpromise.in/v1/track/indiapost/CP999999999IN"

Sample JSON Response

ClearTrack returns a standardized JSON payload with normalized status enums, milestone timestamps, diagnostic insights, and sanitized checkpoint events:

          JSON (Illustrative Example)
          200 OK
        

{
  "awb": "CP999999999IN",
  "tracking_number": "CP999999999IN",
  "carrier": "indiapost",
  "status": "in_transit",
  "status_text": "Item Dispatched from Sorting Hub",
  "is_delivered": false,
  "is_rto": false,
  "origin": {
    "office": "Bengaluru GPO",
    "city": "Bengaluru",
    "state": "Karnataka",
    "pincode": "560001"
  },
  "destination": {
    "office": "Mumbai GPO",
    "city": "Mumbai",
    "state": "Maharashtra",
    "pincode": "400001"
  },
  "estimated_delivery_at": "2026-10-18T18:00:00.000Z",
  "delivered_at": null,
  "first_scan_at": "2026-10-14T06:30:00.000Z",
  "last_location": "Mumbai National Sorting Hub",
  "last_known_location": "Mumbai National Sorting Hub",
  "last_updated_at": "2026-10-16T12:00:00.000Z",
  "last_polled_at": "2026-10-16T12:00:00.000Z",
  "cached": true,
  "stale": false,
  "shipment": {
    "service_type": "speed_post",
    "weight_grams": 350,
    "origin": {
      "office": "Bengaluru GPO",
      "city": "Bengaluru",
      "state": "Karnataka",
      "pincode": "560001"
    },
    "destination": {
      "office": "Mumbai GPO",
      "city": "Mumbai",
      "state": "Maharashtra",
      "pincode": "400001"
    },
    "booked_at": "2026-10-14T06:30:00.000Z"
  },
  "milestones": {
    "booked_at": "2026-10-14T06:30:00.000Z",
    "picked_up_at": "2026-10-14T07:00:00.000Z",
    "in_transit_at": "2026-10-14T08:30:00.000Z",
    "out_for_delivery_at": null,
    "first_attempt_at": null,
    "delivered_at": null,
    "rto_initiated_at": null,
    "rto_delivered_at": null
  },
  "delivery_attempts": {
    "count": 0,
    "attempts": []
  },
  "insights": {
    "transit_days_elapsed": 2.2,
    "hours_since_last_scan": 3.5,
    "is_stuck": false,
    "is_late_vs_carrier_edd": false,
    "delay_days_vs_carrier_edd": null,
    "hub_count": 2,
    "current_stage": "in_transit",
    "requires_attention": false,
    "attention_reason": null,
    "benchmark": {
      "median_transit_days_for_route": null,
      "sample_size": null,
      "expected_delivery_by": null
    }
  },
  "events": [
    {
      "timestamp": "2026-10-16T12:00:00.000Z",
      "status": "in_transit",
      "status_text": "Item Dispatched from Sorting Hub",
      "code": "dispatched",
      "facility": "Mumbai National Sorting Hub",
      "location": "Mumbai",
      "description": "Item Dispatched from Sorting Hub"
    },
    {
      "timestamp": "2026-10-14T06:30:00.000Z",
      "status": "picked_up",
      "status_text": "Item Booked",
      "code": "booked",
      "facility": "Bengaluru GPO",
      "location": "Bengaluru",
      "description": "Item Booked"
    }
  ]
}

Status Mapping: India Post to Normalized Status

Raw status updates and checkpoint descriptions emitted by India Post are mapped into standardized top-level status values and granular code identifiers:

Carrier Raw Status	Normalized Status (`status`)	Event Code (`code`)	Description
Item Booked	`picked_up`	`booked`	Consignment registered at origin booking post office.
Item Bagged	`in_transit`	`bagged`	Article placed in dispatch bag at booking post office.
Item Dispatched / Despatched	`in_transit`	`dispatched`	Bag dispatched to National Sorting Hub (NSH) or transit mail office.
Item Received	`in_transit`	`received`	Consignment scanned and verified at intermediate postal sorting center.
Out for Delivery	`out_for_delivery`	`out_for_delivery`	Article handed over to postman beat for doorstep delivery attempt.
Item Delivered / Article Delivered	`delivered`	`delivered`	Consignment successfully delivered to recipient (terminal state).
Door Locked / Addressee Absent	`returned`	`delivery_attempted`	Delivery attempt failed; consignment held at local branch office for re-attempt.
Item Returned to Sender	`returned`	`rto_delivered`	Undelivered article returned to origin booking office (RTO terminal state).

For the comprehensive lifecycle specification across all couriers, see the Shipment Statuses Reference.

Non-Delivery Report (NDR) Reasons

When delivery attempts fail, ClearTrack normalizes unstructured failure remarks into canonical NDR reason codes inside the delivery_attempts array:

Normalized Reason Code	Diagnostic Category	Meaning
`customer_unavailable`	Customer Unavailable	Addressee absent, not available at premises, or unclaimed during holding period.
`address_issue`	Address Issue	Insufficient address, incorrect pin code, or addressee moved.
`refused`	Customer Refused	Addressee refused to accept consignment or rejected payment.
`premises_closed`	Premises Closed	Door locked, office closed, or premises inaccessible during postman beat.
`cod_not_ready`	COD Payment Not Ready	Value Payable (VP) / COD cash amount not ready at doorstep.
`other`	Operational Exception	Postal sorting delay, transport connection hold, or local holiday.

Learn how to automate buyer re-attempt outreach in our NDR Reason Codes Documentation.

AWB Format

India Post consignment numbers are 13-character alphanumeric codes consisting of 2 prefix letters (such as E, C, or R for Speed Post, Parcel Post, or Registered Post), 9 digits, and the country suffix IN (for example, CP999999999IN). Pass the 13-character identifier directly into the :awb path parameter.

Frequently Asked Questions

Does India Post have an official tracking API?

India Post (Department of Posts) does not provide a public self-serve REST API for developers. While corporate customers with bulk Speed Post agreements may access departmental portals or FTP/EDI data feeds, there is no open developer API. ClearTrack normalizes India Post consignments into a modern JSON API without requiring departmental contracts.

Which India Post service types are supported by the API?

The tracking API supports Speed Post, Registered Post, and standard parcel consignments using standard India Post consignment identifiers.

Do I need an India Post account to use ClearTrack?

No. You do not need a Department of Posts account, commercial license, or departmental credentials. ClearTrack queries consignment telemetry via your ClearTrack API key.

How fresh is the tracking data?

Active in-transit consignments are cached for up to 30 minutes, providing fast response times while protecting against postal server downtime. Terminal states (delivered, returned, and cancelled) are cached permanently.

What does the tracking API cost?

Pricing is pay-as-you-go based on lookups in Indian Rupees (₹), ranging from ₹0.25 to ₹0.27 per lookup across prepaid plans with no recurring mandates. We offer a free 14-day trial with 100 lookups for business accounts. View our full pricing plans on the pricing page.