REST API Reference

Endpoints

Authentication

Property and lookup endpoints need a key. During our pilot program keys are provisioned per partner rather than self-serve — email hello@myhailscore.com to request one. Existing keys are listed in your dashboard. The two /meta/* endpoints are public (no key). Send your key as a Bearer token:

curl -H "Authorization: Bearer hs_live_xxxxxxxx" \
  "https://www.myhailscore.com/api/v1/property/verify?address=...&date_of_loss=..."

Keep keys server-side. Never embed a key in client JavaScript or mobile apps shipped to end users — the Pro API sets no CORS headers, so browser calls are blocked by design. An ?api_key= query parameter is still accepted for legacy integrations but is deprecated: URLs land in server logs, proxies, and Referer headers. Use the header.

Response envelope

Every /property/* and /meta/* response is wrapped in a { data, meta } envelope. The meta block is identical across endpoints and carries the request id, the methodology version that produced the response, and the publisher catalog:

{
  "data": { /* endpoint-specific payload */ },
  "meta": {
    "request_id": "0f0c…",            // quote this when reporting an issue
    "api_version": "v1",
    "methodology_version": "v6.2",
    "methodology_last_updated": "2026-05-30",
    "computed_at": "2026-06-09T15:00:00.000Z",
    "data_sources": ["NOAA_SED", "NEXRAD_SWDI", "MRMS_MESH",
                     "NWS_ALERT", "SPC_LSR", "COCORAHS"]
  }
}

meta.data_sources is the methodology-level publisher catalog (six feeds). Per-event citations are drawn from the four feeds that expose a native record id — see Data sources & citations. The older /api/v1/lookup endpoint predates this envelope and returns a flat object.

GET /api/v1/property/verify

Date-of-loss verification. Given an address and a loss date, returns every hail event near the property inside a verification window — each event cited from its publisher with that publisher’s native record identifier. The core endpoint for adjusters, public adjusters, and carrier SIU.

Query parameters

Example request

curl -H "Authorization: Bearer hs_live_xxxxxxxx" \
  "https://www.myhailscore.com/api/v1/property/verify?address=1701%20Franklin%20Ave%2C%20Waco%2C%20TX%2076701&date_of_loss=2024-05-31"

Example response

{
  "data": {
    "property": {
      "address": "1701 Franklin Ave, Waco, TX 76701",
      "resolved_address": "1701 Franklin Avenue, Waco, Texas 76701, United States",
      "lat": 31.5493,
      "lon": -97.1467
    },
    "date_of_loss": "2024-05-31",
    "verification": {
      "window_days": 45,
      "window_start": "2024-04-16T00:00:00.000Z",
      "window_end": "2024-07-15T00:00:00.000Z",
      "radius_mi": 5,
      "min_size_in": 0.75,
      "verdict": "hail_confirmed",
      "event_count": 3,
      "max_hail_size_in": 2.75
    },
    "events": [
      {
        "occurred_at": "2024-05-31T20:34:00.000Z",
        "size_in": 2.75,
        "distance_mi": 1.42,
        "bearing": "NE",
        "sources": [
          {
            "publisher": "NOAA_SED",
            "record_id": "1123456",
            "url": "https://www.ncdc.noaa.gov/stormevents/eventdetails.jsp?id=1123456"
          }
        ]
      },
      {
        "occurred_at": "2024-05-31T20:30:00.000Z",
        "size_in": 2.5,
        "distance_mi": 0.88,
        "bearing": "N",
        "sources": [
          {
            "publisher": "NEXRAD_SWDI",
            "record_id": "KGRK/2024-05-31T20:30:00.000Z/AL27",
            "url": "https://www.ncdc.noaa.gov/swdiws/",
            "detail": { "station": "KGRK", "timestamp": "2024-05-31T20:30:00.000Z", "cell_id": "AL27" }
          }
        ]
      }
    ]
  },
  "meta": { /* envelope — see Response envelope above */ }
}

