Skip to main content
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 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). 
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 utilityId (for example, 14328 for PG&E) and choose one of the returned entries in ratePlans. Each plan now includes both id and rateID: use id as the ratePlanId in the next step, and use rateID if you want the semantic normalized tariff reference. As of April 19, 2026, the public docs source publishes this lookup flow under POST /v1/utility/get; it does not list a public GET /v1/utility/plans endpoint.

​
1.2 Create the Home

Now, create a home using the IDs you just found. 
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>"
         }'
Response: 
{
  "id": "ws_home_123456789"
}
Save the id from the response. This is your homeId.

​
Step 2: Get Price Signal

Now that you have a home with a utility and rate plan, you can immediately generate a price signal! 
curl -X POST "https://api.wattshift.com/v1/homes/<your_home_id>/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. 
{
  "prices": [
    {
      "start": "2023-10-27T00:00:00Z",
      "price": 0.24
    },
    ...
  ]
}

​
Congratulations!

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

​
Next Steps

  • Explore Onboarding Options: Learn about our UI Based Onboarding for a user-friendly experience.
  • Calculate Impacts: Use the Impact Calculations endpoint to estimate bill savings.
  • Automate with Webhooks: Set up Webhooks to receive price signals automatically. ₹