Developer Reference

API Documentation

Integrate roofing claim predictions into your application with a single API call. This guide covers authentication, request/response formats, and usage limits.

Quick Start

Generate an API key from your dashboard.
POST claim data to https://claimpredict.io/api/v1/predict.
Get back a prediction with confidence tier, evidence report, and storm verification — all in one response.

Authentication

Include your API key in every request using the Authorization header:

Header format

Authorization: Bearer tp_your_api_key_here

Endpoint

POST/api/v1/predict

Submit claim details and receive an instant prediction with confidence scoring and risk analysis.

Request Body

Send a JSON object with the following fields. Providing a full address enables auto-detection of pitch, roof size, and stories.

Field	Type	Description
`carrier`	string	Required — Insurance carrier name — "State Farm", "Erie", "Allstate", "Nationwide", "Liberty Mutual", "Travelers", "USAA", "Progressive Insurance". Other carriers still work but may have lower confidence.
`address`	string	Required — Street address — enables geocoding & auto roof detection
`city`	string	Required — City name (used with address for geocoding)
`state`	string	Required — Two-letter code or full state name (e.g. "PA" or "Pennsylvania"). Trained states: AZ, CA, CO, CT, DE, FL, GA, HI, ID, IL, IN, KS, KY, LA, MA, MD, MI, MN, MO, MS, MT, NC, NE, NJ, NM, NY, OH, OK, OR, PA, RI, SC, SD, TN, TX, UT, VA, WA, WI, WV.
`zip`	string	Required — 3–5 digit ZIP code (e.g. "17011")
`material`	string	Required — Roof material. Accepted values: "Architectural", "3 tab", "Metal", "Slate", "Cedar Shake"
`roofAge`	string	Required — Accepted values: "5-10 Years", "11-15 Years", "16-20 Years", "21-25 Years", "26-30 Years", "Over 30 Years"
`pitch`	string	Optional — "1-4", "5-7", or "8+" — detected from address if not provided
`roofSize`	string	Optional — "0-15 Squares", "15-25 Squares", "25-35 Squares", "35-50 Squares", or "50+ Squares" — detected from address if not provided
`stories`	number	Optional — 1 or 2 — detected from address if not provided
`insuranceDate`	string	Required — Date claim was filed/screened — any common date format (e.g. "2019-03-01", "03/01/2019")
`lossDate`	string	Optional — Date of loss — any common date format — detected from nearest storm when insuranceDate and address are provided
`deductible`	number	Required — Policy deductible amount — non-negative number under 100,000 (e.g. 1500 for $1,500)
`description`	string	Required — Description of damage (max 10,000 chars)
`inspTestSquareHits`	number	Optional — Hail hits counted in the test square — whole number ≥ 0
`inspSlopesWithDamage`	number	Optional — Number of roof slopes with damage — whole number ≥ 0
`inspTotalHailHits`	number	Optional — Total hail hits counted across the roof — whole number ≥ 0
`inspPriorClaim`	string	Optional — Prior claim on this roof — "Y" or "N"
`inspMatchingIssue`	string	Optional — Shingle matching issue present — "Y" or "N"
`aerialOrdered`	string	Optional — Aerial/drone report ordered — "Y" or "N"
`collateralDamage`	string	Optional — Whether damage extends beyond the roof — "Y" or "N"
`collSiding`	string	Optional — Siding damage present — "Y" when collateralDamage is "Y"
`collFasciaSoffit`	string	Optional — Fascia or soffit damage present — "Y" when collateralDamage is "Y"
`collWindows`	string	Optional — Window damage present — "Y" when collateralDamage is "Y"
`collScreens`	string	Optional — Screen damage present — "Y" when collateralDamage is "Y"
`collFenceDeck`	string	Optional — Fence or deck damage present — "Y" when collateralDamage is "Y"
`evidGutters`	string	Optional — Visible gutter hail evidence — "Y" when observed during inspection
`evidDownspouts`	string	Optional — Visible downspout hail evidence — "Y" when observed during inspection
`evidSoftMetals`	string	Optional — Visible soft-metal hail evidence — "Y" when observed during inspection
`dtlRidge`	string	Optional — Ridge damage detail — "Y" when collateralDamage is answered
`dtlVents`	string	Optional — Vent damage detail — "Y" when collateralDamage is answered
`dtlChimney`	string	Optional — Chimney damage detail — "Y" when collateralDamage is answered
`dtlSkylight`	string	Optional — Skylight damage detail — "Y" when collateralDamage is answered
`dtlValleys`	string	Optional — Valley damage detail — "Y" when collateralDamage is answered
`dtlFlashing`	string	Optional — Flashing damage detail — "Y" when collateralDamage is answered
`dtlAcCondenser`	string	Optional — AC condenser damage detail — "Y" when collateralDamage is answered
`dtlAllSlopes`	string	Optional — All-slopes damage detail — "Y" when collateralDamage is answered
`dtlTornShingles`	string	Optional — Torn-shingle damage detail — "Y" when collateralDamage is answered
`dtlCrackedSplit`	string	Optional — Cracked or split damage detail — "Y" when collateralDamage is answered
`inspTotalSlopes`	number	Optional — Total roof slopes — whole number ≥ 0
`yearBuilt`	number	Optional — Year the property was built — 1800 through 2100
`insuredName`	string	Optional — Insured contact name — forwarded to your configured webhooks as contact.insured_name, never sent to the model
`insuredPhone`	string	Optional — Insured contact phone number — forwarded to your configured webhooks as contact.insured_phone
`insuredEmail`	string	Optional — Insured contact email — must be a valid email address — forwarded to your configured webhooks as contact.insured_email
`policyNumber`	string	Optional — Insurance policy number — forwarded to your configured webhooks as contact.policy_number