verdict is hail_confirmed when at least one publisher reports hail ≥ min_size_in inside the window, otherwise no_hail_in_window. One address per call. To batch a loss run today, use the in-product Loss Runs page (dashboard, up to 50 addresses); an API-key bulk endpoint is on the roadmap.

GET /api/v1/property/score

The calibrated HailScore (0–100) for a property, plus the events that produced it, each cited from its publisher. Pass roof age and material so the score reflects the actual roof exposure window.

Query parameters

Example response

{
  "data": {
    "property": {
      "address": "1701 Franklin Ave, Waco, TX 76701",
      "resolved_address": "1701 Franklin Avenue, Waco, Texas 76701, United States",
      "lat": 31.5493, "lon": -97.1467,
      "roof_age": 10, "roof_type": "asphalt_shingle"
    },
    "score": {
      "value": 67,
      "tier": "High",
      "max_hail_size_in": 2.75,
      "storm_count": 12
    },
    "events": {
      "total_in_lookback": 41,
      "returned": 41,
      "items": [
        {
          "occurred_at": "2024-05-31T20:30:00.000Z",
          "size_in": 2.75, "distance_mi": 0.88,
          "sources": [{ "publisher": "NEXRAD_SWDI", "record_id": "KGRK/2024-05-31T20:30:00.000Z/AL27", "url": "https://www.ncdc.noaa.gov/swdiws/" }]
        }
      ]
    },
    "parameters": { "radius_mi": 5, "lookback_start": "2016-06-09T15:00:00.000Z" }
  },
  "meta": { /* envelope */ }
}

tier maps to value: 0–25 Low · 26–50 Moderate · 51–75 High · 76–100 Very High. Up to 50 most-recent cited events are returned in items; total_in_lookback is the full count.

GET /api/v1/property/history

Full chronological event history for a property, cited from every publisher we have data on. Built for portfolio analytics, underwriting pulls, and SIU pattern review.

Query parameters

Example response

{
  "data": {
    "property": { "address": "...", "resolved_address": "...", "lat": 31.5493, "lon": -97.1467 },
    "window": { "since": "2015-01-01", "until": "2026-06-09", "radius_mi": 5, "min_size_in": 0.75 },
    "events": {
      "total": 128,
      "returned": 128,
      "truncated": false,
      "items": [
        {
          "occurred_at": "2024-05-31T20:34:00.000Z",
          "size_in": 2.75, "distance_mi": 1.42,
          "sources": [{ "publisher": "NOAA_SED", "record_id": "1123456", "url": "https://www.ncdc.noaa.gov/stormevents/eventdetails.jsp?id=1123456" }]
        }
      ]
    }
  },
  "meta": { /* envelope */ }
}

GET /api/v1/lookup

The original single-address endpoint — HailScore plus a storm summary, in the same shape that powers a homeowner lookup at myhailscore.com. Predates the { data, meta } envelope and returns a flat object; kept stable for existing integrations. New integrations should prefer /property/score.

Query parameters

Example response

{
  "request": {
    "address": "1701 Franklin Ave, Waco, TX 76701",
    "resolved_address": "1701 Franklin Avenue, Waco, Texas 76701, United States",
    "lat": 31.5493,
    "lon": -97.1467
  },
  "score": {
    "value": 67,
    "tier": "High",
    "max_hail_size_in": 4.0
  },
  "storms": {
    "total_radar_events": 851,
    "last_damaging_event": {
      "date": "2024-05-31",
      "size": 2.75,
      "days_ago": 349
    },
    "claim_window_open": true
  },
  "live_mrms": {
    "hail_days_last_30": 1,
    "max_in_last_30": 0.85
  },
  "meta": {
    "api_version": "v1",
    "generated_at": "2026-05-15T03:00:00Z",
    "sources": ["NOAA Storm Events", "NCEP MRMS", "NEXRAD MESH (SWDI)", "SPC LSR", "NWS Active Alerts"]
  }
}

GET /api/v1/meta/health

