Reference

REST API

Programmatic access to the ClearCost estimate engine and your exclusive leads. Available on the Enterprise plan. Base URL https://getclearcost.com/api/v1.

Authentication

Create a key under Website Embed → API access. Send it as a Bearer token. Keys are shown once at creation; store them securely. Requests are rate limited per account.

Authorization header

Authorization: Bearer cc_live_xxx

POST /v1/estimate

Returns a Fair Market Rate using your per-account price calibration. Does not create a lead.

cURL

curl -X POST https://getclearcost.com/api/v1/estimate \
  -H "Authorization: Bearer cc_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "category": "deck",
    "zipCode": "30080",
    "dimensionsSqft": 320,
    "finishLevel": "standard",
    "features": ["post_cap_lights"]
  }'

Response: { estimate: { min_price, max_price, labor_hours, labor_cost, material_cost, confidence }, scope_inclusions: [...] }

POST /v1/leads

Prices the project server-side and creates an exclusive lead (also fires your CRM webhook + email).

cURL

curl -X POST https://getclearcost.com/api/v1/leads \
  -H "Authorization: Bearer cc_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "category": "deck",
    "zipCode": "30080",
    "dimensionsSqft": 320,
    "finishLevel": "standard",
    "features": [],
    "customerName": "Jane Doe",
    "customerEmail": "jane@example.com",
    "customerPhone": "555-123-4567"
  }'

Response: { lead_id, pricing: { minPrice, maxPrice } } (HTTP 201).

GET /v1/leads

Lists your embed leads, newest first. Query params limit (max 100) and offset.

Errors

Errors return { "error": "..." } with a standard status code: 400 (validation), 401 (bad/missing key), 403 (plan lacks API access or inactive subscription), 429 (rate limited), 500 (server error).