GET /api/v1/context/finance-products — Lender Context

The /api/v1/context/finance-products endpoint returns lender and finance-program context records from the finance_products dataset. These records capture broad product facts — loan amount windows, APR ranges, dealer fee structures, eligible and ineligible measures, and sourcing metadata — and are designed for enrichment, comparison, and CRM display rather than direct quote calculation. They are distinct from the quote-safe dealer-fee rows returned by /api/v1/finance/fees.

Not all records returned by this endpoint are quote-safe. Always check the quote_safe field before using a record in a customer-facing quote. Context records sourced from contractor-uploaded PDFs, sample agreements, or lender summaries may have quote_safe: false until an official rate or dealer-fee table is approved.

Endpoint

GET https://homeservicedata.org/api/v1/context/finance-products

Request

Headers

string

required

Your API key. Obtain or rotate keys in your dashboard.

Query Parameters

string

Filter by trade category (case-insensitive). Accepted values: solar, hvac, roofing, plumbing, electrical. Returns a 400 for unrecognized values.

string

Filter by product type. Accepted values: loan, lease, pace, home_improvement_loan, credit_application, backup_plan, checklist, unknown.

string

Two-letter state code (e.g. CA, TX). Post-filters records by state_scope — records with an empty state_scope are returned for any state.

string

Financier name or slug. Matched against both financier_slug (exact) and financier_name (substring, case-insensitive).

string

Filter to records whose eligible_measures array contains this exact value (case-insensitive), e.g. battery_storage, heat_pump.

boolean

Pass true to return only verified records; false to return only unverified context. Omit to return all records. Returns a 400 for values other than true or false.

integer

Maximum number of records to return. Defaults to 100; hard cap is 250.

Response

A successful response returns an application/json object with data.records (the program context rows), data.coverage (a summary of the applied filters), and a usage block.

Response Fields

array

Array of finance product context objects, ordered by quote_safe descending then last_verified_at descending.

Show FinanceProductRecord fields

string

Stable UUID for this finance product context record.

string | null

ID of the source document from which this record was extracted.

string

Trade this product applies to: solar, hvac, roofing, plumbing, or electrical.

string

Display name of the lender or financing company.

string

URL-safe lender identifier. Use this in the financier filter parameter.

string

Lender’s own product name for this program context record.

string

Product category: loan, lease, pace, home_improvement_loan, credit_application, backup_plan, checklist, or unknown.

string[] | null

Array of two-letter state codes this product is available in. An empty array means nationwide availability. null indicates scope is unknown.

number | null

Minimum eligible project or loan amount in USD.

number | null

Maximum eligible project or loan amount in USD.

integer | null

Shortest available term in months.

integer | null

Longest available term in months.

number | null

Lowest advertised APR as a decimal (e.g. 0.0 for 0% promo tiers).

number | null

Highest advertised APR as a decimal.

string | null

Describes how the dealer fee is structured: e.g. percentage, flat, tiered.

number | null

Flat dealer fee amount in USD, when dealer_fee_type is flat.

number | null

Low end of the dealer fee percentage range (e.g. 0.2 for 20%).

number | null

High end of the dealer fee percentage range.

string[] | null

Measure keys this product can finance (e.g. ["solar_panels", "battery_storage"]).

string[] | null

Measure keys explicitly excluded from this product.

object | null

Structured requirement facts extracted from the source (e.g. minimum credit score, contractor enrollment rules).

string[] | null

List of requirement statements from the source document that could not be parsed into structured fields. Review these manually before quoting.

string

Internal record lifecycle status (e.g. active, superseded, archived).

boolean

true if this record has passed verification review and is cleared for use in quotes. false for unverified context records. Always check this field.

string | null

Data confidence tier as assessed during extraction: high, medium, or low.

string | null

ISO 8601 date when this product context became effective.

string | null

ISO 8601 datetime after which this context record is no longer valid.

string | null

URL of the source document or page from which this record was derived.

string

ISO 8601 datetime when this record was last confirmed against a source.

string | null

Human-readable title of the source document.

string | null

Provenance category of the source: e.g. official_lender_doc, contractor_upload, web_scrape.

object

Summary of applied filters and result metadata.

Show coverage fields

string

The trade filter applied, or "all" if not filtered.

string | null

The financier filter applied, or null.

string

The product_type filter applied, or "all".

string | null

The state filter applied (uppercased two-letter code), or null.

string | null

The measure filter applied, or null.

