GET /api/v1/sync/snapshot — Full Dataset Snapshot

The /api/v1/sync/snapshot endpoint downloads every current record in a named dataset in a single paginated response. Each snapshot response includes a version object with a cursor string that acts as a bookmark — after loading the initial snapshot, pass that cursor to /api/v1/sync/changes to receive only the records that changed since your last sync. This two-step pattern (snapshot once, then poll changes) keeps your CRM or quoting database up to date without re-downloading entire datasets on every run. The endpoint supports conditional GET via the ETag / If-None-Match mechanism. If nothing has changed since your last snapshot, the API returns 304 Not Modified with an empty body, saving both bandwidth and API quota.

Request

GET https://homeservicedata.org/api/v1/sync/snapshot

Authentication

All requests must include your API key in the x-api-key header. The required access tier varies by dataset; most datasets require production tier.

Query Parameters

string

required

The dataset to snapshot. Must be one of the following keys:

Key	Description
`finance_fees`	Dealer-fee and finance-program rows used by quote tools
`finance_products`	Finance product catalog
`finance_eligibility`	Eligibility rules by trade, state, county, and measure
`equipment_pricing`	Equipment catalog with pricing
`utility_territory`	Utility territory boundary data
`electricity_rates`	Electricity rate data by territory
`hvac_incentives`	HVAC-specific rebate and incentive programs
`hvac_climate`	HVAC climate context by county
`hvac_labor`	HVAC labor adder records
`hvac_ahri_matches`	AHRI-certified HVAC system match records

string

Optional trade filter. When provided, only records for that trade category are returned. Must be one of solar, hvac, roofing, plumbing, or electrical. Not all datasets carry trade-scoped records — for trade-agnostic datasets the parameter is accepted but has no filtering effect.

integer

Maximum number of records to return. The ceiling varies by dataset (up to 5000 for high-volume datasets like finance_fees). When omitted, the dataset’s default maximum is used. Lowering the limit is useful during development or when testing incremental sync without pulling full production volumes.

Conditional GET (ETag)

Every 200 response includes an ETag response header. Store that value and include it as If-None-Match on your next request. If the dataset version and limit parameters have not changed, the API returns 304 Not Modified with no body, and no quota is charged for the data transfer.

# First request — no ETag yet
curl https://homeservicedata.org/api/v1/sync/snapshot?dataset=finance_fees \
  -H "x-api-key: YOUR_API_KEY" \
  -i

# Subsequent request — send stored ETag
curl https://homeservicedata.org/api/v1/sync/snapshot?dataset=finance_fees \
  -H "x-api-key: YOUR_API_KEY" \
  -H 'If-None-Match: "v42:finance_fees:all:5000"' \
  -i
# → HTTP 304 Not Modified (no body, no data charge)

Response

object

Top-level data envelope containing the snapshot payload.

Show data

object

Metadata describing the dataset that was snapshotted.

Show dataset

string

Dataset key (e.g. finance_fees).

string

Human-readable dataset title (e.g. "Finance Fee Records").

string

The default REST endpoint for this dataset (e.g. /api/v1/finance/fees).

string

Dataset source identifier for this snapshot.

string

Trade category filter applied, or "all" when no trade filter was used.

object | null

The current published version of the dataset. null if no version has been published yet.

Show version

string

UUID of this dataset version.

integer

Monotonically increasing version number.

string | null

Opaque cursor string representing this version. Pass this value as since to /api/v1/sync/changes to receive only records that changed after this snapshot.

string

ISO 8601 timestamp of when this version was published.

integer

Total number of rows in this version of the dataset.

integer

Number of rows flagged as quote_safe: true in this version.

object

Free-form object describing what changed in this version (upserts, deletes, record counts by trade, etc.).

array

Array of dataset records. Schema varies by dataset key. Each record typically includes quote_safe, trade_category, and provenance fields alongside the domain-specific payload.

object

Sync control metadata for integrating this snapshot into an incremental pipeline.

Show sync

string

Always "snapshot" for this endpoint.

string

ETag value. Store this and send it as If-None-Match on your next snapshot request to detect whether anything has changed.

string | null

Same value as version.cursor. Store this as your starting bookmark for incremental sync.

string | null

Pre-built URL for the first incremental changes request using this snapshot’s cursor. null if no cursor is available. Example: /api/v1/sync/changes?dataset=finance_fees&since=v42%3A...

Examples

curl -G https://homeservicedata.org/api/v1/sync/snapshot \
  -H "x-api-key: YOUR_API_KEY" \
  --data-urlencode "dataset=finance_fees"

curl -G https://homeservicedata.org/api/v1/sync/snapshot \
  -H "x-api-key: YOUR_API_KEY" \
  --data-urlencode "dataset=hvac_climate" \
  --data-urlencode "trade=hvac" \
  --data-urlencode "limit=200"

curl -G https://homeservicedata.org/api/v1/sync/snapshot \
  -H "x-api-key: YOUR_API_KEY" \
  -H 'If-None-Match: "v42:finance_fees:all:5000"' \
  --data-urlencode "dataset=finance_fees"

Response — 200 OK

{
  "data": {
    "dataset": {
      "key": "finance_fees",
      "title": "Finance Fee Records",
      "endpoint": "/api/v1/finance/fees",
      "source": "current_finance_fee_records",
      "trade": "all"
    },
    "version": {
      "id": "018f3a2b-1c4d-7e8f-9012-3b4c5d6e7f80",
      "number": 42,
      "cursor": "v42:finance_fees:all",
      "published_at": "2025-01-15T18:30:00.000Z",
      "row_count": 1248,
      "quote_safe_count": 1201,
      "change_summary": {
        "upserted": 14,
        "deleted": 2,
        "unchanged": 1232
      }
    },
    "records": [
      {
        "finance_program_version_id": "018f3a2b-0000-7e8f-0001-3b4c5d6e7f01",
        "trade_category": "solar",
        "financier_name": "GoodLeap",
        "financier_slug": "goodleap",
        "product_title": "GoodLeap 25-Year 5.99%",
        "quote_safe": true
        /* additional fields vary by dataset */
      }
    ],
    "sync": {
      "mode": "snapshot",
      "etag": "\"v42:finance_fees:all:5000\"",
      "cursor": "v42:finance_fees:all",
      "changes_url": "/api/v1/sync/changes?dataset=finance_fees&since=v42%3Afinance_fees%3Aall"
    }
  },
  "error": null,
  "meta": { "request_id": "req_01J...", "api_version": "2026-06-30" }
}

Response — 304 Not Modified

When If-None-Match matches the current ETag, the API returns an empty 304 response with no body.

HTTP/1.1 304 Not Modified
ETag: "v42:finance_fees:all:5000"
X-HSD-Dataset: finance_fees
X-HSD-Cursor: v42:finance_fees:all

Next Steps

Once you have a snapshot cursor, use Sync Changes to poll for incremental updates without re-downloading the full dataset.

Overview

Search & Catalog

Finance

Equipment & Hardware

Context Datasets

Composite

Sync

GET /api/v1/sync/snapshot — Full Dataset Snapshot

Request

Authentication

Query Parameters

Conditional GET (ETag)

Response

Examples

Response — 200 OK

Response — 304 Not Modified

Next Steps

​Request

​Authentication

​Query Parameters

​Conditional GET (ETag)

​Response

​Examples

​Response — 200 OK

​Response — 304 Not Modified

​Next Steps

Request

Authentication

Query Parameters

Conditional GET (ETag)

Response

Examples

Response — 200 OK

Response — 304 Not Modified

Next Steps