Skip to main content
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.com/api/v1/finance/fees

​
Request

​
Headers

​
x-api-key
string
required
Your API key. Pass the value exactly as shown in your dashboard.

​
Query Parameters

​
trade
string
Filter by trade category. Matched against the trade_category field (case-insensitive). Accepted values: solar, hvac, roofing, plumbing, electrical.
​
financier
string
Filter by financier slug (e.g. goodleap, sunlight_financial). Matched against the financier_slug field.
​
payment_type
string
Filter by payment product type. Matched against the payment_type field (case-insensitive). Common values: loan, lease, ppa, cash.
​
term_months
integer
Exact term filter in months (e.g. 120, 180, 240). Must be a valid integer or the request returns a 400 error.
​
interest_rate
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.
​
limit
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

​
data
array
Array of dealer-fee record objects. Every object in this array has quote_safe: true.
​
usage
object
Request metering information tied to your API key.

​
Examples

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

​
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

StatusCause
400term_months or interest_rate is not a valid number.
401Missing or invalid x-api-key header.
403Your key does not have production access to the finance_fees dataset.
500Internal 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.