ClaimProof API

Quick start

1. Get a tenant. Tenants are created by Ward Tech during onboarding (request a pilot). You receive one API key — shown once — and portal access.
2. Check connectivity.

curl https://claimproof.wardtechsystems.com/v1/health
# {"ok":true,"engine":"mesh-fi/0.1","version":"…","time":"…"}

3. Analyse your first photo — under 60 seconds from key to verdict.

curl -X POST https://claimproof.wardtechsystems.com/v1/analyze \
  -H "Authorization: Bearer cp_live_…" \
  -F "image=@roof.jpg"

{
  "id": "ana_7f3c…",
  "analysis": { "engine": "mesh-fi/0.1", "verdict": "edited_likely", "score": 0.78, "confidence": 0.71, "…": "…" },
  "annotatedUrl": "https://claimproof.wardtechsystems.com/v1/files/tenants/…/annotated.jpg?sig=…&exp=…",
  "storedUntil": "2027-02-08T00:00:00Z"
}

Then read verdict semantics before wiring any automation to the result.

Authentication

Every request except /v1/health, /v1/demo/analyze, /v1/leads and /v1/portal/session needs a bearer token:

Authorization: Bearer cp_live_0123456789abcdef0123456789abcdef

• Keys look like cp_live_ + 32 hex characters. We store only a SHA-256 hash; the plaintext is shown once at creation.
• Keys carry scopes: analyze, claims, read (default all three) and admin. A call outside the key's scopes returns 401 UNAUTHORIZED.
• The portal exchanges a key for a 24-hour session token via POST /v1/portal/session; the API accepts either interchangeably in the Authorization header.
• Rotate by asking support for a new key, moving traffic, then revoking the old one. Self-service rotation is on the roadmap.

Keep keys server-side. Never embed a cp_live_ key in a browser or mobile app — use your own backend as the proxy.

Rate limits & quotas

Every response carries X-RateLimit-Limit and X-RateLimit-Remaining. A 429 RATE_LIMITED response also carries Retry-After (seconds). Back off and retry; do not spin.

An image is one photo analysed — via /v1/analyze or as part of a claim. Rejected files, re-reads and reports are not counted. See /v1/usage.

Single image analysis

Synchronous. Returns within ~25 s (typically 2–8 s). Accepts either multipart form data or JSON with URLs.

Request (multipart)

Request (JSON)

{ "imageUrl": "https://…/photo.jpg", "referenceUrl": "https://…/original.jpg", "context": { "lossDate": "2026-05-14", "peril": "hail" } }

Query

?store=false — analyse without persisting anything. The response then contains annotatedBase64 instead of annotatedUrl, and no id is retrievable later.

Response 200

{
  "id": "ana_…",
  "analysis": { /* AnalysisResult — see reference */ },
  "annotatedUrl": "…signed, 7-day…",
  "sideBySideUrl": "…only when reference was supplied…",
  "storedUntil": "ISO-8601 (retention)"
}

Examples

curl -X POST "https://claimproof.wardtechsystems.com/v1/analyze?store=false" \
  -H "Authorization: Bearer $CLAIMPROOF_KEY" \
  -F "image=@roof.jpg" \
  -F "reference=@roof_original.jpg" \
  -F 'context={"lossDate":"2026-05-14","peril":"hail","lossLocation":{"lat":32.93,"lng":-96.9}}'

import { readFile } from 'node:fs/promises';

export async function analyze(path, context) {
  const form = new FormData();
  form.append('image', new Blob([await readFile(path)], { type: 'image/jpeg' }), 'photo.jpg');
  if (context) form.append('context', JSON.stringify(context));
  const res = await fetch('https://claimproof.wardtechsystems.com/v1/analyze', {
    method: 'POST',
    headers: { Authorization: `Bearer ${process.env.CLAIMPROOF_KEY}` },
    body: form,
  });
  if (!res.ok) {
    const { error } = await res.json();
    throw new Error(`${error.code}: ${error.message} (request ${error.requestId})`);
  }
  return res.json(); // { id, analysis, annotatedUrl, storedUntil }
}

import json, os, requests

