GET /api/v1/context/finance-eligibility — Eligibility Records

The /api/v1/context/finance-eligibility endpoint returns eligible-product records from the finance_eligibility dataset. Each record describes which specific product types and measures a lender or PACE program makes available in a given state, county, or scope — including whether a permit is required, what the maximum term is, and the availability status. Records are granular by design: a single program may produce multiple rows, one per criteria_scope (e.g. hillsborough_county, sarasota_county, all_other_counties).

Eligibility records sourced from contractor-uploaded PDFs carry quote_safe: false until an official public source or admin review approves them. Use the quote_safe filter or always inspect the field on each record before building proposal logic from it.

Endpoint

GET https://homeservicedata.com/api/v1/context/finance-eligibility

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 400 for unrecognized values.

state

string

Two-letter state code (e.g. GA, FL). Filters on state_code (exact match, case-insensitive). Returns 400 for values that are not a two-letter code.

measure

string

Slugified measure key to filter on (e.g. solar_panels, heat_pump). Matched against measure_key using exact slug equality.

financier

string

Financier slug or name. Slugified and matched against financier_slug (exact).

program_type

string

Filter by program type. Accepted values: pace, loan, lease, home_improvement_loan, rebate, unknown.

county

string

County name used to resolve criteria_scope. Records with criteria_scope matching the county key are returned, along with all_other_counties records for non-specifically-scoped counties. See criteria_scope below.

product

string

Substring match against product_label (case-insensitive). Useful for narrowing to a specific product name within a program.

quote_safe

boolean

Pass true to return only verified eligibility records; false for unverified context only. Omit to return all.

limit

integer

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

Understanding `criteria_scope`

criteria_scope encodes the geographic resolution of each eligibility rule. A single program often publishes different product availability or term limits by county, so a program with statewide coverage in Florida might have three records:

`criteria_scope`	Meaning
`hillsborough_county`	Rule applies specifically to Hillsborough County
`sarasota_county`	Rule applies specifically to Sarasota County
`all_other_counties`	Rule applies to every other county in the state

When you pass the county query parameter, the API resolves the county name to a scope key and returns matching records. Unrecognized county names are resolved to all_other_counties. If no county is passed, records for all scopes are returned.

Response

A successful response returns data.records (the eligibility rows), data.coverage (filter summary), and a usage block.

Response Fields

data.records

array

Array of finance eligibility records, ordered by trade_category, product_label, and criteria_scope ascending.

Show FinanceEligibilityRecord fields

string

Stable UUID for this eligibility record.

source_document_id

string | null

ID of the source document this record was extracted from.

financier_name

string

Display name of the lender or PACE administrator.

financier_slug

string

URL-safe lender identifier. Pass this value in the financier query parameter.

program_name

string

Full name of the finance program (e.g. PACE Florida, GoodLeap HVAC Loan).

program_type

string

Program category: pace, loan, lease, home_improvement_loan, rebate, or unknown.

trade_category

string

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

measure_key

string | null

Slugified measure identifier this record applies to (e.g. solar_panels, battery_storage, heat_pump). null if the record applies to all measures within the trade.

product_type

string | null

Product type sub-classification within the program (e.g. pace, loan).

product_label

string | null

Human-readable label for the product as written in the source document.

criteria_scope

string | null

Geographic scope of this eligibility rule. One of: a county slug (e.g. hillsborough_county), all_other_counties, or null for statewide/unconstrained rules. See Understanding criteria_scope.

state_code

string | null

Two-letter state code where this eligibility rule applies.

county_name

string | null

Raw county name from the source document, if county-specific. null for statewide records.

eligibility_criteria

object | null

Structured criteria extracted from the source (e.g. property type, ownership requirements, income limits).

permit_required

boolean | null

Whether a permit is required to use this financing product for the measure. null if not stated in the source.

max_term_years

number | null

Maximum financing term in years for this product/measure combination.

availability_status

string | null