Example request bodyJSON

{
  "carrier": "Erie",
  "address": "456 Oak Ave",
  "city": "Camp Hill",
  "state": "PA",
  "zip": "17011",
  "material": "Architectural",
  "roofAge": "11-15 Years",
  "pitch": "5-7",
  "roofSize": "15-25 Squares",
  "stories": 2,
  "insuranceDate": "2019-03-01",
  "lossDate": "2025-06-15",
  "deductible": 1500,
  "description": "Hail and wind damage to roof and siding",
  "inspTestSquareHits": 9,
  "inspSlopesWithDamage": 3,
  "inspTotalHailHits": 50,
  "inspPriorClaim": "N",
  "inspMatchingIssue": "N",
  "aerialOrdered": "Y",
  "collateralDamage": "Y",
  "collSiding": "Y",
  "collFenceDeck": "Y",
  "evidGutters": "Y",
  "dtlValleys": "Y",
  "inspTotalSlopes": 4,
  "yearBuilt": 1998
}

Response

A successful prediction returns a JSON object with the prediction result, confidence tier, and contributing factors.

Field	Type	Description
`prediction`	string	"Approved", "Denied", or "Abstained"
`confidenceTier`	string	"high", "moderate", "low", or "insufficient_data"
`evidence`	object\|null	Claim strength score and individual factor scores
`hailReport`	object\|null	Storm verification — loss date, search radius, and hail/wind events on the loss date near the property
`verifyUrl`	string\|null	Public URL to verify and share this prediction

Example responseJSON

{
  "prediction": "Approved",
  "confidenceTier": "high",
  "evidence": {
    "claimStrength": 72,
    "scores": { "storm": 85, "timing": 90, "damage": 70, "roof": 80, "carrier": 60 }
  },
  "hailReport": {
    "lossDate": "2025-06-10",
    "searchRadiusMiles": 25,
    "nearbyEvents": [
      {
        "date": "2025-06-10",
        "category": "hail",
        "hailSize": 2.5,
        "distanceMi": 3.2
      },
      {
        "date": "2025-06-10",
        "category": "wind",
        "windSpeed": 65.0,
        "distanceMi": 1.1
      }
    ]
  },
  "verifyUrl": "https://claimpredict.io/verify/abc123-def456"
}

