RoofTap Enrichment API

One JSON call. Roof + property + storm data on every address. Same shape every CRM. Pay-as-you-go, never billed for bad reads.

Quickstart

Activate a key in 60 seconds at /integrations/signup. You'll see the key once on the success page, copy it before closing the tab. Every key is prefixed with rt_live_.

curl -X POST https://api.rooftap.app/v1/enrich \
  -H "X-API-Key: rt_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{ "address": "5701 W Loma Ln, Glendale, AZ 85302" }'

Authentication

Every request must include the X-API-Key header. Keys are tied to one billing account. Treat them like passwords: do not embed in client-side JavaScript or commit to git.

Lost your key? Email support@rooftap.appfrom the address on file and we'll rotate it.

Tiers - one API, free & paid

Your key's tier decides which fields return. Free keys get the zero-cost layers: storm history, FEMA hazard risk, Census neighborhood, and areactivation flag (when you pass lead_date). Paid keys ($3.95/record, sliding to $1.95 at volume) get everything in free plusthe real-time roof + property record, roof area, facets & pitch, edge measurements, material takeoff, cost estimate, complexity, pool/garage flags, owner & property details, and solar. Premium fields are simply omitted on the free tier; upgrade and they appear with no code change (same key). Every measurementcarries a confidence score, and you're never billed for a low-confidence read.

POST /v1/enrich

The primary endpoint. Returns the full enrichment payload synchronously. Cold call latency (first time we see an address) is typically 4-7 seconds, Solar API + property + storm history fetched in parallel. Cached addresses (same parcel called twice within the 7-day cache TTL) return sub-second. If you need to keep enrichment off your hot path, use the prewarm endpoint.

Request

POST https://api.rooftap.app/v1/enrich
X-API-Key: rt_live_abc123...
Content-Type: application/json

{
  "address": "5701 W Loma Ln, Glendale, AZ 85302",
  "lead_id": "lead-9821",
  "owner_match_name": "Sarah Johnson"
}

Response shape

Free keys return storm, risk (FEMA), neighborhood (Census), and reactivation (when lead_date is sent). Paid keys add roof, property, solar, and data_quality. Numeric fields can be null when source data is missing, never 0 as a fallback. The field tables below marked paid are omitted on the free tier.

200 OK

{
  "ok": true,
  "lead_id": "lead-9821",
  "billable": true,
  "address": {
    "input":      "5701 W Loma Ln, Glendale, AZ 85302",
    "formatted":  "5701 W Loma Ln, Glendale, AZ 85302, USA",
    "lat":        33.5601,
    "lng":       -112.1888,
    "place_id":   "ChIJ..."
  },
  "roof": {
    "area_sqft":          4003,
    "squares":            44,
    "predominant_pitch":  "4/12",
    "complexity":         "cut_up",
    "num_facets":         9,
    "linear_measurements": {
      "drip_edge_ft": 457
    }
  },
  "gutter": {
    "linear_feet":             127,
    "downspout_count_estimate": 4
  },
  "siding": {
    "wall_sqft_estimate": 2540,
    "perimeter_ft":        254,
    "stories":               1
  },
  "solar": {
    "suitability":             "high",
    "max_panel_count":          34,
    "kw_potential":             13.6,
    "annual_kwh_potential":     14820,
    "max_array_area_sqft":      612,
    "sunshine_hours_per_year":  1820,
    "panel_capacity_watts":     400
  },
  "property": {
    "year_built":                 1972,
    "estimated_roof_age_years":   18,
    "owner_match":                true,
    "owner_occupied":             true,
    "lot_size_sqft":              7800,
    "stories":                    1,
    "bedrooms":                   3,
    "bathrooms":                  2,
    "last_sale_date":             "2024-09-12",
    "last_sale_price":            412000,
    "sold_within_12mo":           true
  },
  "storm": {
    "hail_2024":      "1.75in",
    "hail_5yr_count": 4,
    "wind_5yr_max":   "72mph",
    "last_event_date": "2024-04-14",
    "claim_eligible_window": {
      "event_date":     "2024-04-14",
      "expires":        "2026-04-14",
      "days_remaining": 0
    }
  },
  "data_quality": {
    "confidence":      "high",
    "imagery_quality": "HIGH",
    "footprint_match": true
  }
}

Roof fields

Gutter fields

Siding fields

Solar fields

Property fields

Storm fields

Contact compliance fields (premium add-on)

Quality + meta

POST /v1/enrich/prewarm

Optional. Hit this at lead intake to kick off the enrichment fetch in the background. Returns 202 in under 50ms, the next/v1/enrich call on the same address (the one that runs when your routing decision happens) lands a warm cache and returns sub-500ms.

Prewarm calls don't bill. Only the real call does.

POST https://api.rooftap.app/v1/enrich/prewarm
X-API-Key: rt_live_abc123...

{ "address": "5701 W Loma Ln, Glendale, AZ 85302",
  "lead_id":  "lead-9821" }

202 Accepted · <50ms
{ "ok": true, "lead_id": "lead-9821",
  "message": "Prewarm queued. Hit POST /v1/enrich on the same address in 2-6s for a cache hit." }

Bulk reactivation

Run an aged lead list back through NOAA storm history to find the homeowners worth a call today. This is storm-only screening(NOAA storm history + a worth-a-call-today flag + optional ongoing next-storm monitoring), not a full enrich. It's async + batched: you enqueue a job and poll for results (or wait for a webhook). Use it to wake a dormant CRM, not to measure a roof, when you need measurements use /v1/enrich.

POST /v1/reactivate