def analyze(path: str, context: dict | None = None) -> dict:
    r = requests.post(
        "https://claimproof.wardtechsystems.com/v1/analyze",
        headers={"Authorization": f"Bearer {os.environ['CLAIMPROOF_KEY']}"},
        files={"image": open(path, "rb")},
        data={"context": json.dumps(context)} if context else None,
        timeout=60,
    )
    if r.status_code >= 400:
        err = r.json()["error"]
        raise RuntimeError(f"{err['code']}: {err['message']} (request {err['requestId']})")
    return r.json()

Returns a stored single analysis (same shape as the POST response) until storedUntil.

Claims & multi-photo

A claim groups photos so they can be checked against each other and against your other claims. Photos are analysed asynchronously by a queue; the ClaimReport is built when the last photo finishes.

{
  "claimNumber": "HO-2026-48211",          // required
  "policyNumber": "P-99812",
  "peril": "hail",                          // hail|wind|water|fire|auto|theft|other
  "lossDate": "2026-05-14",
  "lossLocation": { "lat": 32.93, "lng": -96.9, "address": "…" },
  "insured": { "name": "…", "email": "…" },
  "expectedDevice": "iPhone 15 Pro",
  "webhookUrl": "https://claims.example.com/hooks/claimproof",   // per-claim override
  "metadata": { "adjusterId": "A-114" }     // free-form, echoed back
}

201 { "id": "clm_…", "status": "open",
      "uploadUrls": { "photos": "/v1/claims/clm_…/photos", "zip": "/v1/claims/clm_…/zip" } }

Multipart, 1–50 files per request in field photos[] (or a single photo). Up to 200 photos per claim. Each accepted photo is stored and queued immediately.

202 { "claimId": "clm_…", "status": "processing",
      "accepted": [ { "photoId": "pho_…", "filename": "IMG_0412.jpg", "bytes": 2817771 } ],
      "rejected": [ { "filename": "notes.pdf", "reason": "UNSUPPORTED_FORMAT" } ] }

{
  "id": "clm_…", "claimNumber": "HO-2026-48211",
  "status": "open" | "processing" | "complete" | "failed",
  "counts": { "total": 12, "done": 12, "failed": 0 },
  "photos": [ { "photoId": "pho_…", "filename": "…", "status": "done", "verdict": "authentic_likely",
                "score": 0.12, "confidence": 0.81, "thumbUrl": "…", "annotatedUrl": "…" } ],
  "report": null | { /* ClaimReport */ }
}

Full per-photo detail: { photoId, filename, status, analysis, originalUrl, annotatedUrl }.

json returns the ClaimReport; html returns a branded, printable page. Because browsers cannot attach headers to a new tab, the HTML variant also accepts the bearer credential as ?token= — on this endpoint only.

Paged list, newest first. Follow nextCursor until it is absent.

Deletes the claim, its photos, analyses and stored files. 204. Irreversible.

ZIP ingestion

Send the archive your claims system already produces. Either a raw application/zip body or multipart with field zip. Up to 50 MB; the central directory is budgeted before anything is inflated (≤ 60 MB of declared image bytes, ≤ 200 entries).

curl -X POST https://claimproof.wardtechsystems.com/v1/claims/clm_…/zip \
  -H "Authorization: Bearer $CLAIMPROOF_KEY" \
  -H "Content-Type: application/zip" \
  --data-binary @HO-2026-48211.zip
# 202 { "claimId": "clm_…", "workflowId": "…", "status": "unpacking" }

A durable workflow unpacks the archive, skips non-images, __MACOSX entries and files over 25 MB, creates photo rows and queues each one. Poll GET /v1/claims/:id — counts.total grows as entries are accepted — or wait for claim.completed.

Polling vs webhooks

Polling: GET /v1/claims/:id every 10 s while status is processing. Fine for the portal and for low volume.

Webhooks (Starter and above): set webhookUrl on the tenant or per claim. We POST JSON with these headers:

X-ClaimProof-Event: claim.completed
X-ClaimProof-Signature: sha256=<hex HMAC-SHA256 of the raw body, keyed with your webhook_secret>
Content-Type: application/json

Deliveries retry 3× (after 1 min, 5 min, 30 min) on any non-2xx. Respond 200 quickly and process asynchronously. Always verify the signature over the raw body:

import { createHmac, timingSafeEqual } from 'node:crypto';
import express from 'express';