Service health and per-feed data freshness. No authentication. Returns 200 even when individual feeds are degraded — inspect feeds[] and data_freshness_ok. Intended for status dashboards and automated probes.

Example response

{
  "data": {
    "status": "healthy",
    "database": { "connected": true },
    "methodology_version": "v6.2",
    "data_freshness_ok": true,
    "feeds": [
      { "feed": "mrms_mesh", "publisher": "MRMS_MESH", "last_observation_at": "2026-06-09T13:00:00.000Z", "hours_since": 2, "status": "fresh", "threshold_hours": 6 },
      { "feed": "radar_hail", "publisher": "NEXRAD_SWDI", "last_observation_at": "2026-06-07T00:00:00.000Z", "hours_since": 63, "status": "fresh", "threshold_hours": 168 }
    ]
  },
  "meta": { /* envelope */ }
}

Per-feed status is fresh, stale, or unknown. Top-level status is healthy, degraded, or down.

GET /api/v1/meta/methodology

Methodology version, change log, and the publisher catalog. No authentication. Poll this to know when to refresh against a new methodology revision.

Example response

{
  "data": {
    "methodology_version": "v6.2",
    "last_updated": "2026-05-30",
    "url": "https://www.myhailscore.com/methodology",
    "changelog": [
      { "version": "v6.2", "published": "2026-05-30", "summary": "Ground-truth point-to-point match geometry..." }
    ],
    "publishers": {
      "cited_per_event": ["NOAA_SED", "NEXRAD_SWDI", "MRMS_MESH", "COCORAHS"],
      "referenced_in_methodology": ["NOAA_SED", "NEXRAD_SWDI", "MRMS_MESH", "NWS_ALERT", "SPC_LSR", "COCORAHS"],
      "notes": {
        "NWS_ALERT": "Referenced in §3 of the methodology; per-event citations pending live-archive ingestion.",
        "SPC_LSR": "Referenced in §3 of the methodology; per-event citations pending preliminary-record ingestion."
      }
    }
  },
  "meta": { /* envelope */ }
}

Data sources & citations

Every event we return carries a sources array. Each entry names the originating publisher and that publisher’s native record identifier so the fact can be verified against the public record. Four publishers expose a per-event record id today; two more are referenced at the methodology level (ingestion pending) and appear in meta.data_sources but not in any per-event sources array.

Rate limits

Default: 60 requests per minute, 1,000 per day per key.

When exceeded, the API returns HTTP 429:

{
  "error": {
    "code": "rate_limited",
    "message": "Rate limit exceeded (minute-rate-limit). Retry after 38s.",
    "request_id": "0f0c…",
    "detail": { "retry_after_seconds": 38, "reason": "minute-rate-limit" }
  }
}

Need higher? Email hello@myhailscore.com.

Errors

/property/* and /meta/* return a structured error object; every error carries the request_id so you can quote it when reporting an issue:

{
  "error": {
    "code": "unprocessable_entity",
    "message": "Address could not be geocoded.",
    "request_id": "0f0c…",
    "detail": { "address": "garbled input" }
  }
}

The legacy /api/v1/lookup endpoint returns a flat { "error": "..." } string instead of the structured object above.

Machine-readable spec

The full API surface is published as an OpenAPI 3.1 document for use with code-generation tools (openapi-generator, openapi-typescript, Postman, Insomnia, etc.):

# Spec URL (always current)
https://www.myhailscore.com/api/v1/openapi.json

# Generate a TypeScript client
npx openapi-typescript https://www.myhailscore.com/api/v1/openapi.json -o hailscore-client.ts

Roadmap — not available yet

The endpoints below are planned but not callable today. They are listed for direction only — do not build against them yet.

• · POST /api/v1/bulk — batch property verification / scoring via API key. (Bulk DOL verification exists in-product today on the dashboard Loss Runs page, up to 50 addresses per request.)
• · GET /api/v1/storms — historical storm events around a point
• · GET /api/v1/swaths — hail-swath GeoJSON polygons