Documentation

Core Integration Flows

Learn how to map customer entities and initiate SmartShield intents using secure session boundaries — stateful, token-scoped, and built for ecommerce scale.

v2.1 Stable Avg latency <80ms Session TTL: 15 min TLS 1.3 · HMAC-SHA256
flow-1

Device Session Init

The core of the Assurify ecosystem relies on creating stateful sessions for a given device. This lets our risk AI models verify hardware attributes before presenting pricing using BharatiWarrantyCost tiers. Each session carries a 15-minute TTL and scopes all downstream API calls.

Sandbox note: Use keys prefixed sk_sandbox_ for all test sessions. Production keys (sk_live_) require IP allowlisting and are rate-limited to 500 req/min.
01
Auth
Establish Handshake
Pass your sandbox secret key in the Authorization header as a Bearer token. All API requests must be made over HTTPS — plain HTTP calls will be rejected at the edge.
02
Request
Pass Device Parameters
Transmit IMEI, device model, and customer ID to the intent engine. The imei field must be a valid 15-digit GSMA IMEI — the risk engine performs checksum validation on intake.
03
Response
Store UserPlanIntent Token
The API returns a session_id scoping all downstream calls — risk analysis, plan fetch, and subscription attach. Tokens are single-use across plan purchase.
session/device/init
Python
JS
cURL
import requests

url     = "https://api.assurify.in/v1/session/device/init"
headers = {"Authorization": "Bearer sk_sandbox_..."}
payload = {
    "imei":     "351234567890123",
    "customer": "cust_84920kL",
    "model":    "Samsung Galaxy S23"
}

resp = requests.post(url, json=payload, headers=headers)
data = resp.json()
session_id = data["data"]["session_id"]
const resp = await fetch('https://api.assurify.in/v1/session/device/init', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer sk_sandbox_...'
  },
  body: JSON.stringify({
    imei:     "351234567890123",
    customer: "cust_84920kL",
    model:    "Samsung Galaxy S23"
  })
});
const { data } = await resp.json();
const sessionId = data.session_id;
curl -X POST 'https://api.assurify.in/v1/session/device/init' \
  -H 'Authorization: Bearer sk_sandbox_...' \
  -H 'Content-Type: application/json' \
  -d '{
    "imei":     "351234567890123",
    "customer": "cust_84920kL",
    "model":    "Samsung Galaxy S23"
  }'
Response 200 OK 
{
  "status": "success",
  "data": {
    "session_id":       "sess_9xLop21Z",
    "device_verified":  true,
    "risk_score":       0.05,
    "eligible_products": ["EW", "ADLD"],
    "expires_at":       "2026-03-24T18:00:00Z"
  }
}
Request Parameters
Parameter Type Required Description
imei string required 15-digit GSMA IMEI. Validated via Luhn checksum on intake.
customer string required Your internal customer ID. Prefixed cust_.
model string optional Device model string for OEM rule matching. Improves plan precision.
geography string optional ISO 3166-1 alpha-2 country code. Defaults to IN if omitted.
flow-2

Subscription Purchase

Once a session is established and risk verified, your application retrieves eligible SmartShield tiers — Extended Warranty, ADLD, or Screen Protection — and commits the customer's chosen plan. Pricing is calculated dynamically against BharatiWarrantyCost limits and device model rules.

Fetch Eligible Plans
Use the session token to retrieve dynamically calculated plan options. Coverage values and pricing tiers vary by geography, device condition, and OEM agreement rules.
GET /v1/plans/eligible?session_id=...
Commit & Bind Policy
Finalize the purchase and bind the selected SmartShield policy ID to the customer record. Triggers a policy.activated webhook within 200ms of commitment.
POST /v1/subscription/attach
01
GET Plans
Retrieve Eligible Tiers
Pass the session_id from Step 1 to retrieve available SmartShield plans with computed pricing. Response includes coverage type, premium amount, and BharatiWarrantyCost validity flag.
02
POST
Attach Subscription
POST the chosen plan_id alongside the session token to finalize and bind the policy to the customer record in our underwriting system.
03
Webhook
Receive Policy Webhook
A policy.activated event fires to your configured webhook endpoint with the full policy object and subscription_id for your records.
subscription/attach
Python
JS
cURL
# Step 1 — fetch eligible plans
plans_resp = requests.get(
    "https://api.assurify.in/v1/plans/eligible",
    params={"session_id": session_id},
    headers=headers
)
plans = plans_resp.json()["data"]["plans"]

# Step 2 — attach chosen plan
attach = requests.post(
    "https://api.assurify.in/v1/subscription/attach",
    json={
        "session_id": session_id,
        "plan_id":    "extended_warranty",
        "customer":   "cust_84920kL"
    },
    headers=headers
)
policy = attach.json()["data"]
// Step 1 — fetch eligible plans
const plansRes = await fetch(
  `https://api.assurify.in/v1/plans/eligible?session_id=${sessionId}`,
  { headers: { 'Authorization': 'Bearer sk_sandbox_...' } }
);
const { data: { plans } } = await plansRes.json();