const app = express();
app.post('/hooks/claimproof', express.raw({ type: 'application/json' }), (req, res) => {
  const sig = req.get('X-ClaimProof-Signature') || '';
  const expected = 'sha256=' + createHmac('sha256', process.env.CLAIMPROOF_WEBHOOK_SECRET)
    .update(req.body).digest('hex');
  const ok = sig.length === expected.length && timingSafeEqual(Buffer.from(sig), Buffer.from(expected));
  if (!ok) return res.status(401).end();

  const event = req.get('X-ClaimProof-Event');
  const payload = JSON.parse(req.body.toString('utf8'));
  res.status(200).end();                 // ack first
  if (event === 'claim.completed') queueForAdjuster(payload.claimId, payload.report);
});

import hmac, hashlib, os
from flask import Flask, request, abort

app = Flask(__name__)

@app.post("/hooks/claimproof")
def claimproof_hook():
    body = request.get_data()                       # raw bytes, not parsed JSON
    expected = "sha256=" + hmac.new(
        os.environ["CLAIMPROOF_WEBHOOK_SECRET"].encode(), body, hashlib.sha256
    ).hexdigest()
    if not hmac.compare_digest(request.headers.get("X-ClaimProof-Signature", ""), expected):
        abort(401)
    event = request.headers.get("X-ClaimProof-Event")
    payload = request.get_json(force=True)
    if event == "claim.completed":
        queue_for_adjuster(payload["claimId"], payload["report"])
    return "", 200

Sends a signed webhook.test event to the tenant's URL so you can verify your receiver before the first real claim.

Files & signed URLs

Every *Url field in the API (annotatedUrl, thumbUrl, originalUrl, sideBySideUrl) is a signed URL on this endpoint: HMAC-signed, valid for 7 days, no bearer token needed. They can be embedded in your claim system or emailed to an adjuster. Do not try to construct them; re-fetch the parent resource to get a fresh one.

Originals and renders are deleted after 90 days by a storage lifecycle rule, or immediately when the claim is deleted through the API; URLs stop resolving at that point even if the 7-day signature is still valid. Other retention periods are set per tenant by Ward Tech on Enterprise contracts.

Usage

{ "month": "2026-11", "plan": "carrier",
  "images": { "used": 8120, "included": 20000 }, "claims": 611,
  "overageImages": 0, "estimatedOverageUsd": 0 }

AnalysisResult reference

Returned verbatim as analysis by /v1/analyze, /v1/analyses/:id, /v1/claims/:id/photos/:photoId and /v1/demo/analyze.

ClaimReport reference

Built once when the last photo of a claim finishes. Available as report on GET /v1/claims/:id, via /report, and inside the claim.completed webhook.

Verdict semantics

A verdict is a reading of evidence with a stated confidence. It is never a determination of fraud, and no verdict should trigger a denial without human review.

Reference-aware mode

When a reference is supplied, the engine aligns the two images (downscaling the larger if sizes differ), diffs luma after a 3×3 median, and reports changed areas as regions with signals:["reference"] and a reference signal at reliability 1.0. This is the only mode that can state "these pixels changed" rather than "these pixels look inconsistent".

Signals explained

Ten signals, each with a score and a reliability. Reliability is lowered by degradation before fusion: no EXIF → metadata/thumbnail ×0.4; JPEG quality < 75 or < 0.5 MP → ela/noise/grid ×0.5; PNG/screenshot → quant/grid skipped; vision capped at 0.5. The fused score is a noisy-OR over score × reliability, capped so a single low-reliability signal can never exceed 0.45.

What it cannot do

Limits & formats

Errors

All errors share one envelope. Log requestId — it is also in the X-Request-Id header on every response, success or failure.

{ "error": { "code": "RATE_LIMITED", "message": "Too many requests", "requestId": "req_…" } }

Changelog

v0.1 — 2026-11

• Initial release of the /v1 API and engine mesh-fi/0.1: ten signals, reliability-weighted fusion, reference-aware mode.
• Claims with multi-photo upload, ZIP ingestion workflow, cross-photo checks and ClaimReport.
• Signed webhooks with 3 retries; signed 7-day file URLs; public in-memory demo endpoint.
• Known limitations: C2PA manifests read but not cryptographically verified; HEIC requires the transcoding binding; self-service key rotation not yet in the portal.