​
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" }

​
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",
    "wsRatePlans": [
      {
        "id": "662955dff338bcedec0dbfe7",
        "ratePlanName": "TOU-D"
      },
      {
        "id": "66d811ce52c6fe40859130e8",
        "ratePlanName": "TOU-C"
      },
      {
        "id": "66d811ce52c6fe40859130e8",
        "ratePlanName": "E-6"
      }
    ]
  }
]

​
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": "662955dff338bcedec0dbfe7",

  // Optional fields
  "hasEvCharger": true, // boolean | null | undefined
  "hasElectricHeater": false,
  "hasSmartWaterHeater": null,
  "hasElectricWaterHeater": true,
  "hasAC": true,
  "acType": "central", // central | window | split | other
}

// Response
{ "id": "home_id" }

​
3. Create Solar (if needed)

Provide details about Solar System. [POST] /v1/homes/solar/create

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

// Response
{ "homeId": "home_id" }

​
4. Get Price Signal Data

See the Price Signal documentation for more details.