integer

Number of records included in this response after all filters.

string

The dataset key that backed this response: finance_products.

string

Prose explanation of the quote_safe semantics for this endpoint.

Examples

curl -G https://homeservicedata.org/api/v1/context/finance-products \
  -H "x-api-key: YOUR_API_KEY" \
  --data-urlencode "trade=solar" \
  --data-urlencode "product_type=loan" \
  --data-urlencode "state=CA"

import requests

resp = requests.get(
    "https://homeservicedata.org/api/v1/context/finance-products",
    headers={"x-api-key": "YOUR_API_KEY"},
    params={"trade": "solar", "product_type": "loan", "state": "CA"},
)
records = resp.json()["data"]["records"]

const res = await fetch(
  "https://homeservicedata.org/api/v1/context/finance-products?trade=solar&product_type=loan&state=CA",
  { headers: { "x-api-key": "YOUR_API_KEY" } }
);
const { records } = (await res.json()).data;

Example Response

{
  "data": {
    "records": [
      {
        "id": "fp_001aaa",
        "source_document_id": "src_xyz789",
        "trade_category": "solar",
        "financier_name": "GoodLeap",
        "financier_slug": "goodleap",
        "product_name": "GoodLeap Standard Loan",
        "product_type": "loan",
        "state_scope": ["CA", "TX", "FL", "AZ"],
        "loan_amount_min": 5000,
        "loan_amount_max": 150000,
        "term_months_min": 60,
        "term_months_max": 300,
        "apr_min": 0.0,
        "apr_max": 0.0799,
        "dealer_fee_type": "percentage",
        "dealer_fee_flat": null,
        "dealer_fee_percent_min": 0.18,
        "dealer_fee_percent_max": 0.36,
        "eligible_measures": ["solar_panels", "battery_storage", "ev_charger"],
        "ineligible_measures": null,
        "requirements": {
          "min_credit_score": 600,
          "contractor_enrollment": "required"
        },
        "unresolved_requirements": null,
        "status": "active",
        "quote_safe": true,
        "confidence": "high",
        "effective_date": "2024-01-01",
        "expires_at": null,
        "source_url": "https://goodleap.com/dealer-program-guide",
        "last_verified_at": "2024-11-10T09:00:00.000Z",
        "source_title": "GoodLeap Dealer Program Guide 2024",
        "source_kind": "official_lender_doc"
      }
    ],
    "coverage": {
      "trade": "solar",
      "financier": null,
      "product_type": "loan",
      "state": "CA",
      "measure": null,
      "returned": 1,
      "source": "finance_products",
      "quote_safe_rule": "Quick facts, sample agreements, and contractor-uploaded lender summaries return as context unless an official deterministic rate/dealer-fee table has been approved."
    }
  },
  "usage": {
    "endpoint": "/api/v1/context/finance-products",
    "status_code": 200,
    "duration_ms": 58
  }
}

Finance Products vs. Finance Fees

	`/context/finance-products`	`/finance/fees`
Purpose	Lender program enrichment and comparison	Quote-safe dealer-fee rows for calculation
`quote_safe`	Mixed — check per record	Always `true`
Dealer fee fields	Ranges (`min`/`max`)	Exact `fee_percentage`
Rate fields	APR range (`apr_min`/`apr_max`)	Exact `interest_rate`
Best for	CRM display, product comparison, eligibility checks	Quoting engines, proposal builders

Use the measure filter to pre-screen which lender products support a specific installation type (e.g. battery_storage, heat_pump) before fetching exact fee rows from /api/v1/finance/fees.

Error Reference

Status	Cause
`400`	Invalid `trade`, `product_type`, `quote_safe`, or `state` parameter value.
`401`	Missing or invalid `x-api-key` header.
`403`	Your key does not have access to the `finance_products` dataset.
`500`	Internal server error.

Overview

Search & Catalog

Finance

Equipment & Hardware

Context Datasets

Composite

Sync

GET /api/v1/context/finance-products — Lender Context

Endpoint

Request

Headers

Query Parameters

Response

Response Fields

Examples

Example Response

Finance Products vs. Finance Fees

Error Reference

​Endpoint

​Request

​Headers

​Query Parameters

​Response

​Response Fields

​Examples

​Example Response

​Finance Products vs. Finance Fees

​Error Reference

Endpoint

Request

Headers

Query Parameters

Response

Response Fields

Examples

Example Response

Finance Products vs. Finance Fees

Error Reference