> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wattshift.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API Based Onboarding

> Onboard homes programmatically

## 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](/api-reference/endpoint/onboarding/generate-session-token) (helpful for frontend calls):
`[POST] /v1/onboarding/session-token/generate`

```json theme={null}
// Response Body
{ "sessionToken": "your_session_token" }
```

***

***

## Onboarding Flow

```mermaid theme={null}
sequenceDiagram
    participant Backend as Your Backend
    participant WattShift as WattShift API

    Backend->>WattShift: POST /utility/get (zipcode)
    WattShift-->>Backend: Returns utilities and ratePlans
    Backend->>WattShift: POST /homes/create (utilityId, ratePlans[].id as ratePlanId)
    WattShift-->>Backend: Returns home ID
    opt Solar System
        Backend->>WattShift: POST /homes/solar/create
        WattShift-->>Backend: Returns success
    end
```

## 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`](/api-reference/endpoint/utility/list-utilities)

```tsx theme={null}
// 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`](/api-reference/endpoint/homes/create-home)

```json theme={null}
// 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`](/api-reference/endpoint/homes/update-home)

```json theme={null}
// Request
{
  "solarSystemSizeKw": 6.4,
  "isNonNetMetered": true
}
```

You can also continue to use the dedicated Create Solar endpoint.
[`[POST] /v1/homes/solar/create`](/api-reference/endpoint/homes/create-solar)

```json theme={null}
// Request
{
  "homeId": "ws_home_123456789",
  "solarSystemSizeKw": 5,
  "isNonNetMetered": false
}

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

### 4. Get Price Signal Data

See the [Price Signal](/docs/optimize_shifts_calculate_impacts/price_signal) documentation for more details.