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

# Quickstart Guide

> From Zero to Price Signal in 5 Minutes

<script type="text/javascript" id="hs-script-loader" async defer src="//js.hs-scripts.com/46106422.js" />

Welcome to WattShift! This guide will walk you through the fastest way to get your first Price Signal using our API.

## Prerequisites

Before you begin, make sure you have your **API Key**.
If you haven't obtained one yet, follow the [Get API Key](/docs/get_started/get-api-keys) guide.

## Step 1: Onboard a Home

For this quickstart, we'll use the **API Based Onboarding** method to programmatically create a home. This is the fastest way to test the flow.

### 1.1 Find a Utility and Rate Plan

First, let's find a valid utility and rate plan for a test zip code (e.g., `95313`).

```bash theme={null}
curl -X POST "https://api.wattshift.com/v1/utility/get" \
     -H "x-ws-api-key: <your_api_key>" \
     -H "Content-Type: application/json" \
     -d '{ "zipcode": "95313" }'
```

Copy the returned `utilityId` (for example, `14328` for PG\&E) and choose one of the returned entries in `ratePlans`. Send that plan's `ratePlans[].id` value as `ratePlanId` in the next step. The companion `ratePlans[].rateID` field is the semantic normalized tariff reference.

```json theme={null}
{
  "utilityId": "14328",
  "utilityName": "Pacific Gas & Electric",
  "ratePlans": [
    {
      "id": "6915de3f881cbc6041e4c887",
      "rateID": "<semantic_rate_id>",
      "ratePlanName": "TOU-D"
    }
  ]
}
```

### 1.2 Create the Home

Now, [create a home](/api-reference/endpoint/homes/create-home) using the IDs you just found.

```bash theme={null}
curl -X POST "https://api.wattshift.com/v1/homes/create" \
     -H "x-ws-api-key: <your_api_key>" \
     -H "Content-Type: application/json" \
     -d '{
           "name": "My Test Home",
           "zipcode": "95313",
           "utilityId": "14328",
           "ratePlanId": "<selected ratePlans[].id>",
           "solarSystemSizeKw": 5,
           "isNonNetMetered": false
         }'
```

Omit `solarSystemSizeKw` and `isNonNetMetered` for non-solar homes. If you add solar later, send those same fields to `POST /v1/homes/<homeId>/update`.

**Response:**

```json theme={null}
{
  "id": "ws_home_123456789"
}
```

Save the response `id`. This is the home ID, shown as `homeId` in the examples below.

## Step 2: Get Price Signal

Now that you have a home with a utility and rate plan, you can immediately generate a home-based price signal.

```bash theme={null}
curl -X POST "https://api.wattshift.com/v1/homes/<homeId>/price_signal" \
     -H "x-ws-api-key: <your_api_key>" \
     -H "Content-Type: application/json" \
     -d '{}'
```

**Response:**
You will receive a JSON object containing the price signal data for the current day, including 15-minute interval prices.

```json theme={null}
{
  "prices": [
    {
      "start": "2023-10-27T00:00:00Z",
      "price": 0.24
    },
    ...
  ]
}
```

For more detail on time-window requests, see the [Price Signals guide](/docs/optimize_shifts_calculate_impacts/price_signal).

## Congratulations!

You've successfully onboarded a home and retrieved your first price signal.

## Next Steps

* **Explore Onboarding Options**: Learn about our [UI Based Onboarding](/docs/onboard_sites/onboarding) for a user-friendly experience.
* **Calculate Impacts**: Use the [Impact Calculations](/docs/optimize_shifts_calculate_impacts/impact_calculations) endpoint to estimate bill savings.
* **Automate with Webhooks**: Set up [Webhooks](/docs/optimize_shifts_calculate_impacts/receiving-updates) to receive price signals automatically.
  ₹