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.com/api/v1/context/finance-products

Request

Headers

x-api-key

string

required

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

Query Parameters

trade

string

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

product_type

string

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

state

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.

financier

string

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

measure

string

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

quote_safe

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.

limit

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

data.records

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.

source_document_id

string | null

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

trade_category

string

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

financier_name

string

Display name of the lender or financing company.

financier_slug

string

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

product_name

string

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

product_type

string

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

state_scope

string[] | null

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

loan_amount_min

number | null

Minimum eligible project or loan amount in USD.

loan_amount_max

number | null

Maximum eligible project or loan amount in USD.

term_months_min

integer | null

Shortest available term in months.

term_months_max

integer | null

Longest available term in months.

apr_min

number | null

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

apr_max

number | null

Highest advertised APR as a decimal.

dealer_fee_type

string | null

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

dealer_fee_flat

number | null

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

dealer_fee_percent_min

number | null

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

dealer_fee_percent_max

number | null

High end of the dealer fee percentage range.

eligible_measures

string[] | null

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

ineligible_measures

string[] | null

Measure keys explicitly excluded from this product.

requirements

object | null

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

unresolved_requirements

string[] | null

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

status

string

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

quote_safe

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.

confidence

string | null

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

effective_date

string | null

ISO 8601 date when this product context became effective.

expires_at

string | null

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

source_url

string | null

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

last_verified_at

string

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

source_title

string | null

Human-readable title of the source document.

source_kind

string | null

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

data.coverage

object

Summary of applied filters and result metadata.

Show coverage fields

trade

string

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

financier

string | null

The financier filter applied, or null.

product_type

string

The product_type filter applied, or "all".

state

string | null

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

measure

string | null

The measure filter applied, or null.

returned

integer

Number of records included in this response after all filters.

source

string

The dataset key that backed this response: finance_products.

quote_safe_rule

string

Prose explanation of the quote_safe semantics for this endpoint.

Examples

curl -G https://homeservicedata.com/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"

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.

​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