iChek Address API

Make sure every customer gives you a delivery address that actually works. iChek fills in city and state from the PIN code, catches wrong or incomplete addresses while the customer is still typing, and returns a clean, standardized address you can ship to.

Quick start

1. Create an account. The free plan includes 1,000 checks a month.
2. Open Install & settings in your dashboard. You get two keys:
   • pk_… is the publishable key. It's safe to put in web pages and is used by the widget.
   • sk_… is the secret key. It's for your server only. Never put it in a web page or app.
3. Pick how you connect:

   You have…	Use	Coding needed
   Any website checkout (custom, Magento, OpenCart…)	Checkout widget: one script tag	Paste one line
   WooCommerce	WordPress plugin	None
   Your own backend or mobile app	REST API	A few lines
   A spreadsheet of existing addresses	Bulk upload in the dashboard	None

4. Before going live, add your website domain under Allowed website domains so your publishable key only works on your site.

Checkout widget

Paste this on your checkout or address page, just before </body>. Use your own publishable key:

<script src="https://api.isectrain.com/widget.js" data-key="pk_YOUR_KEY" async></script>

That's all. The widget finds the address fields on the page by itself, including forms that appear later, like WooCommerce's. Then it:

• fills city and state as soon as a valid PIN code is typed (it works with text boxes and state drop-downs)
• checks the address when the customer leaves a field, and shows hints right under the address box
• offers a "Use this address" button with the cleaned-up version
• adds hidden fields to your form so your server receives the result: ichek_status, ichek_score, ichek_check_id

Options

Point it at your fields (optional)

<script src="https://api.isectrain.com/widget.js" data-key="pk_YOUR_KEY" data-auto="false"></script>
<script>
  iChek.attach({
    pincode: '#zip', city: '#city', state: '#state',
    line1: '#address1', line2: '#address2', landmark: '#landmark', phone: '#phone',
    onResult: function (r) { console.log(r.status, r.score, r.standardized.full); }
  });
</script>

Every check also fires an ichek:result event on the form, with the result in event.detail.

WooCommerce plugin

1. Download ichek-woocommerce.zip.
2. In WordPress, go to Plugins → Add New → Upload Plugin, choose the zip, then Install and Activate.
3. Go to WooCommerce → iChek and paste your publishable key. The iChek URL is already filled in. Click Save.

The widget now runs on your checkout and cart pages. Each order stores the address check result, which shows in the order screen under the shipping address.

REST API

POST/address/verify

Checks one address and returns a score, the problems found, hints to show the customer and a standardized address.

curl -X POST https://api.isectrain.com/api/v1/address/verify \
  -H "X-API-Key: sk_YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"line1":"flat 204 lotus towers, 5th cross","line2":"indiranagar",
       "city":"Bangalore","state":"KA","pincode":"560038","phone":"+91 98765 43210"}'

<?php
$ch = curl_init('https://api.isectrain.com/api/v1/address/verify');
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ['X-API-Key: sk_YOUR_SECRET_KEY', 'Content-Type: application/json'],
  CURLOPT_POSTFIELDS => json_encode([
    'line1' => 'flat 204 lotus towers, 5th cross', 'line2' => 'indiranagar',
    'city' => 'Bangalore', 'state' => 'KA', 'pincode' => '560038', 'phone' => '+91 98765 43210',
  ]),
]);
$r = json_decode(curl_exec($ch), true);
if ($r['status'] === 'INVALID') {
  // ask the customer to fix: implode("\n", $r['suggestions'])
}
echo $r['standardized']['full'];

import requests

r = requests.post(
    "https://api.isectrain.com/api/v1/address/verify",
    headers={"X-API-Key": "sk_YOUR_SECRET_KEY"},
    json={"line1": "flat 204 lotus towers, 5th cross", "line2": "indiranagar",
          "city": "Bangalore", "state": "KA", "pincode": "560038", "phone": "+91 98765 43210"},
    timeout=10,
).json()

print(r["status"], r["score"], r["standardized"]["full"])
for hint in r["suggestions"]:
    print("-", hint)

