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

# UI-Based Onboarding Flow

> Display our onboarding UI in your app

<script type="text/javascript" id="hs-script-loader" async defer src="//js.hs-scripts.com/46106422.js" />

## Display Onboarding Flow

## Onboarding Flow

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

    User->>Frontend: Clicks "Connect Utility"
    Frontend->>Backend: Request Onboarding URL
    Backend->>WattShift: POST /onboarding/url/generate
    WattShift-->>Backend: Returns URL
    Backend-->>Frontend: Returns URL
    Frontend->>User: Redirects to WattShift URL
    User->>WattShift: Completes Onboarding
    WattShift->>Backend: Redirects to redirectUrl
```

## Generating Onboarding URL

To onboard the user, you will need to redirect them to our onboarding flow.

The following endpoint will generate an onboarding URL for the user–

```typescript theme={null}
async function getWattshiftOnboardingUrl() {
  const { url, homeId } = await wattshiftApiCall(
    "https://api.wattshift.com/v1/onboarding/url/generate",
    {
      userId: "user_123",
      redirectUrl: "https://yourbackend.com/redirecturi",
      enableThirdPartyDevice: false, // set to false if you control your own devices.
      hvacs: [
        {
          name: "Primary thermostat",
          enabled: true,
          defaultMode: "HEAT",
          tempUnits: "F",
          maxTemp: "75",
          minTemp: "65",
          defaultTemp: "70",
          deviceType: "Hvac",
          canHeat: true,
          canCool: false,
          targetTemp: 70,
          currentTemp: 70,
        },
      ],
    },
  );
  return { url, homeId };
}
```

<Note>
  The URL's domain will always be `https://app.wattshift.com` but this endpoint
  will provide a sessionToken that is temporary and tied to your API Key
</Note>

The `userId` is the unique identifier of the user in your system,
which will be used to query the user's data once the onboarding flow is complete.

Your frontend should invoke the onboarding URL in a webview or a new tab.

```javascript theme={null}
const { url } = await getWattshiftOnboardingUrl();
const webview = document.createElement("webview");
webview.src = url;
document.body.appendChild(webview);
```

The user will be then be prompted to onboard onto WattShift and
we will redirect to your redirect URL once the onboarding flow is complete.

## Query Onboarding Status

You can query for the onboarding status with the following url

```bash theme={null}
curl -X POST "https://api.wattshift.com/v1/onboarding/status/get"
     -d '{ "homeId": "ws_home_123456789" }'
      -H "x-ws-api-key: your api key"
```

Now you need to ensure you are responding to optimized schedules sent out by WattShift!