Confidence Tiers

Every prediction includes a confidence tier based on the model's certainty. Use these tiers to decide how much weight to give each prediction.

Extremely Confident

High

≥ 0.85

~99% accuracy. Right about 99 in 100 on recent claims.

Confident

Moderate

0.70 – 0.84

~80% accuracy. Matches 4 in 5 similar historical claims.

Signal

Low

0.55 – 0.69

Directional read. Worth reviewing before acting.

Abstained

Insufficient Data

< 0.55

Not enough signal. Manual review recommended.

Code Examples

cURL

Terminalbash

curl -X POST https://claimpredict.io/api/v1/predict \
  -H "Authorization: Bearer tp_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "carrier": "Erie",
    "address": "456 Oak Ave",
    "city": "Camp Hill",
    "state": "PA",
    "zip": "17011",
    "material": "Architectural",
    "roofAge": "11-15 Years",
    "pitch": "5-7",
    "roofSize": "15-25 Squares",
    "stories": 2,
    "insuranceDate": "2019-03-01",
    "lossDate": "2025-06-15",
    "deductible": 1500,
    "description": "Hail and wind damage to roof and siding",
    "inspTestSquareHits": 9,
    "inspSlopesWithDamage": 3,
    "inspTotalHailHits": 50,
    "inspPriorClaim": "N",
    "inspMatchingIssue": "N",
    "aerialOrdered": "Y",
    "collateralDamage": "Y",
    "collSiding": "Y",
    "collFenceDeck": "Y",
    "evidGutters": "Y",
    "dtlValleys": "Y",
    "inspTotalSlopes": 4,
    "yearBuilt": 1998
  }'

Python

predict.pypython

import requests

response = requests.post(
    "https://claimpredict.io/api/v1/predict",
    headers={
        "Authorization": "Bearer tp_your_api_key_here",
        "Content-Type": "application/json",
    },
    json={
        "carrier": "Erie",
        "address": "456 Oak Ave",
        "city": "Camp Hill",
        "state": "PA",
        "zip": "17011",
        "material": "Architectural",
        "roofAge": "11-15 Years",
        "pitch": "5-7",
        "roofSize": "15-25 Squares",
        "stories": 2,
        "insuranceDate": "2019-03-01",
        "lossDate": "2025-06-15",
        "deductible": 1500,
        "description": "Hail and wind damage to roof and siding",
        "inspTestSquareHits": 9,
        "inspSlopesWithDamage": 3,
        "inspTotalHailHits": 50,
        "inspPriorClaim": "N",
        "inspMatchingIssue": "N",
        "aerialOrdered": "Y",
        "collateralDamage": "Y",
        "collSiding": "Y",
        "collFenceDeck": "Y",
        "evidGutters": "Y",
        "dtlValleys": "Y",
        "inspTotalSlopes": 4,
        "yearBuilt": 1998,
    },
)

data = response.json()
print(f"Prediction: {data['prediction']} ({data['confidenceTier']} confidence)")
print(f"Evidence scores: {data['evidence']['scores']}")

JavaScript / TypeScript

predict.tsjavascript

const response = await fetch("https://claimpredict.io/api/v1/predict", {
  method: "POST",
  headers: {
    "Authorization": "Bearer tp_your_api_key_here",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    carrier: "Erie",
    address: "456 Oak Ave",
    city: "Camp Hill",
    state: "PA",
    zip: "17011",
    material: "Architectural",
    roofAge: "11-15 Years",
    pitch: "5-7",
    roofSize: "15-25 Squares",
    stories: 2,
    insuranceDate: "2019-03-01",
    lossDate: "2025-06-15",
    deductible: 1500,
    description: "Hail and wind damage to roof and siding",
    inspTestSquareHits: 9,
    inspSlopesWithDamage: 3,
    inspTotalHailHits: 50,
    inspPriorClaim: "N",
    inspMatchingIssue: "N",
    aerialOrdered: "Y",
    collateralDamage: "Y",
    collSiding: "Y",
    collFenceDeck: "Y",
    evidGutters: "Y",
    dtlValleys: "Y",
    inspTotalSlopes: 4,
    yearBuilt: 1998,
  }),
});

