API Reference

Base URL: https://riskbeforebuy.smarttechinvest.com

Authentication

Pass your API key via the X-API-Key header on every request (except /v1/signup and /v1/login).

GET/v1/risk/:zip

Get risk scores for a U.S. ZIP code.

Parameters

Name	Type	Required	Description
zip	path	required	5-digit U.S. ZIP code
detail	query	optional	"county" (default) or "tract" (paid plans)

Response

{
  "success": true,
  "data": {
    "composite": 62,
    "flood": 28,
    "earthquake": 78,
    "wildfire": 42,
    "crime": 55,
    "county": "Los Angeles",
    "state": "CA",
    "fips": "06037"
  }
}

Error Codes

400 Invalid ZIP code
404 ZIP not found
429 Rate limit exceeded

GET/v1/risk/:zip/report

Get full risk report with NPV calculations.

Parameters

Name	Type	Required	Description
zip	path	required	5-digit U.S. ZIP code
format	query	optional	"json" (default) or "pdf"
years	query	optional	NPV projection years (default: 30)

Response

{
  "success": true,
  "data": {
    "scores": { "composite": 62, "flood": 28, ... },
    "npv30Year": 127000,
    "insuranceCosts": {
      "flood": 1200,
      "earthquake": 800,
      "fire": 450,
      "homeowners": 1800
    },
    "recommendation": "Moderate overall risk...",
    "dataUpdated": "2026-02-28"
  }
}

Error Codes

401 API key required
403 Plan upgrade required
429 Rate limit exceeded

POST/v1/risk/compare

Compare risk and costs for multiple locations.

Parameters

Name	Type	Required	Description
zips	body	required	Array of 2-5 ZIP codes to compare
years	body	optional	NPV projection years (default: 30)

Response

{
  "success": true,
  "data": {
    "locations": [
      { "zip": "90210", "composite": 62, ... },
      { "zip": "94102", "composite": 71, ... }
    ],
    "npvDifference": 43000,
    "recommendation": "90210 has lower 30-year risk cost..."
  }
}

Error Codes

400 Invalid request body
401 API key required
429 Rate limit exceeded

GET/v1/hazards

List all available hazard types and their data sources.

Response

{
  "success": true,
  "data": [
    { "id": "flood", "name": "Flood Risk", "source": "FEMA NRI" },
    { "id": "earthquake", "name": "Earthquake Risk", "source": "USGS" },
    { "id": "wildfire", "name": "Wildfire Risk", "source": "USFS" },
    { "id": "crime", "name": "Crime Risk", "source": "FBI UCR" }
  ]
}

POST/v1/signup

Create an account and receive an API key.

Parameters

Name	Type	Required	Description
name	body	required	User display name
email	body	required	Email address
password	body	required	Password (min 8 characters)

Response

{
  "success": true,
  "data": {
    "name": "Jane Doe",
    "email": "jane@example.com",
    "tier": "free",
    "apiKey": "rbb_abc123..."
  }
}

Error Codes

400 Invalid input
409 Email already registered

POST/v1/login

Authenticate with email and password.

Parameters

Name	Type	Required	Description
email	body	required	Email address
password	body	required	Password

Response

{
  "success": true,
  "data": {
    "name": "Jane Doe",
    "email": "jane@example.com",
    "tier": "free",
    "apiKey": "rbb_abc123..."
  }
}

Error Codes

401 Invalid credentials

GET/v1/account/keys

List all API keys for the authenticated user.

Response

{
  "success": true,
  "data": {
    "keys": [
      { "id": 1, "prefix": "rbk_live_abc...", "lastUsed": "2026-03-01T12:00:00Z" }
    ]
  }
}

Error Codes

401 API key required

POST/v1/account/keys/rotate

Rotate API key — generates a new key and invalidates the old one.

Response

{
  "success": true,
  "data": {
    "apiKey": "rbk_live_new_key..."
  }
}

Error Codes

401 API key required

DELETE/v1/account/keys/:id

Revoke a specific API key.

Parameters

Name	Type	Required	Description
id	path	required	API key ID

Response

{
  "success": true,
  "data": { "message": "Key revoked" }
}

Error Codes

401 API key required
404 Key not found

DELETE/v1/account

Permanently delete your account and all data.

Response

{
  "success": true,
  "data": { "message": "Account deleted" }
}

Error Codes

401 API key required

GET/v1/data/insurance-estimate/:fips

Get NFIP flood insurance claims data for a county.

Parameters

Name	Type	Required	Description
fips	path	required	5-digit county FIPS code (e.g., 06037)

Response

{
  "success": true,
  "data": {
    "county": "Los Angeles",
    "countyType": "County",
    "fips": "06037",
    "insurance": {
      "totalClaims": 12453,
      "avgClaimAmount": 42150.00,
      "totalClaimsPaid": 524891250.00,
      "lastUpdated": "2026-01-01T00:00:00Z"
    }
  }
}

Error Codes

400 Invalid FIPS code
404 County not found

GET/v1/data/flood-zone/:fips

Get FEMA flood zone designation for a county.

Parameters

Name	Type	Required	Description
fips	path	required	5-digit county FIPS code (e.g., 06037)

Response

{
  "success": true,
  "data": {
    "county": "Los Angeles",
    "countyType": "County",
    "fips": "06037",
    "floodZone": {
      "primaryZone": "X",
      "hasDfirm": true,
      "sfhaZoneCount": 4,
      "totalZoneCount": 12,
      "lastUpdated": "2026-01-01T00:00:00Z"
    }
  }
}

Error Codes

400 Invalid FIPS code
404 County not found

POST/v1/forgot-password

Request a password reset email. Returns 200 regardless of email existence.

Parameters

Name	Type	Required	Description
email	body	required	Email address

Response

{
  "success": true,
  "data": { "message": "If an account exists, a reset email was sent." }
}

POST/v1/reset-password

Reset password using a token from the reset email.

Parameters

Name	Type	Required	Description
token	body	required	Reset token from email
password	body	required	New password (min 8 characters)

Response

{
  "success": true,
  "data": { "message": "Password updated" }
}

Error Codes

400 Invalid or expired token

Rate Limiting

Requests that exceed your plan limit return 429 Too Many Requests with a Retry-After header indicating seconds until the limit resets.

Plan	Requests/Day	Tract-Level
Developer (Free)	100	No
Starter ($17/mo)	1,000	Yes
Business ($49/mo)	10,000	Yes
Enterprise (Custom)	Unlimited	Yes