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.

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.