Recommended homeowner app design
You can use our Enrollment API in order to build a custom VPP management flow within your homeowner 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.
:::
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.
:::
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.