// Node 18+ (server side; never expose sk_ keys in the browser)
const res = await fetch("https://api.isectrain.com/api/v1/address/verify", {
  method: "POST",
  headers: { "X-API-Key": "sk_YOUR_SECRET_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({ line1: "flat 204 lotus towers, 5th cross", line2: "indiranagar",
    city: "Bangalore", state: "KA", pincode: "560038", phone: "+91 98765 43210" }),
});
const r = await res.json();
console.log(r.status, r.score, r.standardized.full);

Response: a good address

{
  "score": 95,
  "status": "VERIFIED",
  "standardized": {
    "line1": "Flat 204 Lotus Towers, 5th Cross",
    "line2": "Indiranagar",
    "landmark": "",
    "city": "Bangalore",
    "state": "Karnataka",
    "pincode": "560038",
    "country": "IN",
    "full": "Flat 204 Lotus Towers, 5th Cross, Indiranagar, Bangalore, Karnataka 560038"
  },
  "issues": [
    { "code": "NO_LANDMARK", "severity": "info", "message": "No landmark given", "penalty": 5 }
  ],
  "suggestions": [ "Add a nearby landmark (helps the courier)" ],
  "pincode_info": { "pin": "560038", "found": true, "state": "Karnataka",
                    "districts": ["Bengaluru"], "offices": ["HAL II Stage", "Indiranagar"] },
  "location": null,
  "phone": "9876543210",
  "phone_valid": true,
  "country": "IN"
}

Response: an address that needs fixing ("line1": "near temple", "state": "Bihar", "pincode": "560038")

{
  "score": 40,
  "status": "INVALID",
  "issues": [
    { "code": "STATE_PIN_MISMATCH", "severity": "error", "message": "PIN 560038 belongs to Karnataka, not Bihar", "penalty": 25 },
    { "code": "LINE_SHORT",  "severity": "warn", "message": "Address is very short", "penalty": 20 },
    { "code": "NO_HOUSE_NO", "severity": "warn", "message": "No house / flat / plot number", "penalty": 15 }
  ],
  "suggestions": [
    "PIN and state don't match — is the PIN or the state wrong? (Karnataka)",
    "Add building, street and area",
    "Add house or flat number"
  ],
  ...
}

GET/pincode/{pin}

Looks up a PIN code and returns its state, districts and post offices. Useful for building your own auto-fill.

curl https://api.isectrain.com/api/v1/pincode/560038 -H "X-API-Key: sk_YOUR_SECRET_KEY"

{ "pin": "560038", "valid_format": true, "found": true, "state": "Karnataka",
  "districts": ["Bengaluru"], "offices": ["HAL II Stage", "Indiranagar"], "source": "api" }

found is false when the PIN doesn't exist. It is null when only the PIN's range could be checked, because the lookup service was unreachable.

Response fields

Issue codes

Bulk CSV / Excel

In the dashboard, go to Bulk upload → Addresses and upload a .csv or .xlsx file of up to 5,000 rows. Column names are matched flexibly ("Pin Code", "Mobile", "Address 1", Shopify/WooCommerce exports…). You get a score, status, standardized address and hints for every row, and can download the results as CSV.

From code: POST /api/v1/bulk/verify with multipart fields file and mode=addresses.

Errors & limits

RTO risk scoring PRO

For COD-heavy stores. Every order gets a risk level (LOW / REVIEW / HIGH) with reasons. The score uses address quality, COD vs prepaid, order value, the customer's past RTOs and failed deliveries, one phone used with many addresses (or one address with many phones), the PIN code's RTO rate and bursts of orders. Your team works a review queue (call, then Verify or Reject) before dispatch. Courier outcomes flow back, so the rules can be tuned from real results.

Downloads

• WooCommerce plugin (zip)
• OpenAPI specification (import into Postman, Insomnia, or code generators)
• Sample addresses CSV for trying bulk upload
• widget.js (source, no dependencies)

PIN code data: India Post. Questions? Contact us through ichek.info.