> ## Documentation Index
> Fetch the complete documentation index at: https://docs.homeservicedata.org/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Quick Start: Make Your First Home Service Data API Call

> Learn how to make your first Home Service Data API call and fetch quote-safe finance fee records.

This guide walks you through making your first request to the Home Service Data API. By the end, you will have retrieved published finance fee records filtered to a specific trade, proving your API key works and showing the shape of a typical response.

## Prerequisites

* A Home Service Data account. [Request access](https://homeservicedata.org/contact) if you do not have one yet.
* An API key from your dashboard [API Keys page](/docs/dashboard/api-keys).

<Steps>
  <Step title="Get your API key">
    Open your [Dashboard → API Keys](/docs/dashboard/api-keys) page and copy an active key. Your key looks like `hsd_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx`.
  </Step>

  <Step title="Make your first request">
    Fetch published quote-safe solar finance fee records by passing your key in the `x-api-key` header:

    ```bash theme={null}
    curl -X GET "https://homeservicedata.org/api/v1/finance/fees?trade=solar" \
      -H "x-api-key: YOUR_API_KEY"
    ```

    A successful response looks like:

    ```json theme={null}
    {
      "data": [
        {
          "finance_program_version_id": "fpv_abc123",
          "financier_name": "Acme Lender",
          "financier_slug": "acme-lender",
          "product_title": "25-Year 0% APR",
          "payment_type": "loan",
          "term_months": 300,
          "fee_percentage": 28.5,
          "trade_category": "solar",
          "quote_safe": true,
          "last_verified_at": "2025-01-15T00:00:00Z"
        }
      ],
      "error": null,
      "meta": {
        "request_id": "req_01J...",
        "api_version": "2026-06-30",
        "dataset_version": null,
        "trust": {
          "endpoint": "/api/v1/finance/fees",
          "level": "quote_safe",
          "use_case": "Approved finance fee records for production quote workflows.",
          "data_rights_note": "Use only within your workspace entitlement.",
          "required_response_fields": ["quote_safe", "last_verified_at"]
        },
        "performance": {
          "target_ms": 250,
          "warn_ms": 500,
          "max_response_bytes": 65536,
          "basis": "server"
        }
      }
    }
    ```
  </Step>

  <Step title="Filter to your needs">
    Add query parameters to narrow results. For example, fetch only HVAC finance programs from a specific lender:

    ```bash theme={null}
    curl -X GET "https://homeservicedata.org/api/v1/finance/fees?trade=hvac&payment_type=loan" \
      -H "x-api-key: YOUR_API_KEY"
    ```
  </Step>

  <Step title="Check the quote_safe flag">
    Before using any record in a customer-facing quote, verify `quote_safe: true`. Context-only rows (`quote_safe: false`) are useful for market research but should not appear in quotes.

    ```typescript theme={null}
    const response = await fetch('https://homeservicedata.org/api/v1/finance/fees?trade=solar', {
      headers: { 'x-api-key': process.env.HSD_API_KEY! }
    });
    const { data } = await response.json();

    // Filter to only quote-safe rows before displaying to customers
    const quoteSafePrograms = data.filter((row: any) => row.quote_safe === true);
    ```
  </Step>
</Steps>

## Next steps

<CardGroup cols={2}>
  <Card title="Authentication" icon="key" href="/docs/authentication">
    Learn about API key scopes and how to manage keys.
  </Card>

  <Card title="Quote Context" icon="file-invoice-dollar" href="/docs/api-reference/quote-context">
    Bundle finance, equipment, and context data in a single call.
  </Card>

  <Card title="Sync Integration" icon="arrows-rotate" href="/docs/guides/sync-integration">
    Keep your database in sync with dataset snapshots and deltas.
  </Card>

  <Card title="API Reference" icon="code" href="/docs/api-reference/overview">
    Explore all available endpoints.
  </Card>
</CardGroup>