Skip to main content

​
End-User Device Onboarding

We believe the end-user’s primary goal is to take control of their electricity consumption with minimal to no effort. End-users want easy-to-use, safe, and explainable processes to reduce their energy costs. The software should abstract away complexity to only present end-users with vital information that is easy to understand regardless of the end-user’s technical knowledge.
The following workflow achieves the end-user’s goals in the most efficient and frictionless way. Your feedback is very welcome at [email protected].

​
Complete Onboarding Flow

​
Step 1: Instantiate End-User Account

When an end-user opts into your device optimization service (e.g., upon visiting a dedicated subpage of your mobile or web app), trigger the process of creating a new end-user account on the Podero platform. 
curl -X POST \
  'https://app.podero.com/api/partners/v2.0/org/{org_id}/users' \
  -H 'Authorization: Bearer {auth_token}' \
  -H 'Content-Type: application/json' \
  -d '{
    "role": "user",
    "email": "[email protected]",
    "external_user_id": "your_internal_user_id"
  }'
The API returns a unique user_id which you use for subsequent requests for this end-user.

​
Step 2: Create Device Onboarding Session

Create an onboarding session that generates a unique URL for the Whitelabel onboarding form. You can optionally link the device to a building during this step. 
curl -X POST \
  'https://app.podero.com/api/partners/v2.0/device-onboarding' \
  -H 'Authorization: Bearer {auth_token}' \
  -H 'Content-Type: application/json' \
  -d '{
    "language": "en",
    "price_zone_default": "DE",
    "is_smart_optimization_active_default": true,
    "success_url": "https://yourapp.com/success",
    "cancel_url": "https://yourapp.com/cancel",
    "user_id": "{user_id}",
    "building_id": "{building_id}"
  }'

​
Step 3: Whitelabel Onboarding Form - Manufacturer Selection

The form leads the end-user through a device type-specific selection of available manufacturers. The onboarding form will always be up to date since it is maintained by Podero. Device Type Selection
Redirect your user to the authentication_url received in the response to start the onboarding flow.

​
Step 4: Whitelabel Onboarding Form - Connect Device

After selecting their device manufacturer, the end-user is prompted to connect their device. The user journey continues depending on the device manufacturer:

​
Option A: OAuth Redirect

The end-user is redirected to the manufacturer’s authentication webpage (e.g., Nibe myUplink) for secure login. OAuth Authentication Redirect

​
Option B: Generic Login Screen

A generic login screen that calls the manufacturer’s authentication API in the background (e.g., Tesla). Generic Login Screen

​
Option C: Gateway Ordering

The end-user is redirected to the Podero Gateway ordering journey for devices that require a gateway. Gateway Ordering Flow

​
Step 5: Success and Redirect

The end-user sees a success page after completing the onboarding flow and is subsequently redirected back to your application. Onboarding Success The redirect URL will include the device ID as a parameter: 
https://yourapp.com/success?deviceId=8c6efd5a-36d2-4c3d-83a8-b7c9f39242cd
Store this deviceId for future API calls related to this device.

​
Test Credentials

For testing the onboarding flow, you can use these demo credentials:
Please use sparingly to avoid rate limiting the test accounts.
These credentials are only valid for testing and sandbox purposes.

​
Best Practices

  • Keep the onboarding flow embedded within your app’s user journey
  • Provide clear instructions before redirecting to Connect UI
  • Handle success and cancel callbacks gracefully
  • Show loading states during the onboarding process
  • Handle cancel_url redirects (user abandoned onboarding)
  • Implement retry mechanisms for failed device connections
  • Provide user support options if onboarding fails
  • Log onboarding session IDs for debugging
  • Onboarding sessions expire after a certain period
  • Don’t reuse onboarding URLs across multiple users
  • Create a new session for each onboarding attempt

​
Next Steps

Setting Preferences

Configure device-specific preferences

Managing Buildings

Organize devices by location