// Step 2 — attach chosen plan
const attachRes = await fetch('https://api.assurify.in/v1/subscription/attach', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer sk_sandbox_...'
  },
  body: JSON.stringify({
    session_id: sessionId,
    plan_id:    "extended_warranty",
    customer:   "cust_84920kL"
  })
});
const { data: policy } = await attachRes.json();
# Fetch plans
curl 'https://api.assurify.in/v1/plans/eligible?session_id=sess_9xLop21Z' \
  -H 'Authorization: Bearer sk_sandbox_...'

# Attach plan
curl -X POST 'https://api.assurify.in/v1/subscription/attach' \
  -H 'Authorization: Bearer sk_sandbox_...' \
  -H 'Content-Type: application/json' \
  -d '{"session_id":"sess_9xLop21Z","plan_id":"extended_warranty","customer":"cust_84920kL"}'
Response 200 OK 
{
  "subscription_id": "sub_XQ9182KJ",
  "plan_id":         "extended_warranty",
  "price_inr":       599,
  "bharati_valid":   true,
  "activated_at":    "2026-03-25T10:00:00Z"
}
flow-3

Claims OCR Analysis

Assurify's claims flow is highly automated. Bypass manual verification entirely by sending base64-encoded invoice images to the OCR engine. The AI evaluates vendor authenticity, repair amounts, and device serial matching — returning a payout decision in under 100ms.

Async processing: OCR evaluation is asynchronous when the risk engine flags an invoice for manual review. In these cases, the initial response returns status: "pending". A claim.decision webhook fires to your endpoint when AI evaluation concludes — typically within 30 seconds.
Async Webhook Flow
POST /claims/ocr/verify
→
AI Risk Engine
→
OCR · Invoice Parse
→
claim.decision webhook
01
Encode
Prepare Base64 Assets
Convert your invoice image and front-panel photo to base64 strings. Supported formats: JPEG, PNG, WEBP. Maximum payload size: 10MB per image.
02
POST
Submit OCR Payload
Send the claim reference, session token, damage type, and encoded images to /claims/ocr/verify. The mode field controls risk engine strictness: AUTO, STRICT, or LENIENT.
03
Webhook
Handle Decision & Payout
Receive claim.decision on your webhook URL. The payload includes extracted invoice fields, confidence score, risk flags, and — if approved — a payout_id for reconciliation.
claims/ocr/verify
Python
JS
cURL
import requests, base64

with open("invoice.jpg", "rb") as f:
    invoice_b64 = base64.b64encode(f.read()).decode()

with open("front_panel.jpg", "rb") as f:
    front_b64 = base64.b64encode(f.read()).decode()

resp = requests.post(
    "https://api.assurify.in/v1/claims/ocr/verify",
    json={
        "session_token": "sess_9xLop21Z",
        "claim_ref":     "clm_TY29183K",
        "claim_type":    "accidental_damage",
        "mode":          "AUTO",
        "images": {
            "invoice":     invoice_b64,
            "front_panel": front_b64
        }
    },
    headers=headers
)
const toB64 = file => new Promise((res, rej) => {
  const r = new FileReader();
  r.onload = () => res(r.result.split(',')[1]);
  r.onerror = rej;
  r.readAsDataURL(file);
});

const [invoiceB64, frontB64] = await Promise.all([
  toB64(invoiceFile), toB64(frontPanelFile)
]);

const resp = await fetch('https://api.assurify.in/v1/claims/ocr/verify', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer sk_sandbox_...'
  },
  body: JSON.stringify({
    session_token: "sess_9xLop21Z",
    claim_ref:     "clm_TY29183K",
    claim_type:    "accidental_damage",
    mode:          "AUTO",
    images: { invoice: invoiceB64, front_panel: frontB64 }
  })
});
curl -X POST 'https://api.assurify.in/v1/claims/ocr/verify' \
  -H 'Authorization: Bearer sk_sandbox_...' \
  -H 'Content-Type: application/json' \
  -d '{
    "session_token": "sess_9xLop21Z",
    "claim_ref":     "clm_TY29183K",
    "claim_type":    "accidental_damage",
    "mode":          "AUTO",
    "images": {
      "invoice":     "'$(base64 invoice.jpg)'",
      "front_panel": "'$(base64 front.jpg)'"
    }
  }'
Webhook Payload claim.decision 
{
  "claim_ref":      "clm_TY29183K",
  "decision":       "APPROVED",
  "ocr_confidence": 0.94,
  "risk_flags":     ["amount_above_threshold"],
  "extracted": {
    "vendor":  "Croma Retail Ltd.",
    "amount":  8450.00,
    "invoice": "INV-20240312-0042"
  },
  "payout_id":      "pay_A9KX01ZW"
}
You're all set. After handling the claim.decision webhook, use the payout_id to reconcile disbursements and update your customer portal. For claim status polling, use GET /v1/claims/{id}/status — though webhook delivery is strongly preferred for latency-sensitive flows.