const data = await response.json();
console.log(`Prediction: ${data.prediction} (${data.confidenceTier} confidence)`);
console.log(`Storm score: ${data.evidence.scores.storm}`);

Integrations

ClaimPredict works with any platform that can make HTTP requests. Here's how to connect with popular tools.

Zapier

Create a new Zap and choose your trigger (e.g. "New Record in CRM", "New Row in Google Sheets").
Add an action step → search for Webhooks by Zapier → select Custom Request.
Set Method to POST.
Set URL to https://claimpredict.io/api/v1/predict.
Under Headers, add:
Authorization: Bearer tp_your_key
Content-Type: application/json
Under Data, map your trigger fields to the JSON body (carrier, address, city, state, zip, material, roofAge, insuranceDate, deductible, description, and any optional fields).
Add a second action to write the response fields (prediction, confidenceTier, evidence, hailReport, verifyUrl) back to your CRM or spreadsheet.

Make (Integromat)

Add an HTTP → Make a request module.
Set URL to https://claimpredict.io/api/v1/predict, method POST.
Add headers: Authorization: Bearer tp_your_key and Content-Type: application/json.
Set Body type to Raw → JSON and map your fields.
Connect a downstream module to parse the JSON response and route data back to your system.

CRM Integration (JobNimbus, AccuLynx, Roofr, HubSpot, etc.)

Most CRMs support webhook/automation triggers when a new job or contact is created. The pattern is always the same:

Trigger: New job/claim created in your CRM.
Map fields: CRM field → API field (e.g. "Insurance Company" → carrier, "Property Address" → address).
Call API: POST to /api/v1/predict with your API key.
Store result: Write prediction, confidenceTier, evidence, hailReport, and verifyUrl into custom fields on the job record.

💡 Tip

If your CRM doesn't have native HTTP actions, use Zapier or Make as the bridge. Trigger on "New Job" in your CRM → call ClaimPredict → write results back to the job.

Embeddable Widget

Add the prediction widget directly on your own website with a single <script> tag. Visitors get an instant approval prediction, and every submission runs on your account and appears in your dashboard. Create an embed under Dashboard → Integrations → Embeddable Form, then paste the generated snippet:

<script src="https://claimpredict.io/embed.js" data-key="ep_your_key" async></script>

The loader injects an auto-resizing iframe. Add an optional data-target="#css-selector" to mount it at a specific element instead of inline.

Security

Bot protection: each submission is verified with Cloudflare Turnstile before a prediction runs.
Domain allowlist: restrict which websites may load the widget. At least one domain is required — allowlisted origins are enforced with a browser frame-ancestors policy and a server-side origin check (both fail closed).
Daily cap: a per-embed limit on billable predictions per 24 hours bounds cost if the key is abused. Default 50, configurable per embed.
The embed key (ep_…) is publishable and safe to expose in the iframe URL — unlike your secret tp_… API keys.

Pricing

Each prediction is priced based on the confidence tier of the result. Abstained predictions are always free.

Confidence Tier	Cost
High	$60
Moderate	$40
Low	$20
Abstained	$0

Errors

400 — Validation error. Check the details field for which fields failed.
401 — Missing or invalid API key. Ensure your Authorization header is set to Bearer tp_xxx.
403 — API key has been revoked. Generate a new key from your Integrations page.
429 — Rate limited. Max 60 requests per hour. Wait and retry.
502 — Prediction engine error or unreachable. Try again shortly.
504 — Prediction engine timed out (max 120s). Try again later.