End-user app design

There are three ways you can enable end-users to manage their participation in VPPs:

In all cases, the site and device need to be commissioned before we can start working with them. Read on about the commissioning process.

Commissioning

Commissioning is how you create the site and device in our systems.

As part of your existing equipment commissioning process, you should add a call to our API to commission the equipment on our servers as well.

To do so, from your cloud, call POST /v1/commission with the site and device info. The response will contain information about which programs the device is eligible to participate in, and, if the device can be automatically enrolled, information about the newly created enrollment.

You do not need to add steps to the installer-facing commissioning flow. You simply need to add a backend process that forward the information you already have to Flip. In addition, note that all site fields are optional for this phase, and any missing information will be collected later.

INFO

About auto enrolling

The ability to auto enroll homeowners in programs is limited to those programs that permit it. In addition, the homeowner should have previously agreed to be enrolled, for instance by agreeing to Terms & Conditions that describe that this may happen.

Option 1: Embed our whitelabel portal

A great compromise between option 1 and 2, this approach lets you embed our pre-built whitelabel portal into your app. So you can control the branding while keeping integration work to a minimum. You do not need to separately commission the site and device with this option.

How it works

We'll give you a unique URL to add as an iframe or WebView into your app. Add the following parameters to log in a specific user:

Name	Description
token	A session token obtained by calling `POST /v1/sessions`

The path will be /auth/session_token. So for example the iframe URL might be https://<your-custom-subdomain>.flip.energy/auth/session_token?token={token}

Available Branding Parameters

The following parameters can be configured to tailor the app's appearance:

alwaysShowBackButton: Determines whether the back button is always visible. By default, the back button is shown on mobile and hidden on desktop. When set to true, the back button is displayed on both mobile and desktop platforms.

faviconFileName: Custom favicon displayed in the browser tab.

fontName: Primary font used throughout the app.

logoFileName: logo displayed in the app header.

primaryButtonBackgroundColor: Background color for primary action buttons.

primaryButtonBorderColor: Border color for primary action buttons.

primaryButtonTextColor: Text color for primary action buttons.

primaryTextColor: Default text color used in the app.

secondaryButtonBackgroundColor: Background color for secondary action buttons.

secondaryButtonBorderColor: Border color for secondary action buttons.

secondaryButtonTextColor: Text color for secondary action buttons.

secondaryTextColor: Secondary text color used in the app.

If you would like to customize any of those, please ask the Flip team.

Option 2: Build it yourself

You can use our Mobile App API in order to build a custom VPP management flow within your monitoring app. We recommend the following design.

TIP

Our API was designed for you to use it as a backend. In this respect, you don't need to copy any of the data we return in your own database.

VPP tab

TIP

From then on, and for all the API endpoints mentioned below, you can use site tokens.

The VPP experience should be self-contained in a dedicated tab. Optionally you may decide to hide the tab if the homeowner does not actively participate in any VPPs and their utility does not offer any.

In order to check if the homeowner is currently enrolled in a VPP, call GET /v1/site/{siteId}/enrollments with the site ID. If the response contains enrollment info, the user is enrolled and you should display the Manage enrollment flow.

If there are no enrollments, you can check for programs. In order to do so, call GET /v1/site/{siteId}/programs with the homeowner's zip code and device type. If the response contains program info, programs are available and you should display the Program enrollment flow.

TIP

During testing, you can use zip codes 88801 and 88802 to fetch test programs. 88803 is an example of no results.

Program enrollment

In this flow, you will want to display a list of the available programs and their descriptions. Allow users to tap on each program to display all their info. At the bottom of the info page, add an Enroll button.

When they tap Enroll, you should call the POST /v1/site/{siteId}/enrollments endpoint with the site, program and appropriate device IDs. The enrollment will be set as PENDING, which could take a few days depending on the program. In the meantime, users should be given an option to cancel their enrollment via DEL /v1/site/{siteId}/enrollments/{id}.

WARNING

Prior to being able to enroll a homeowner, the site info needs to be provided to our system. Ideally, this would be done by the installer in the commissioning phase. If this wasn't done, you will need to give homeowners a way to enter the info manually and then submit it to PATCH /v1/sites/{id}.

Manage enrollment

Once a homeowner has an enrollment in the ACTIVE state, they are officially enrolled in a program. They should be able to do the following:

see past and upcoming events

update their participation in current and upcoming events

unenroll entirely from the program

See past and upcoming events

All events can be found using the GET /v1/site/{siteId}/events endpoint.

Update participation in current and upcoming events

When an event is in the IN_PROGRESS or UPCOMING state, users have the option to change their participation. They can either opt-out of the event, or update their reserve level, just for this event. To do so, use the PATCH /v1/site/{siteId}/event/{id} endpoint. If the event-specific reserve level in unset, it will default to that set by the program first, or otherwise the one set by the user.

Unenroll entirely from the program

If the homeowner decides to, they should be able to unenroll from the program using DEL /v1/site/{siteId}/enrollments/{id}. Note that some programs have minimum time commitments, and therefore unenrollment might fail. Conversedly, they might be able to unenroll, but might be charged a penalty by the utility.

Option 3: Use our standalone whitelabel portal

We've pre-built the entire experience in such a way that you can customize it with your own branding and domain. Logging in users works via oAuth 2.0. Please reach out if you'd like to use this option.

Commissioning#

Option 1: Embed our whitelabel portal#

How it works#

Available Branding Parameters#

Option 2: Build it yourself#

VPP tab#

Program enrollment#

Manage enrollment#

See past and upcoming events#

Update participation in current and upcoming events#

Unenroll entirely from the program#

Option 3: Use our standalone whitelabel portal#