Enqueue an async batch of up to 1,000 addresses per request. Authenticate with the same X-API-Key header you use for /v1/enrich. Returns 202 immediately with a job_id and a status_url to poll. For a 50k+ list, split into chunks of 1,000 and POST each chunk, every chunk returns its own job_id.

curl -X POST https://api.rooftap.app/v1/reactivate \
  -H "X-API-Key: rt_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "addresses": [
      "5701 W Loma Ln, Glendale, AZ 85302",
      { "address": "1804 E Vista Ave, Phoenix, AZ 85020", "external_ref": "lead-9821" }
    ],
    "monitor": true,
    "email": "ops@yourcompany.com",
    "webhook_url": "https://yourcompany.com/hooks/rooftap"
  }'

202 Accepted
{
  "ok": true,
  "job_id": "rjb_7f3c9a2e",
  "queued": 2,
  "status": "queued",
  "status_url": "https://api.rooftap.app/v1/reactivate/rjb_7f3c9a2e",
  "message": "Batch queued. Poll status_url or wait for the completion webhook."
}

The 202 body carries ok, job_id, queued (count accepted this request), status ("queued"), status_url, and a message.

Errors specific to this endpoint:

GET /v1/reactivate/{job_id}

Poll job status and pull results. Authenticate with X-API-Key, you can only read your own jobs. status moves queued → processing → completed (or failed).

curl https://api.rooftap.app/v1/reactivate/rjb_7f3c9a2e?status=follow_up \
  -H "X-API-Key: rt_live_abc123..."

200 OK
{
  "ok": true,
  "job_id": "rjb_7f3c9a2e",
  "status": "completed",
  "summary": {
    "total":       2,
    "processed":   2,
    "follow_ups":  1,
    "monitored":   2,
    "errors":      0
  },
  "results": [
    {
      "address":               "5701 W Loma Ln, Glendale, AZ 85302",
      "external_ref":           null,
      "status":                "done",
      "matched":                true,
      "last_event":            "2026-05-26",
      "max_hail_in":            1.75,
      "events_5yr":             4,
      "worth_following_up":     true,
      "trigger":               { "date": "2026-05-26", "type": "hail", "hail_in": 1.75, "wind_mph": null },
      "days_since_last_storm":  8,
      "claim_window_days":      365,
      "within_claim_window":    true,
      "priority":               1,
      "monitored":              true
    }
  ],
  "paging": { "limit": 500, "offset": 0, "returned": 1 }
}

The response carries ok, job_id, status, a summary block (total, processed, follow_ups, monitored, errors), the results array, and paging (limit, offset, returned).

Reactivation result fields

priority is a call-ordering heuristic, not legal or insurance advice. We rank fresher storms higher so your team works the list top-down. The scale:

• 1 - severe storm 14 days ago or less.
• 2 - 15 to 90 days ago.
• 3 - 91 to 365 days ago.
• 4 - 366 days up to the state's claim window (only reachable in 2-year states).
• 5 - past the state's claim window, or older than 2 years. Still listed, just the lowest rank.

The claim window is per US state (roughly 1 to 2 years) and is a best-effort heuristic. When we can't determine the state we default to 2 years (claim_window_days: 730). Leads are never dropped: anything past the window simply floors to priority 5.

Completion webhook

Optional. If you set webhook_urlon the enqueue call, we POST a completion event there when the job finishes, so you don't have to poll.

POST https://yourcompany.com/hooks/rooftap
Content-Type: application/json

{
  "event":   "reactivation.completed",
  "job_id":  "rjb_7f3c9a2e",
  "summary": {
    "total":      50000,
    "processed":  50000,
    "errors":     0,
    "follow_ups": 3142,
    "monitored":  50000
  }
}

Errors

All errors return JSON with { ok: false, error, message }. The error field is a stable machine-readable code; message is human-readable and may change between releases.

401 Unauthorized · invalid_key
{ "ok": false, "error": "invalid_key",
  "message": "X-API-Key header missing or unrecognized." }

422 Unprocessable Entity · address_unresolvable
{ "ok": false, "error": "address_unresolvable",
  "message": "Could not geocode the supplied address.",
  "billable": false }

429 Too Many Requests · rate_limited
{ "ok": false, "error": "rate_limited",
  "message": "Rate limit: 10 rps. Retry after 600ms." }
// Honor the Retry-After response header.

Rate limits

• /v1/enrich - 10 rps per API key. 429 returns a Retry-After header in seconds.
• /v1/enrich/prewarm - 30 rps per API key (separate bucket).
• Need higher caps for an aggregator burst? Email support, we lift to 50+ rps once we see your traffic profile.

Billing

Volume tiers are auto-applied for the entire month based on your final volume. Run 16,000 calls in a month and every call that period prices at $2.45, including the first 5,000.

Quality guarantee

Changelog

• 2026-06 - Bulk reactivation launched. Async batch storm-screening for aged lead lists: POST /v1/reactivate + GET /v1/reactivate/{job_id}, first 1,000 addresses free, then $0.01/address, with optional ongoing next-storm monitoring and a completion webhook.
• 2026-05 - Storm Alerts webhook API launched in free beta. Register addresses, get signed POSTs when qualifying hail/wind events land within 10 mi. linear_measurements slimmed to drip_edge_ft only in auto-mode reports; per-edge fields ship when the report is refined via the on-screen labeling tool. Storm 5-year wind max added.
• 2026-04 - Prewarm endpoint launched. Volume tier breakpoints widened.
• 2026-03 - owner_match_name request parameter live.
• 2026-02 - v1 GA. Public launch.