Skip to main content

​
Authentication

Authentication can be done in two different ways. Session tokens are useful for frontend calls, while API keys are useful for backend calls.
  1. API Key: Add your API key in the header x-ws-api-key
    -> { 'x-ws-api-key': '{apiKey}' }
  2. 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

​
Steps to Onboard a Home

​
1. Fetch Utilities and Rate Plans

Fetch all utilities and rate plans for a given zip code. [POST] /v1/utility/get 
// Request
{ "zipcode": "95313" }

// Response
[
  {
    "utilityId": "14328",
    "utilityName": "Pacific Gas & Electric",
    "ratePlans": [
      {
        "id": "6915de3f881cbc6041e4c887",
        "rateID": "<semantic_rate_id_1>",
        "ratePlanName": "TOU-D"
      },
      {
        "id": "<rate_plan_id_2>",
        "rateID": "<semantic_rate_id_2>",
        "ratePlanName": "TOU-C"
      },
      {
        "id": "<rate_plan_id_3>",
        "rateID": "<semantic_rate_id_3>",
        "ratePlanName": "E-6"
      }
    ]
  }
]
Choose the matching entry from ratePlans, then use that plan’s ratePlans[].id value as ratePlanId when calling the home endpoints. The companion ratePlans[].rateID field is the semantic normalized tariff identifier for reference and troubleshooting.

​
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.