API Based Onboarding

Authentication

Authentication can be done in two different ways. Session tokens are useful for frontend calls, while API keys are useful for backend calls.

API Key: Add your API key in the header x-ws-api-key
-> { 'x-ws-api-key': '{apiKey}' }
Session Token: Add the token in the header Authorization as: Bearer {sessionToken}
-> { 'Authorization': 'Bearer {sessionToken}' }

How to Get a Session Token

Use this endpoint to get a session token (helpful for frontend calls): [POST] /v1/onboarding/session-token/generate

// Response Body
{ "sessionToken": "your_session_token" }

Onboarding Flow

WattShift separates discovery from evaluation:

Discovery — POST /v1/utility/get returns supported utilities and rate plans. No home is required.
Evaluation — Retrieve normalized pricing and impact outputs. This onboarding flow uses a Home as a lightweight evaluation context, not necessarily a real customer or installation; home-free impact routes are also available.

Steps to Onboard a Home

1. Fetch Utilities and Rate Plans

Fetch utilities and rate plans for a location, or look up plans for a known utility. [POST] /v1/utility/get Pass utilityId (EIA utility ID) when you already know the utility; use zipcode (or lat/long) to discover utilities for a location.

// Request (by zip code)
{ "zipcode": "95313" }

// Or lookup by EIA utility ID
{ "utilityId": "14328" }

// Response
[
  {
    "utilityId": "14328",
    "utilityName": "Pacific Gas & Electric",
    "ratePlans": [
      {
        "id": "6915de3f881cbc6041e4c887",
        "udId": "6915de3f881cbc6041e4c887",
        "rateID": "<semantic_rate_id_1>",
        "ratePlanName": "TOU-D"
      },
      {
        "id": "<rate_plan_id_2>",
        "udId": "<rate_plan_id_2>",
        "rateID": "<semantic_rate_id_2>",
        "ratePlanName": "TOU-C"
      },
      {
        "id": "<rate_plan_id_3>",
        "udId": "<rate_plan_id_3>",
        "rateID": "<semantic_rate_id_3>",
        "ratePlanName": "E-6"
      }
    ]
  }
]

The response utilityId is the EIA utility ID. Choose the matching entry from ratePlans, then use that plan’s ratePlans[].id value as ratePlanId when calling the home endpoints. ratePlans[].udId repeats that WattShift plan ID; the companion ratePlans[].rateID field is the semantic normalized tariff identifier for reference and troubleshooting — not an EIA ID and not the value to send as ratePlanId.

2. Create a Home

Create Home with basic details, connecting to the utility, and select a rate plan. [POST] /v1/homes/create

// Request
{
  "name": "Your Home Name",
  "zipcode": "95313",
  "utilityId": "14328",
  "ratePlanId": "<selected ratePlans[].id>",
  "solarSystemSizeKw": 5,
  "isNonNetMetered": false
}

// Response
{ "id": "ws_home_123456789" }

The response field is named id; use that value as the homeId in later requests. For solar homes, the recommended fields are solarSystemSizeKw and isNonNetMetered. When both are present, WattShift creates solar info using standard defaults for module type, array type, efficiency, azimuth, and tilt. If you need to supply the full solar model yourself, use the advanced solarInfo object in the API reference.

3. Add or Update Solar Later (if needed)

If the home already exists, send the same solar fields to Update Home. [POST] /v1/homes/{homeId}/update

// Request
{
  "solarSystemSizeKw": 6.4,
  "isNonNetMetered": true
}

You can also continue to use the dedicated Create Solar endpoint. [POST] /v1/homes/solar/create

// Request
{
  "homeId": "ws_home_123456789",
  "solarSystemSizeKw": 5,
  "isNonNetMetered": false
}

// Response
{ "homeId": "ws_home_123456789" }

4. Get Price Signal Data

See the Price Signal documentation for more details.

Home

Getting Started

Onboard Sites

Optimize Shifts and Calculate Impacts

Advanced Options

Authentication

How to Get a Session Token

Onboarding Flow

Steps to Onboard a Home

1. Fetch Utilities and Rate Plans

2. Create a Home

3. Add or Update Solar Later (if needed)

4. Get Price Signal Data

​Authentication

​How to Get a Session Token

​Onboarding Flow

​Steps to Onboard a Home

​1. Fetch Utilities and Rate Plans

​2. Create a Home

​3. Add or Update Solar Later (if needed)

​4. Get Price Signal Data

Authentication

How to Get a Session Token

Onboarding Flow

Steps to Onboard a Home

1. Fetch Utilities and Rate Plans

2. Create a Home

3. Add or Update Solar Later (if needed)

4. Get Price Signal Data