API & Integration Docs

Embed Widget

Add the HomeBuyerCalc calculator to your website with a single code snippet. The widget is fully responsive and renders with your custom branding (logo, colors, CTA text) configured in the Branding dashboard.

Option 1: iframe (Recommended)

Drop-in embed. Works with any CMS, WordPress, Squarespace, Webflow, or static HTML site.

<iframe
  src="https://homebuyercalc.com/embed/your-partner-slug"
  width="100%"
  height="800"
  frameborder="0"
  style="border:0; border-radius:8px;"
  allow="clipboard-write"
></iframe>

Option 2: JavaScript Snippet

Dynamic embed with auto-resizing. The script creates the iframe and adjusts height to match content.

<div id="homebuyercalc-widget"></div>
<script
  src="https://homebuyercalc.com/widget.js"
  data-slug="your-partner-slug"
  data-container="homebuyercalc-widget"
></script>

Widget Attributes

WordPress Example

Paste this into a Custom HTML block in the WordPress editor.

<div style="max-width:720px; margin:0 auto;">
  <iframe
    src="https://homebuyercalc.com/embed/your-partner-slug"
    width="100%"
    height="800"
    frameborder="0"
    style="border:0; border-radius:8px;"
    allow="clipboard-write"
  ></iframe>
</div>

Works in any page builder (Elementor, Divi, Beaver Builder) that supports HTML blocks.

Webflow / Squarespace

White-Label Setup

Run a fully branded affordability calculator under your own identity. Buyers see your logo, your colors, and your CTA — HomeBuyerCalc stays in the background.

How White-Labeling Works

Branding Options

Your Branded Calculator Page

Every partner gets a hosted page that you can share directly:

https://homebuyercalc.com/embed/your-partner-slug

This page includes the full 6-step wizard (entry, location, finances, profile, results, and lead capture) with your branding applied. Use it in email campaigns, social posts, or as a standalone landing page.

Lead Capture Flow

The embed widget replaces the AI Chat step (step 6) with a lead capture form. When a buyer completes the wizard:

Advanced: CSS Overrides (iframe)

The embed page applies your primary_color as a CSS custom property. If you need more granular control, you can override styles via the parent page:

/* Constrain widget width and center it */
#homebuyercalc-widget iframe {
  max-width: 720px;
  margin: 0 auto;
  display: block;
  border-radius: 12px;
  box-shadow: 0 4px 24px rgba(0,0,0,0.15);
}

Note: styles inside the iframe are controlled by your Branding settings. Parent-page CSS only affects the iframe container itself.

Authentication

All API requests require a Bearer token in the Authorization header. Generate API keys from your dashboard.

Authorization: Bearer hbc_live_your_api_key_here

API keys use the prefix hbc_live_ followed by 32 hex characters. Keys are hashed on our side and cannot be retrieved after creation.

Calculate Scenarios

Generate loan scenarios with detailed monthly payment breakdowns for a given buyer profile.

Request Body

Example Request

curl -X POST https://homebuyercalc.com/v1/calculate \
  -H "Authorization: Bearer hbc_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "entry_mode": "price",
    "home_price": 450000,
    "state": "CA",
    "annual_income": 120000,
    "monthly_debts": 500,
    "credit_band": "good",
    "cash_for_down_payment": 50000,
    "is_first_time_buyer": true,
    "is_veteran": false
  }'

Example Response

{
  "data": {
    "request_id": "550e8400-e29b-...",
    "scenarios": [
      {
        "loanType": "conventional",
        "downPaymentPct": 0.10,
        "downPaymentAmt": 45000,
        "loanAmount": 405000,
        "interestRate": 0.06875,
        "termYears": 30,
        "monthlyPayment": {
          "principalAndInterest": 2662,
          "propertyTax": 469,
          "homeInsurance": 150,
          "pmi": 169,
          "total": 3450
        },
        "cashToClose": 54200,
        "dtiRatio": 0.39
      }
    ],
    "max_affordable_price": 520000,
    "calculated_at": "2026-03-07T..."
  },
  "_meta": {
    "api_version": "1.0.0",
    "duration_ms": 12
  }
}

Detailed Scenarios

Similar to /v1/calculate but returns extended scenario data with an input summary. Accepts the same request body using snake_case field names.

See the /v1/calculate section for the full request body reference.

Lead Capture API

Submit a lead from your own form or application. No API key required — the partner is identified by partner_slug in the request body. This is the same endpoint used by the embed widget.

Request Body

Example: Basic Lead

curl -X POST https://homebuyercalc.com/api/leads \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Jane Smith",
    "email": "jane@example.com",
    "phone": "(555) 123-4567",
    "partner_slug": "acme-lending"
  }'

Example: Lead with Full Profile + Scenarios

curl -X POST https://homebuyercalc.com/api/leads \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Jane Smith",
    "email": "jane@example.com",
    "partner_slug": "acme-lending",
    "consumer_profile": {
      "entry_mode": "price",
      "home_price": 450000,
      "state": "CA",
      "annual_income": 120000,
      "monthly_debts": 500,
      "credit_band": "good",
      "cash_for_down_payment": 50000,
      "is_first_time_buyer": true
    },
    "scenario_results": [
      { "loanType": "conventional", "monthlyPayment": { "total": 3450 } },
      { "loanType": "fha", "monthlyPayment": { "total": 3280 } }
    ]
  }'

Response

{
  "data": {
    "lead_id": "a1b2c3d4e5f6...",
    "message": "Lead captured successfully."
  }
}

When consumer_profile is provided, a full consumer profile and scenario run are stored and linked to the lead automatically.

Error Codes

All errors follow a consistent format with an error object containing code and message fields.

Error Response Format

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid input.",
    "details": {
      "fieldErrors": {
        "state": ["String must contain exactly 2 character(s)"]
      }
    }
  }
}

Rate Limits

API requests are rate-limited per partner account. The default limit is 100 requests per minute. When exceeded, the API returns a 429 status with a RATE_LIMITED error code.

Brokerage and Enterprise plans can request higher limits. Contact support@homebuyercalc.com for details.

CORS

All /v1/* endpoints support CORS with Access-Control-Allow-Origin: *. This means you can call the API directly from browser-based JavaScript applications.

Preflight OPTIONS requests are handled automatically and return a 204 response with appropriate CORS headers.