Current availability of this product in the scoped area: e.g. available, suspended, limited.

quote_safe

boolean

true if this record has passed verification review. Always inspect this field before building proposal logic.

confidence

string | null

Data confidence tier: high, medium, or low.

effective_date

string | null

ISO 8601 date when this eligibility rule became effective.

expires_at

string | null

ISO 8601 datetime after which this eligibility record expires.

last_verified_at

string

ISO 8601 datetime of the most recent source verification.

source_url

string | null

URL of the source document or page.

unresolved_requirements

string[] | null

Requirement statements from the source that could not be parsed into structured fields.

source_title

string | null

Human-readable title of the source document.

source_kind

string | null

Provenance category: e.g. official_lender_doc, contractor_upload, web_scrape.

data.coverage

object

Summary of filters applied to this request.

Show coverage fields

trade

string

Applied trade filter, or "all".

state

string | null

Applied state filter (uppercased), or null.

county

string | null

Applied county filter, or null.

financier

string | null

Applied financier filter, or null.

program_type

string

Applied program type filter, or "all".

measure

string | null

Applied measure filter, or null.

product

string | null

Applied product substring filter, or null.

returned

integer

Number of records in this response after all filters.

source

string

The dataset key that backed this response: finance_eligibility.

quote_safe_rule

string

Explanation of quote_safe semantics for this endpoint.

Examples

curl -G https://homeservicedata.com/api/v1/context/finance-eligibility \
  -H "x-api-key: YOUR_API_KEY" \
  --data-urlencode "trade=hvac" \
  --data-urlencode "state=GA"

Example Response

{
  "data": {
    "records": [
      {
        "id": "elig_001bbb",
        "source_document_id": "src_ga_pace_001",
        "financier_name": "Ygrene Energy Fund",
        "financier_slug": "ygrene_energy_fund",
        "program_name": "Ygrene PACE Georgia",
        "program_type": "pace",
        "trade_category": "hvac",
        "measure_key": "heat_pump",
        "product_type": "pace",
        "product_label": "Ygrene PACE — Heat Pump",
        "criteria_scope": "all_other_counties",
        "state_code": "GA",
        "county_name": null,
        "eligibility_criteria": {
          "property_type": ["residential", "commercial"],
          "ownership_required": true
        },
        "permit_required": true,
        "max_term_years": 25,
        "availability_status": "available",
        "quote_safe": true,
        "confidence": "high",
        "effective_date": "2023-06-01",
        "expires_at": null,
        "last_verified_at": "2024-10-05T14:00:00.000Z",
        "source_url": "https://ygrene.com/contractors/georgia",
        "unresolved_requirements": null,
        "source_title": "Ygrene Georgia Contractor Program Guide",
        "source_kind": "official_lender_doc"
      }
    ],
    "coverage": {
      "trade": "hvac",
      "state": "GA",
      "county": null,
      "financier": null,
      "program_type": "all",
      "measure": null,
      "product": null,
      "returned": 1,
      "source": "finance_eligibility",
      "quote_safe_rule": "Eligibility lists from contractor-uploaded PDFs are context until an official public/current source or admin approval marks them quote-safe."
    }
  },
  "usage": {
    "endpoint": "/api/v1/context/finance-eligibility",
    "status_code": 200,
    "duration_ms": 52
  }
}

Error Reference

Status	Cause
`400`	Invalid `trade`, `program_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_eligibility` dataset.
`500`	Internal server error.

Combine state, trade, and measure to scope eligibility records to a single job type (e.g. HVAC heat pumps in Georgia). Then cross-reference financier_slug with /api/v1/context/finance-products to pull the matching program’s APR ranges and loan limits in one workflow.

​Endpoint

​Request

​Headers

​Query Parameters

​Understanding criteria_scope

​Response

​Response Fields

​Examples

​Example Response

​Error Reference

Endpoint

Request

Headers

Query Parameters

Understanding `criteria_scope`

Response

Response Fields

Examples

Example Response

Error Reference