GET /api/v1/finance/fees — Dealer Fee Records

The /api/v1/finance/fees endpoint returns approved, quote-safe dealer-fee and finance-program rows from the finance_fees dataset. Every row returned has quote_safe: true, meaning it has passed verification review and is cleared for use in customer-facing quote calculations. Results are ordered by financier_name then product_title and reflect the most recently verified version of each fee record.

This endpoint requires production access to the finance_fees dataset. Sandbox-tier keys will receive a 403 response. Request access →

Endpoint

GET https://homeservicedata.org/api/v1/finance/fees

Request

Headers

string

required

Your API key. Pass the value exactly as shown in your dashboard.

Query Parameters

string

Filter by trade category. Matched against the trade_category field (case-insensitive). Accepted values: solar, hvac, roofing, plumbing, electrical.

string

Filter by financier slug (e.g. goodleap, sunlight_financial). Matched against the financier_slug field.

string

Filter by payment product type. Matched against the payment_type field (case-insensitive). Common values: loan, lease, ppa, cash.

integer

Exact term filter in months (e.g. 120, 180, 240). Must be a valid integer or the request returns a 400 error.

number

Exact interest rate filter as a decimal (e.g. 0.0 for 0% promos). Must be a valid number or the request returns a 400 error.

integer

Maximum number of records to return. Defaults to 1000; hard cap is 5000.

Response

A successful response returns an application/json object with a top-level data array of dealer-fee records and a usage block for your request metering.

Response Fields

array

Array of dealer-fee record objects. Every object in this array has quote_safe: true.

Show DealerFeeRecord fields

string

Stable UUID for this version of the finance program row. Use this as the primary record identifier.

string

UUID for this version of the dealer-fee entry. Distinct from finance_program_version_id — a single finance program can have multiple dealer-fee versions over time.

string | null

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

string

The trade this fee record applies to. One of: solar, hvac, roofing, plumbing, electrical.

string

Display name of the lender or financing company (e.g. GoodLeap, Sunlight Financial).

string

URL-safe identifier for the financier. Use this value in the financier query parameter.

string

The lender’s own product name for this fee row (e.g. GoodLeap 2.99% 20yr).

string

Product category. Common values: loan, lease, ppa, cash.

string | null

Integration platform or channel associated with this fee row (e.g. solar_nexus, enerflo), if applicable.

number | null

Nominal annual interest rate as a decimal (e.g. 0.0299 for 2.99%). null for products where a fixed rate is not applicable.

integer | null

Loan or lease term length in months. null when not applicable (e.g. cash products).

number | null

Dealer fee as a percentage of the financed amount (e.g. 0.25 for 25%). null when no dealer fee applies.

string

ISO 8601 date on which this fee record became effective (YYYY-MM-DD).

string | null

ISO 8601 datetime after which this fee record is no longer valid. null if there is no scheduled expiry.

string

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

boolean

Always true for records returned by this endpoint. Records that have not passed verification review are excluded from results.

object

Request metering information tied to your API key.

Show usage fields

string

The endpoint path that was called.

integer

HTTP status code of the response.

number

Server-side processing time in milliseconds.

Examples

curl -G https://homeservicedata.org/api/v1/finance/fees \
  -H "x-api-key: YOUR_API_KEY" \
  --data-urlencode "trade=solar"

import requests

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

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

Example Response

{
  "data": [
    {
      "finance_program_version_id": "c3d2e1f0-aaaa-bbbb-cccc-000000000001",
      "dealer_fee_version_id": "d4e3f2a1-bbbb-cccc-dddd-000000000002",
      "source_document_id": "src_abc123",
      "trade_category": "solar",
      "financier_name": "GoodLeap",
      "financier_slug": "goodleap",
      "product_title": "GoodLeap 2.99% 20yr",
      "payment_type": "loan",
      "integration": "enerflo",
      "interest_rate": 0.0299,
      "term_months": 240,
      "fee_percentage": 0.25,
      "effective_date": "2024-01-01",
      "expires_at": null,
      "last_verified_at": "2024-11-15T08:00:00.000Z",
      "quote_safe": true
    },
    {
      "finance_program_version_id": "a1b2c3d4-eeee-ffff-0000-111111111111",
      "dealer_fee_version_id": "b2c3d4e5-ffff-0000-1111-222222222222",
      "source_document_id": "src_def456",
      "trade_category": "solar",
      "financier_name": "Sunlight Financial",
      "financier_slug": "sunlight_financial",
      "product_title": "Sunlight 0% 12yr",
      "payment_type": "loan",
      "integration": null,
      "interest_rate": 0.0,
      "term_months": 144,
      "fee_percentage": 0.36,
      "effective_date": "2024-03-01",
      "expires_at": "2025-03-01T00:00:00.000Z",
      "last_verified_at": "2024-10-20T12:30:00.000Z",
      "quote_safe": true
    }
  ],
  "usage": {
    "endpoint": "/api/v1/finance/fees",
    "status_code": 200,
    "duration_ms": 43
  }
}

Error Reference

Status	Cause
`400`	`term_months` or `interest_rate` is not a valid number.
`401`	Missing or invalid `x-api-key` header.
`403`	Your key does not have production access to the `finance_fees` dataset.
`500`	Internal server error — contact support if this persists.

Pair term_months with interest_rate to look up a single canonical fee row for a specific product configuration. For broader lender context — loan limits, APR ranges, and eligible measures — use GET /api/v1/context/finance-products.

Overview

Search & Catalog

Finance

Equipment & Hardware

Context Datasets

Composite

Sync

GET /api/v1/finance/fees — Dealer Fee Records

Endpoint

Request

Headers

Query Parameters

Response

Response Fields

Examples

Example Response

Error Reference

​Endpoint

​Request

​Headers

​Query Parameters

​Response

​Response Fields

​Examples

​Example Response

​Error Reference

Endpoint

Request

Headers

Query Parameters

Response

Response Fields

Examples

Example Response

Error Reference